# Runs

> Start a run of a published loop, read it, talk to it and follow it

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`). Body: its `call_id` and `approved`, and optionally `note`, the user's words to the run (at most 500 characters). With `reply: true` and a `note`, the user neither confirms nor declines: the action does not run, and the run reads the note and may ask or change its request. |
| `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.
