API reference

Turns

GET /v1/agents/turns/{turnId}, and the turn's trajectory.

Reads the result of one turn. Every POST /message returns a turnId: the turn the message started, or the running turn it joined. See Structured output for the options that make a turn return typed output.

Authenticate with the same API key as the rest of /v1/agents.

Get a turn

GET /v1/agents/turns/{turnId}

Answers at once. Poll it until status is succeeded or failed; every 2 to 5 seconds is enough.

json

{
  "turnId": "turn_vzjz62w7j7jvOilZ6zBL",
  "sessionId": "cs_02JAB",
  "machineId": "m_7f2a",
  "status": "failed",
  "output": null,
  "reason_code": "output_invalid",
  "raw_answer": "I found two invoices for September: INV-1043 and INV-1051. The totals were not shown on the list page.",
  "usage": { "inputTokens": 48210, "outputTokens": 1630 },
  "recordTrajectory": false,
  "trajectory": {
    "recorded": false,
    "url": "/v1/agents/turns/turn_vzjz62w7j7jvOilZ6zBL/trajectory"
  },
  "evidence": [],
  "output_errors": ["/invoices/0 must have required property 'total'"],
  "template": "Sign in to the {{vendor}} portal and list the invoices dated in {{month}}.",
  "inputs": { "vendor": "Acme", "month": "September 2026" }
}

Field	Notes
`turnId`	The turn.
`sessionId`	The session the message landed in. `null` until it is delivered.
`machineId`	The computer.
`status`	`running`, `needs_input`, `finalizing`, `succeeded` or `failed`. See Status.
`output`	With `output_schema`: an object that matches it. Without: Sai's final answer, a string. `null` until `succeeded`.
`reason_code`	Set when `failed`: `agent_error`, `machine_unavailable`, `not_started`, and for a structured message `output_invalid`, `criteria_not_met` or `criteria_unchecked`.
`raw_answer`	Only when `failed`: Sai's final answer (`output_invalid`), or a short explanation.
`error_code`	Only for a known `agent_error`: `insufficient_credits` or `free_computer_time_exhausted`.
`usage`	`{ inputTokens, outputTokens }` of Sai's model calls in the turn. `null` until the turn ends.
`recordTrajectory`	Whether the turn records its steps.
`trajectory`	`{ recorded, url }`: whether any step was stored, and where to read them.
`evidence`	Structured messages only. One entry per check: `{ id, passed, score?, evidence? }`. A string `success_criteria` gives one entry without `id` or `score`.
`output_errors`	Structured messages only, with `output_invalid`: why the last attempt did not match the schema.
`template`, `inputs`	Structured messages only: the message as sent, before `{{name}}` was filled, and its values.

The structured fields are extra fields on the same object, so code written for plain messages reads a structured turn unchanged.

Trajectory

Requires options.recordTrajectory: true on the message that started the turn.

GET /v1/agents/turns/{turnId}/trajectory

json

{
  "turnId": "turn_vzjz62w7j7jvOilZ6zBL",
  "trajectory": {
    "recorded": true,
    "url": "/v1/agents/turns/turn_vzjz62w7j7jvOilZ6zBL/trajectory"
  },
  "steps": [
    {
      "index": 0,
      "timestamp": "2026-10-10T18:02:11.204Z",
      "title": "Open the Acme portal sign-in page",
      "rationale": "The task starts at the portal, so I open its sign-in page first.",
      "code": "await machine.browser.newtab('https://portal.acme.example/login')",
      "screenshot": "/v1/agents/turns/turn_vzjz62w7j7jvOilZ6zBL/trajectory/screenshots/0"
    },
    {
      "index": 7,
      "final": true,
      "timestamp": "2026-10-10T18:04:52.880Z",
      "screenshot": "/v1/agents/turns/turn_vzjz62w7j7jvOilZ6zBL/trajectory/screenshots/7"
    }
  ]
}

Field	Notes
`index`	Step number, from 0.
`final`	`true` on the last entry: the screen when the turn ended.
`title`	Sai's one-line title for the step.
`rationale`	Sai's reason for the step.
`code`	The code Sai ran.
`error`	Present when the step failed.
`screenshot`	Path of the screen before the step, or `null`. Fetch it with your key.

steps is empty for a turn without recordTrajectory. At most 500 steps are listed.

Screenshot

GET /v1/agents/turns/{turnId}/trajectory/screenshots/{index}

Returns the JPEG (Content-Type: image/jpeg).

Errors

Status	Body
`404`	`{ "error": "turn_not_found", "message": "No turn with this id on your account." }`. Also for another account's turn, and for a screenshot that does not exist.

Gotchas

finalizing is not done. Keep polling until succeeded or failed.
status: succeeded without output_schema or success_criteria only means Sai finished with an answer. Read output.
A message sent while Sai was busy (queued: true) joined the running turn, so its turnId is that turn's and so is the result.
A later message in the same session never changes a finished turn.