Sign in

v1

latestOpenAPI 3.1.02026-07-267154122.0 KB
Runs

Get a run (poll for status / final result)

Returns the run object. Works while the run is still running (status: "running" with partial actions[]) and after it terminates. This is the primary read path — every call after POST /agents polls this endpoint until status !== "running".

get/agents/{id}/runs/{runId}

Query parameters

includestring
Example:stats,transcript

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.

Response

The run object

object'run' required
idstring required
agentIdstring uuid required
status'running' | 'completed' | 'needs_input' | 'step_cap_hit' | 'incomplete' | 'cancelled' | 'errored' | 'timed_out' 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.

promptstring 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'origami-lite' | 'origami-max' 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.

startedAtstring date-time required
completedAtstring date-time nullable
workspaceIdstring uuid required

Example response

{
  "todo": {
    "pendingQuestions": [
      {
        "freeformOption": "Or something else"
      }
    ]
  }
}