Browse documentation

Runs

List a run's turn history

Lists the turns of a run, oldest first: the durable conversation record. Requires run:read. Each turn carries the input it was given, its final output, its status and error, the deployment agent_version that executed it, and its timestamps.

Turns are read from records stored with the run, so the history stays available for as long as the run is retained. It does not depend on the technical event log, which follows its own retention and is never read here. A page holds at most limit turns. Continue with next_cursor as after until has_more is false. A cursor only works for the run that issued it: another run's cursor returns 400 with code invalid_cursor.

Turns that are queued or running are included with their current status. Their output is final once they finish. An expired run returns 410 with code run_expired.

GET/runs/{runId}/turns

Authorization

AuthorizationBearer <token>

Path parameters

runIdstringrequired

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

Query parameters

limitinteger

minimum: 1
maximum: 100
default: 20

afterstring

Response

application/json

A page of the run's turns in conversation order.

object

Additional properties are allowed.

objectstringrequired

const: "list"

dataarrayrequired

Show nested schema

Array items

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

has_morebooleanrequired

next_cursorstring | nullrequired

An opaque cursor to pass as after, or null on the last page.

curl --request GET \
  --url 'https://YOUR_SALAMBO_BASE_URL/api/v1/runs/{runId}/turns' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Replace placeholders with your values.

Response

{
  "object": "list",
  "data": [
    {
      "id": "<string>",
      "object": "turn",
      "status": "queued",
      "agent_version": 123,
      "input": [
        {}
      ],
      "output": [
        {
          "type": "<object>",
          "text": "<object>"
        }
      ],
      "created_at": 123,
      "started_at": 123,
      "completed_at": 123,
      "duration_ms": 123,
      "error": null
    }
  ],
  "has_more": true,
  "next_cursor": "<string | null>"
}