# Runs and sessions

A session is one agent run. It moves through a fixed set of statuses, takes follow-ups between turns and keeps its sandbox while it is parked.

A **session** is one agent run: one request, one sandbox, one record. The API calls it a session
(`POST /o/{org}/sessions`); the console and the CLI call it a run. They are the same thing.

A session is made of **turns**. Your request starts the first turn. Each follow-up you send after a
turn ends starts the next one, in the same sandbox, with everything the agent did before still on
its disk.

_Figure: who starts a run, on the page at /docs/concepts/runs-and-sessions._
## Statuses

A session's `status` moves left to right through the values below. The live stream sends a
`status` event on every change, `GET /o/{org}/sessions/{session}` reads the current one, and the
end of a turn reaches your webhook.

_Figure: lifecycle, on the page at /docs/concepts/runs-and-sessions._
Three of them ask something of you:

- `input_required`: the agent stopped to ask a question. Answer it with a follow-up.
- `needs_review`: the turn ended, but the proof is missing or incomplete, for example a pull request
  whose checks did not pass. A run never reports `completed` without its proof.
- `failed`: the turn could not finish. `error` on the session says why, as a typed code.

## Turns and follow-ups

A follow-up is `POST /o/{org}/sessions/{session}/messages` with the next instruction. It continues
the same session: the same sandbox, the same files, the same branch.

With an API key, send it once the turn has ended. While a turn is still running, a key's
follow-up is refused with `409 TURN_ACTIVE`, so wait for `status` to leave `running`, or for the
stream's `done` event. From the console or the CLI, a text-only message sent mid-turn queues (up to
20) and is delivered when the turn ends; one with files waits for the turn to end.

## Parked sandboxes

When a turn ends, the sandbox **parks**: its disk and its memory are kept, and it costs nothing
while it is parked. A follow-up wakes it where it left off, with its processes and files intact.

_Figure: life of a session, on the page at /docs/concepts/runs-and-sessions._
A parked sandbox is kept for 7 days after it last parked. The clock starts again each time it parks, so a
session you keep using never expires. After 7 idle days the sandbox is removed and the session ends
`expired`; its record stays readable.

## What a session carries

Read a session with `GET /o/{org}/sessions/{session}`. Besides `status`, it carries the agent's
last answer in `result`, the `branch` and `pr_url` when it opened a pull request, the files it saved
in `artifacts`, and its usage: `turns_count`, `tool_calls_count`, the token counts and
`total_cost_usd`. [Results and proof](/docs/concepts/results-and-proof) covers each.