Concepts

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.

View .md

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.

04Each is the same kind of session

Your serveran org API keyThe consolea teammate, signed inThe terminalthe rush CLIRush APIapi.prix.devone routeSESSIONharnessclaudestatusrunningstarted_bywhoever started itrecordtranscript, result
Scene. Three ways to start a run, one API behind them, the same session at the end.

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.

06Or it stops

STARTINGqueuedallocatingWORKINGrunningTURN ENDEDcompletedpausedinput_requiredneeds_reviewSTOPPEDfailedcancellingcancelledexpiredfailed: The run stopped on an error.
Scene. A session's status, lane by lane. The values are the spec's SessionStatus.

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.

08Kept 7 days after it last parks

YouRush APISandboxPOST /o/{org}/sessionsallocateeventstool_usetool_resultthinkingdone$0 parked…/messageswakedone7 days, thenexpiredstatuspausedcompute$0 while parkedturn 2
Scene. One session across two turns: who sends what, what the sandbox does, and when compute is billed.

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 covers each.