Cancel a call
Cancel queued work or request a stop, then follow confirmation.
Content reviewed · Maintained by Cleo Powered · Report a documentation issue · Verification basis
/v1/calls/{call_id}/cancelParameters
- Name
call_id- Location
- Path · required
- Description
- The UUID returned when the call was created.
- Name
Authorization- Location
- Header · required
- Description
Bearer <API_KEY>, from the same Agent Project as the call.
| Name | Location | Description |
|---|---|---|
call_id | Path · required | The UUID returned when the call was created. |
Authorization | Header · required | Bearer <API_KEY>, from the same Agent Project as the call. |
No request body or idempotency key is needed for this operation.
Example request
For cURL, use Bash and set these variables in the same terminal. CALL_ID is the call UUID returned by create, not the idempotency key. The Python tab prompts for both inputs itself.
read -rsp "Cleo API key: " CLEO_API_KEY; echo
export CLEO_API_KEY
read -rp "Call ID returned by create: " CALL_ID
export CALL_IDcurl --fail-with-body -X POST \
"https://api.cleolabs.com/v1/calls/$CALL_ID/cancel" \
-H "Authorization: Bearer $CLEO_API_KEY" \
-H "User-Agent: CleoDocs/1.0"Response
Returns 200 OK with the call object. If the call does not exist or belongs to a different Agent Project, the API returns 404 call_not_found.
A job still queued before dispatch is cancelled locally. If dispatch may have started, the response shows execution.stage: "cancel_requested" while Cleo requests the external stop. Protected disclosure authority is revoked immediately, but a 200 response is not itself confirmation that the phone has hung up.
Continue reading or syncing the same call until call state is terminal. If it has already finished, cancellation returns the existing terminal state. A natural completion can race cancellation; report the confirmed outcome. If execution.error_code becomes reconciliation_required, contact the service operator while preserving the same ID.
Closing your terminal or stopping polling does not cancel work. A cancellation timeout does not prove the request failed. Preserve the call ID and recover its state instead of creating a replacement call.