Browse documentation

Runs

Retrieve a run

Retrieves one retained run and a selected turn. Requires run:read. Without turn_id, the latest turn is selected.

The turn carries the input, output, status, error and agent_version that executed it. These are durable run data, stored with the run for as long as it is retained, and they do not depend on the run's events. An expired run returns 410 with code run_expired.

GET/runs/{runId}

Authorization

AuthorizationBearer <token>

Path parameters

runIdstringrequired

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

Query parameters

turn_idstring

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

Response

application/json

Run object

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 GET \
  --url 'https://YOUR_SALAMBO_BASE_URL/api/v1/runs/{runId}' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Replace placeholders with your values.

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
  }
}