Runs

Poll the durable agent turn. Postgres is the source of truth.

GET /api/v1/chats/{chatId}/runs/{runId}

Send and completion return before the model finishes. Poll this route. The public snapshot does not include a realtime token.

Status

QUEUED → THINKING → WORKING → WAITING or STOPPING → COMPLETE, FAILED, or CANCELLED.

status · string

Terminal values are COMPLETE, FAILED, and CANCELLED.

currentStep · string

What the loop is doing now. Null when idle.

progressPercent · integer

Coarse progress, 0–100.

tools · object[]

Each tool call: toolCallId, toolName, status (PENDING, RUNNING, SUCCESS, FAILED, CANCELLED), and errorMessage.

waitpoint · object

Present while the turn is paused. type is PLAN, CREDIT, MEDIA, or OPTIONS. An unanswered waitpoint expires on read so a stale overlay does not stick. timeoutAt is when it expires.

assistant · object

Assistant message so far: id, status, and contentBlocks (text, thinking, tool use, tool result, assets).

errorCode · string

Set when the turn failed. Pair with errorMessage.

errorMessage · string

Safe message you can show. Partial text and successful tool results stay on the snapshot.

Credit exhaustion stops the turn safely. Completed tool work stays on the snapshot. The run ends FAILED rather than dropping the chat.

Poll with bounded backoff. If a request fails on the network, retry the same GET. The snapshot is the reconciliation point. Do not send a new message until the status is terminal, or you will get 409 RUN_ACTIVE.