Stop or cancel a call
Hang up a live call, or cancel a scheduled one that has not dialled yet.
Hang up a live call, or cancel a scheduled one that has not dialled yet.
Two outcomes, deliberately given different status codes:
200 — cancelled before dial. The call was still scheduled. Nothing was ever placed, nobody was rung, and no minutes are billed.
202 — hangup requested. The call is live and the hangup has been sent to
the telephony provider. This is a 202 and not a 200 on purpose: the
provider's hangup is best-effort, and the stored status flips to a terminal
value whether or not the audio actually stopped. Treat it as "requested",
and confirm with GET /v2/calls/{execution_id}.
409 covers the three states where stopping is not possible, each with its
own message: the call already ended; it has been dialled but has not yet
reported a leg to hang up (retry in a moment — Retry-After: 2); or the
provider refused the hangup.
Rate limit: 600 requests per minute per organization (bucket calls.create). Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/calls/{execution_id}/stopAuthorization
AuthorizationRequiredBearer <token>
Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.
In: header
Request Body
application/jsonOptionalreasonReason | null
Free-text reason recorded alongside the hangup request.
200Path Parameters
execution_idRequiredExecution Id
The call's id, as returned by POST /v2/calls or GET /v2/calls.
Query Parameters
organization_idOrganization Id
Optional. Must equal your key's organization.
Response Body
200
Scheduled call cancelled before dialling.
execution_idRequiredExecution Id
The call that was cancelled.
statusRequiredStatus
Always "canceled" — call statuses spell it with one l, unlike the batch status "cancelled".
canceled_before_dialCanceled Before Dial
Always true here: nobody was rung and no minutes are billed.
truescheduled_atScheduled At | null
The start time that will now never fire.
202
Hangup requested for a live call.
execution_idRequiredExecution Id
The call a hangup was sent for.
statusRequiredStatus
Always "stopped".
requested_atRequested At | null
When the hangup was sent.
reasonReason | null
The reason you supplied, or user_request.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
403
1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
404
1200 — no such resource in your organization. A resource belonging to another organization answers 404, never 403.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
409
1201 — the resource's current state does not allow this action.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
503
1501 — a service this endpoint depends on is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
504
1502 — a service this endpoint depends on did not answer in time.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
Scheduled call cancelled before dialling.