Cancel an agent run
POST/api/agents/:agent_id/cancellations
Request cooperative cancellation of the durable agent run identified by run_id in the JSON body. Requires ownership, current agent access, and the agents.run scope. Sending a cancellation signal does not itself change an active run from RUNNING; poll GET run for the final state. Paused runs become CANCELLED without resuming execution. Repeated requests and requests for terminal runs return the current snapshot. Completion may win a race with cancellation. Completed tool side effects cannot be undone, and external work may continue if a tool does not support cancellation. Cancellation targets this run, not separate background-subagent executions. An active run without a cancellation registration returns 409. Cancellation signaling requires Redis. An interrupted active run can instead become FAILED through deadline cleanup; this does not verify that external tool work has stopped.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 408
- 409
- 413
- 429
- 500
- 503
Current run snapshot after requesting cancellation, or an unchanged terminal run.
Invalid request (malformed JSON, invalid parameter values, unknown fields).
Missing or invalid authentication token.
Token valid but lacks permission for the requested operation.
Resource not found.
Backend did not respond within the timeout window.
Request conflicts with current state of the resource.
Request body exceeds the maximum allowed size.
Rate limit exceeded. Includes Retry-After header.
Unexpected server-side failure.
Backend temporarily unavailable.