Request idempotent cancellation

POST

/v1/sessions/{sessionId}/runs/{runId}/cancel

const url = 'https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/runs/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/cancel';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/runs/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/cancel \
  --header 'Authorization: Bearer <token>'

Requires wamp.cloud.runs:cancel. Always returns the current Run plus cancellationAccepted, which says whether this call registered a new cancel command — false means the Run was already terminal or a cancellation was already recorded, and neither is an error, so calling twice is safe. What happens next depends on where the Run is: a queued or awaiting Run is cancelled synchronously and comes back with status: "cancelled" (and its unresolved Interactions expired), while a dispatching or running Run comes back still running with cancellationRequested: true and is stopped asynchronously — watch for wamp.run.cancelled in the event log to know it landed. Cancelling never archives the Session or rolls back files already written.

Authorizations

cloudInstallationBearer

Parameters

Path Parameters

sessionId

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

Example

9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731

A UUID you mint and own; it is the idempotency key for creation and the address of every Turn, artifact and publication underneath

runId

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

Example

9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731

The Run UUID, which is the same value as the id of the Turn that created it

Responses

200

Current Run and whether a new cancellation command was accepted

application/json

object

run

required

One durable execution attempt-set for a Turn. Exactly one Run exists per Turn, it survives worker loss and sandbox replacement, and only one Run per Session may be active at a time.

object

required

Run id, always equal to the id of the Turn that created it

string format: uuid

sessionId

required

Session this Run belongs to

string format: uuid

status

required

queued, dispatching and running are in flight, awaiting means the agent is blocked on human input, and completed, failed, cancelled and crashed are terminal

string

Allowed values: queued dispatching running awaiting completed failed cancelled crashed

attempts

required

How many times a worker has claimed this Run; recovery after a lost worker increments it instead of creating a second Run

integer

cancellationRequested

required

Whether cancellation was durably requested; it stays true after the Run terminates, and it never asserts that an external side effect was undone

boolean

lastError

Coarse machine code for the most recent failure, retained across retries; absent when nothing has failed

object

code

required

string

createdAt

required

When admission committed this Run in queued

string format: date-time

updatedAt

required

Last durable Run state change

string format: date-time

startedAt

When a worker actually began executing; absent while the Run is still queued

string format: date-time

completedAt

When the Run reached a terminal status; absent otherwise

string format: date-time

cancellationAccepted

required

boolean

Example

{
  "run": {
    "id": "c47a1e08-3d6b-4a92-9f15-8b70d2e5c6a4",
    "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
    "status": "running",
    "attempts": 1,
    "cancellationRequested": true,
    "createdAt": "2026-08-12T09:20:31Z",
    "updatedAt": "2026-08-12T09:38:55Z",
    "startedAt": "2026-08-12T09:21:07Z"
  },
  "cancellationAccepted": true
}

404

The resource is missing or inaccessible

application/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object

error

required

Stable machine code

string

requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string

retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer

>= 1

key

additional properties

any

Example

{
  "error": "cloud_session_not_found"
}

502

A retryable workspace, runtime or provider condition

application/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object

error

required

Stable machine code

string

requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string

retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer

>= 1

key

additional properties

any

Example

{
  "error": "cloud_workspace_unavailable"
}

Headers

Retry-After

integer