Skip to main content
GET
Get a run (poll for status / final result)

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string<uuid>
required
runId
string
required

Run ids are stable text (not UUID) sourced from chat_stream.id. v2-issued ids carry a v2_run- prefix. Use the literal value returned in prior responses.

Pattern: ^[A-Za-z0-9_\\-]{1,128}$

Query Parameters

include
string

CSV-style list of opt-in projections. Recognized tokens:

  • stats — embed table economics on every response.tables[] entry (per-table + per-column).
  • transcript — return the full public transcript on response.transcript. Combine: ?include=stats,transcript. Unknown tokens are ignored.
Example:

"stats,transcript"

Response

The run object

object
string
required
Allowed value: "run"
id
string
required
agentId
string<uuid>
required
status
enum<string>
required

Single discriminator for the run's lifecycle. needs_input means the run completed cleanly but the agent's last assistant message included an ask-questions tool call; answer by sending a follow-up run on the same agent. incomplete means the model finished the step but the AI SDK could not parse a tool call it tried to emit (or it hit the output-token cap mid-tool-call), so the multi-step loop ended without the work being done — recoverable by sending a follow-up run on the same agent. Deploy restarts are auto-followed server-side, so callers never observe a superseded value.

Available options:
running,
completed,
needs_input,
step_cap_hit,
incomplete,
cancelled,
errored,
timed_out
prompt
string
required

The user prompt that drove this run, truncated to 200 characters with an ellipsis when longer. Suitable for a run-history list item; for the full prompt use Get Run.

model
enum<string>
required

Public model id the run actually executed on. When the run has no assistant message yet (still admitting), falls back to the plan default.

Available options:
origami-lite,
origami-max
steps
object
required

Agent step progress. completed is the number of multi-step loop iterations the agent has actually executed; max is the plan-determined hard cap. Once completed === max, the run's status becomes step_cap_hit.

startedAt
string<date-time>
required
workspaceId
string<uuid>
required
request
object
required
response
object | null
required

null while status === "running". Once terminal, an object with the agent's cleaned prose, the structured workspace mutations it performed (actions[]), the full TableObjects for every touched table (tables[]), and (optionally) the full message transcript. tables[] is the resolved version of actions[].tableId — same shape as GET /api/v2/tables/{id}, fanned out server-side. Pass ?include=stats on the Get Run call to attach economics on each embedded TableObject.

todo
object
required
completedAt
string<date-time> | null