Browse documentation

Runs

Cancel active or queued work

Cancels one turn: the active turn, or the queued turn selected with turn_id. Other queued turns are separate work. Requires run:write.

An active turn returns 202 and is cancelling until the runtime stops the work, cleans up its resources and settles it as cancelled.
A queued turn is cancelled immediately and returns 200.
A turn that has already finished returns 200 with the result it settled with. A completed, failed or incomplete turn is never relabelled cancelled.
An idle run without turn_id has nothing to stop and returns 200 with its latest turn, unchanged.

An accepted cancellation is durable. Recording its events or notifying the runtime can fail without rejecting the request; repeating it with the same Idempotency-Key repeats those steps. A repeated request always refers to the turn it first selected.

POST/runs/{runId}/cancel

Authorization

AuthorizationBearer <token>

Path parameters

runIdstringrequired

pattern: "^run_[A-Za-z0-9]+$"

Headers

Idempotency-Keystringrequired

minLength: 1
maxLength: 255

Body

application/json

object

Additional properties are not allowed.

turn_idstring

pattern: "^turn_[A-Za-z0-9]+$"

Response

application/json

The selected turn was queued and is now cancelled, or it had already finished and is returned as it settled.

object

Additional properties are allowed.

idstringrequired

pattern: "^run_[A-Za-z0-9]+$"

objectstringrequired

const: "run"

agent_idstringrequired

pattern: "^agt_[A-Za-z0-9]+$"

agent_versionintegerrequired

The deployment version that executes the returned turn. It equals turn.agent_version.

minimum: 1

statestringrequired

enum: ["idle","busy"]

dispositionstringrequired

enum: ["created_run","created_turn","queued_turn","steered"]

tagsarrayrequired

The run's tags, sorted, without repeats. A run has at most 20.

maxItems: 20
uniqueItems: true

Show nested schema

Array items

string

A free-form label of 1 to 64 characters, stored exactly as sent. It is case-sensitive and nothing is trimmed. It may not be only whitespace or contain a control character.

minLength: 1
maxLength: 64
pattern: "^(?![ \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000]+$)[^\\u0000-\\u001f\\u007f-\\u009f]+$"

turnobjectrequired

Additional properties are allowed.

Show nested schema

idstringrequired

pattern: "^turn_[A-Za-z0-9]+$"

objectstringrequired

const: "turn"

agent_versionintegerrequired

The deployment version of the agent that executes this turn. It is pinned when the turn is admitted and never changes, so it still names the version that ran after the agent's active version moves on. A run can hold turns on different versions.

minimum: 1

statusstringrequired

completed, failed, cancelled and incomplete are final. completed returns its complete result and no error. failed is described by error. cancelled has empty output and no error. incomplete keeps the partial output it produced, and error explains why it stopped when the runtime reported a reason (otherwise null). cancelling means a cancellation was accepted and the runtime is cleaning up.

enum: ["queued","in_progress","cancelling","completed","failed","cancelled","incomplete"]

inputarrayrequired

Show nested schema

Array items

object

Additional properties are allowed.

outputarrayrequired

Show nested schema

Array items

union

Exactly one of

object1

object

Additional properties are allowed.

typestringrequired

const: "output_text"

textstringrequired

object2

object

Additional properties are allowed.

typestringrequired

const: "output_file"

file_idstringrequired

filenamestringrequired

media_typestringrequired

created_atintegerrequired

minimum: 0

started_atinteger | nullrequired

minimum: 0

completed_atinteger | nullrequired

minimum: 0

duration_msinteger | nullrequired

minimum: 0

errorunionrequired

Why a failed turn stopped (always present), or why an incomplete turn stopped when the runtime reported a reason (otherwise null). null for every other status. It is stored with the turn and stays available regardless of event retention.

Show nested schema

Exactly one of

null1

null

object2

object

The structured reason a turn stopped by error. code is a stable machine-readable reason and new codes can be added. retryable says whether sending the same work again can succeed. reference identifies the failure for support.

Additional properties are allowed.

codestringrequired

sourcestringrequired

enum: ["provider","extension","runtime","platform","configuration"]

messagestringrequired

retryablebooleanrequired

referencestringrequired

curl --request POST \
  --url 'https://YOUR_SALAMBO_BASE_URL/api/v1/runs/{runId}/cancel' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: YOUR_IDEMPOTENCY_KEY' \
  --header 'Content-Type: application/json' \
  --data '@request.json'

Replace placeholders before running. JSON templates without a sample body read your payload from request.json.

Response

{
  "id": "<string>",
  "object": "run",
  "agent_id": "<string>",
  "agent_version": 123,
  "state": "idle",
  "disposition": "created_run",
  "tags": [
    "<string>"
  ],
  "turn": {
    "id": "<string>",
    "object": "turn",
    "agent_version": 123,
    "status": "queued",
    "input": [
      {}
    ],
    "output": [
      {
        "type": "output_text",
        "text": "<string>"
      }
    ],
    "created_at": 123,
    "started_at": 123,
    "completed_at": 123,
    "duration_ms": 123,
    "error": null
  }
}