Runs
A runId is the id POST /api/runs answered.
| Method and path | What it does |
|---|---|
POST /api/runs | Starts a run in the loop’s published version. Body: loop (the public id), and optionally message, and subject for a run your key starts on a user’s behalf. Answers 201 with run and realtime. |
POST /api/runs/batch | Starts up to 25 headless runs at once, for a loop that declares an api trigger. API keys only. Each item carries a payload and may carry a key; a repeated key answers the earlier run. |
GET /api/runs/{runId} | Reads the run: its state, its ending once it has one, and what it is waiting on. |
POST /api/runs/{runId}/messages | Sends text to the run. 202 means recorded; the reply arrives on the realtime channel. A finished run answers 409. |
GET /api/runs/{runId}/transcript | Reads the turns a user saw, newest page first (before pages back). |
POST /api/runs/{runId}/stop | Asks the run to stop. 202 means the request is recorded, not that the run has halted. |
POST /api/runs/{runId}/tool-results | Answers a tool call the run asked your page to make (client_call). |
POST /api/runs/{runId}/tool-confirmations | Confirms or declines an action the run asked the user to confirm (client_confirm). |
POST /api/runs/{runId}/inputs | Answers the form the run asks the user to fill in (inputs_request). Body: its call_id, and values by input id, or declined: true. The values reach no model. One answer per request; a request already answered or lapsed answers 409. |
POST /api/runs/{runId}/verification | The user’s side of an email check (verification_request). Every body carries its call_id. Without code, it sends a code to email, or to the address the user’s identity asserted. With code, it redeems it. A wrong or expired code answers 422 with a sentence the person can read. Neither the address nor the code reaches a model. |
A run the credential cannot reach answers 404, so an id outside it reads as no run at all. A
user token reaches only its own user’s runs in its loop; an API key reaches every run of its
loop. A key without the scope a route needs answers 403, naming the scope.
What a run carries
state is one of running, waiting, done, failed, over_budget or cancelled (and the
earlier draft, estimated, approved). waiting_on says who the run waits on: user,
operator or external. ending says why it ended: completed, over_budget, lapsed,
check_failed, stopped, otherwise or escalated, with end_message in words.
A run carries no cost, token, model or tool fields. Those are yours to read in the console, never your users’.
A run over budget still starts. There is no 402: a run that meets a cap ends with the
over_budget ending.
Following a run
POST /api/runs answers realtime: a WebSocket endpoint, a channel and a token scoped to
that one run, until expires_at. You can also poll GET /api/runs/{runId} and its transcript.