harness_commit is the exact commit of the harness this run executed — the tip of
main when the run was created. It is the tree itself, and it is what the run is
reproducible from.
Status
waiting is the state a run sits in when it has raised a request for human input;
answering it is what lets the run go on — see Interactions.
Cancelling is idempotent, and a run already in a terminal state comes back
unchanged.
A run that reaches its agent’s max_iterations while the model is still calling
tools ends there rather than continuing. That cap is a field on the agent; the
starter’s agents set it to 1000.
What a run leaves behind
Messages — the conversation
Messages — the conversation
Each message has a role and a list of content parts:
text, json, or file
with a URL. A tool call and its result are messages too, which is why a turn can
be replayed exactly as it happened.Outputs — the results, separate from the chatter
Outputs — the results, separate from the chatter
An output is
{ id, run_id, type, name, value, created_at } with type either
result or artifact. This is where a run puts the thing it was asked for, so a
caller does not have to parse it out of prose.Events — the ordered record
Events — the ordered record
Every event carries
sequence, type, created_at and a data object:hook.fallback is the one to know: it says a hook of yours did not answer, names
the point, says what the hook did instead of answering, and says how old the
replayed answer is. Read events live over SSE or as durable pages; see
Streaming.The tree — the run and its descendants
The tree — the run and its descendants
GET /v2/runs/{run_id}/tree returns { root_run_id, runs, generated_at }, where
each entry is a run plus its depth and its child_run_ids. A sub-agent run is a
run in a chat of its own, parented to the caller’s — the tree is how you see the
whole piece of work rather than the one conversation you were watching.Usage — what it cost
Usage — what it cost
GET /v2/runs/{run_id}/usage answers with these, and they include the run’s
descendants:integer
Uncached prompt tokens only. An agent run reuses a large cached prefix, so this
alone understates what the run read.
integer
integer
integer
integer
input + output + cache read + cache write. The whole picture.
integer
integer
string
A non-negative decimal amount as a string, never a JSON floating-point number.
string
Three uppercase letters.
boolean
A turn of a chat is a run
In the app you see the same object from the other side. Under a finished turn is the model it ran on, when it ran, how long it took and how fast it generated:
A finished turn: the tool calls it made, and the footer of the run behind it
Runs from your own code
POST /v2/runs carries an idempotency key; retrying with the same key and
body returns the same run rather than starting a second one. Pass a chat_id to
continue a conversation instead of starting one.
Runs API
Creating, listing, cancelling, and reading every one of these surfaces.
Streaming
Events over SSE, reconnection, and the terminal event.