Browse documentation

Runs

Retrieve one turn of a run

Retrieves one turn from the run's durable turn history: the same record that listRunTurns returns. Requires run:read. Unlike getRun, it returns the turn itself rather than the run around it, and it never reads the technical event log. An expired run returns 410 with code run_expired.

GET/runs/{runId}/turns/{turnId}

Authorization

AuthorizationBearer <token>

Path parameters

runIdstringrequired

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

turnIdstringrequired

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

Response

application/json

The turn record.

object

One turn of a run's durable conversation. It holds what the turn was given, its final output, the deployment version that executed it and, when it stopped by error, why. It says nothing about technical events, which follow their own retention.

Additional properties are allowed.

idstringrequired

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

objectstringrequired

const: "turn"

statusstringrequired

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

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

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 or incomplete turn stopped, and null for every other status.

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}/turns/{turnId}' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Replace placeholders with your values.

Response

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