Skip to main content
GET
Get the task's structured output

Authorizations

Authorization
string
header
required

Workspace API key issued from the web app. Pass as Authorization: Bearer YOUR_API_KEY.

Path Parameters

task_id
string<uuid>
required

UUID of the task.

Query Parameters

include_citations
boolean
default:false

true returns each value with the place in the source document it was read from, plus a documents block resolving those files.

Two separate switches, deliberately: Keep citations (structured_output_citations) on the agent decides whether citations are produced; this parameter decides whether they are returned. So turning the agent setting on for the dashboard never changes the bytes an existing API consumer already parses.

Off (the default), every leaf is a plain value, whether or not the agent keeps citations. On, a leaf that has provenance becomes {"value": ..., "bounding_boxes": [...]}; leaves with no document source (a value from a database lookup, say) stay plain. Asking an agent that keeps no citations is not an error — the payload comes back unchanged and documents is omitted.

Prefer normalized_bounding_box (0–1, origin top-left) when drawing: bounding_box is absolute pixels and needs the page dimensions from documents. Spreadsheet and text sources carry sheet/cell or line_start/line_end instead of a box.

Response

Task metadata plus the structured output, when one is available.

task_id
string<uuid>
required
agent_id
string<uuid>
required
status
enum<string>
required

Lifecycle status of a task.

  • pending — created, not yet picked up
  • queued — held back by admission control (agent at concurrent-task limit)
  • running — being processed by the worker
  • waiting_for_input — agent called ask_user; reply with POST /tasks/{id}/message
  • awaiting_review — agent is paused for human approval of a sensitive step
  • completed — terminal: finished successfully
  • failed — terminal: errored out
  • stopped — terminal: cancelled by a user or system
Available options:
pending,
queued,
running,
waiting_for_input,
awaiting_review,
completed,
failed,
stopped
created_at
string<date-time>
required
updated_at
string<date-time>
required
title
string | null
structured_response
any

The run's output against its schema. Leaves are plain values unless include_citations=true, in which case a leaf with provenance becomes { "value": ..., "bounding_boxes": [...] }.

Key filtering rides along with citations rather than being universal: include_citations=true also drops the platform's internal keys (__-prefixed, plus _meta on a cited leaf). The default path unwraps leaves and filters nothing, so an internal key a run happened to write reaches you unchanged. Read the keys your schema declares rather than assuming the object holds only those.

Omitted when no output is available — read message / error to tell "not yet" from "never".

documents
object[]

The source files this response's citations name, so a value can be drawn on the page it came from. Present only with include_citations=true on a run that produced citations.

message
string

Set when the run is still in flight, so the output may yet appear. Poll again.

error
string

Set when no output can ever arrive for this task — no output schema is configured, or the run reached a terminal state without writing one.