Request cancellation of a run
Requires scope
run:manageAsks a pending, running or paused run to stop. Takes no request body.
The answer is always 200 — read the body to learn what happened:
{"status":"cancelling","cancelled":true}— cancellation was REQUESTED, not completed. A running step is executing inside a worker process, so the request is a flag the executor picks up; the run unwinds and settles ascancelledshortly after. PollGET /api/runs/{id}untilstatusis terminal. (Apendingrun is settled immediately even though the response still sayscancelling.){"status":"cancelled","cancelled":true}— apausedrun, which has no executor to unwind, was settled synchronously.{"status":"<settled status>","cancelled":false}— the run was ALREADY terminal; nothing was done and the reported status is the one it already had. This is not an error, so do not retry.
Cancellation is signalled through Redis. If Redis is not configured the call is refused with 503.
Authorization
bearerAuth AuthorizationBearer <token>
An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.
In: header
Path Parameters
id*string
The run id (UUID).
Format
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "cancelling", "cancelled": true }}