Skip to main content
POST
Request a run's cancellation
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

A request, not a rollback

Cancellation was requested. The run reports cancellation_requested until in-flight work drains, then cancelled (or failed if the drain could not finish). A legacy run that no orchestrator drives has nothing to drain: it ends cancelled at once and the answer’s status says so. Effects already performed are not rolled back: a step that already sent a message, wrote a record or called another system stays done. Forge stops dispatching new nodes, stops a running agent before its next tool call, and stops the run’s sandboxes. A step already waiting for a person’s response is in-flight work: the run stays cancellation_requested until that step is answered or times out. A node parked behind a governance hold has not started, so it does not delay cancellation. Poll GET /api/v2/runs/get for the final status. The body is exactly { "id": "<runId>", "reason": "<optional, at most 1,000 characters>" }; any other field is a 400. reason is recorded on the run. Concurrent requests for the same run answer one accepted and the rest already_requested.

Who may cancel a run

The run is decided at the run’s home: its own org unit when it records one (a trigger launch), else its workflow’s owning org unit.
  • A run you cannot read — you need runs:read at its home and at every company it carries — answers 404 like a missing run.
  • A run you can read but whose home you do not hold runs:manage at answers 403 with requiredPermission: "runs:manage".
Who launched the run is never authority. A same-key retry returns the recorded answer only while both still hold; otherwise it answers 409 idempotency_result_unavailable, and the run is never cancelled twice (see Idempotency).

Resume was retired

POST /api/v2/runs/resume was removed. It resumed delegated runs, whose dispatch was removed, so every call answered 500. A workflow run held for a person continues on its own after an eligible person approves; read GET /api/v2/runs/getTrustStatus for its continuation. Restarting a failed run and retrying a notification need runs:manage.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

runId
string
required
Minimum string length: 1

Body

application/json

id is the run's id. reason, at most 1,000 characters, is recorded on the run as the cancel reason.

reason
string
Maximum string length: 1000

Response

Cancellation requested, or the run's unchanged status

data
object
required

accepted: this request moved the run to cancellation_requested; poll GET /api/v2/runs/get until it reports cancelled (or failed if the drain could not finish). A legacy run that no orchestrator drives has nothing to drain and is already cancelled. already_requested and already_terminal: nothing changed, and status is the run's current status. Effects already performed are not rolled back.

meta
object
required