POST /chat starts a run that the platform carries out in the background, so the work does not depend on your HTTP connection staying open.
The durable-run model
POST /chat creates the run and gives you its run_id. Two form fields decide what the first response looks like:
For a run that is still going, there are three ways to get the result:
- Poll
GET /runs/{run_id}until the status is final. See Poll a run. - Stream
GET /runs/{run_id}/stream(Server-Sent Events). See Streaming. - Pass
callback_urlonPOST /chatand receive a POST when the run ends or pauses. See Webhooks.
A dropped connection never cancels a run. Whether you stream, poll or disconnect, the run finishes, its result is saved and it is billed once. Reattach at any time with the
run_id.Start a run: POST /chat
Send the body asmultipart/form-data.
Form fields
A rejected file answers with an
error field instead of detail: 400 for too many files or a file type that is not supported (the answer lists the supported types), 413 for a file or a request that is too large.
202: the run handle
You get a run handle forwait=false, and in observe mode when the run outlives the window (it is still queued, running or awaiting_input):
interruptslists the pending requests for a person. It is empty unless the run isawaiting_input.enqueued_followupis set when your message was held behind an active run withon_conflict=enqueue.
queued handle and starts as soon as it can. A run that still cannot start after several attempts ends failed, with the reason in its error.
200: the completed result
Whenwait=true and the run finishes within the window, the response is the agent’s answer: the same object as the result field of GET /runs/{run_id}, plus agent_id and usage_status. The answer text is in its result field, and the sources it used, if any, in documents.
- A run cancelled within the window returns
200with{"run_id", "status": "cancelled", "agent_id"}. - A run that failed or timed out within the window returns
500with the run’s error indetail.
Poll a run
GET /runs/{run_id} returns the run. Poll while the status is queued or running. Stop when it is final. When it is awaiting_input, act on it instead of polling: see Pauses for a person.
The call answers
404 when the run does not exist and 403 when it is outside your key’s scope.
A finished run is not removed after a fixed time. It stays readable until its conversation or the owning account is deleted, or until your organization’s retention setting removes it. After that the call answers 404.
List a conversation’s runs
GET /chats/{chat_id}/runs returns the conversation’s 20 most recent runs. Add active=true to get only the run that is queued, running or awaiting_input, to reattach to a turn in progress.
Idempotency
A network retry ofPOST /chat could start a second run, and bill it. Send a stable idempotency_key and a retry reattaches to the original run instead.
- Derive the key from the unit of work, such as a request id or an order number. A new random value on each attempt defeats the purpose.
- An idempotency key belongs to the person the API key acts for (its creator) in their organization. The same string sent by someone else starts a separate run. Two API keys made by the same person share their idempotency keys.
- A matching
idempotency_keyreattaches to your own existing run instead of conflicting with it.
One active run per conversation
Achat_id has at most one active run (queued, running or awaiting_input) at a time. Posting to a busy conversation answers 409 with the run that holds it:
- If the active run is
awaiting_inputon a question from the agent, your message is the answer. It resumes that run instead of conflicting. - With
on_conflict=enqueue, the message is held on the active run and started as its own turn as soon as that run ends. The response is the active run’s handle withenqueued_followupset. Up to 5 messages can be held per run; past that you get the409. - Otherwise you get the
409. Attach toactive_run_id(poll or stream it) and send again once it ends.
POST /runs/{run_id}/followups with {"message": "…"}. It answers 409 when the run is no longer active or already holds 5 messages; send the message normally then. The held message becomes a new run, so the checks a new run passes apply when you send it: on SaaS a frozen account answers 403 and used-up usage 429.
To work in parallel, use separate chat_ids, within your concurrency limits.
Pauses for a person
An agent can stop in the middle of a run to wait for a person. The run’s status becomesawaiting_input, and interrupts lists what is pending. Each interrupt has an interrupt_id, a kind and a payload with what the agent asked. How you continue depends on the kind.
clarification: the agent asked a question. Send your answer to POST /chat as the next message, with the same chat_id. The run continues.
browser_handoff: the agent needs a person in its browser, for example to sign in to a site. Do what it asks in the web app’s Browser tab, then resume the run, with an optional note for the agent. Replying with POST /chat also resumes it, with your message as the note.
resumesmust answer exactly the pending interrupt ids. A partial or different set answers409withResume must decide exactly the pending interrupts: […].- A second submission, or a resume that loses to a cancel, answers
409withRun is not awaiting input or a decision was already recorded. decided_by(optional) records who answered when a key relays someone else’s decision. A signed-in person always decides as themselves.- On success the run goes back to
queuedand continues. On SaaS a resume counts against your concurrency limits again, so it can answer429.
failed, with Human input request expired before a decision was recorded. Work done before the pause is billed.
Cancel a run
- A
queuedorawaiting_inputrun stops at once. - A
runningrun finishes the step it is on, then becomescancelled. - A finished run is left as it is.
GET /runs/{run_id}/audit lists who did what to a run (created, cancelled, resumed), with the same access rule as reading the run.
Run status
Any active run can be cancelled. Time limits count active work only: a paused run accrues no time, and an
awaiting_input run does not count against the concurrency limits.