> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Start a session, watch it work, and continue, stop, or clean it up.

A session is one run of an agent on a task. It runs in its own sandbox, starts on the agent's current version in the environment you choose, and keeps a transcript you can stream, read, and continue.

> [!NOTE]
>
> You need an [agent](https://docs.labelbox.com/recursion/agents.md) and an [environment](https://docs.labelbox.com/recursion/environments.md). If the environment has a setup script, it must have passed a current setup run. Starting, messaging, moving, and stopping sessions needs the Developer or Admin role; the User role can list and read them, and can read a session's version state. API calls use a key from [API keys](https://docs.labelbox.com/recursion/api-keys.md).

## Start a session

Send the agent, the environment, and the task. Name the files you want back, so the agent saves them as deliverables.

> [tab] Console
>
> 1. In the sidebar, click **Sessions**, then click **Launch session**.
> 2. Under **Configuration**, select an **Agent** and an **Environment**.
> 3. Under **Task**, write the **Opening message**: the task, the deliverables you want by name, and what done looks like.
> 4. Optionally, choose vaults under **Credentials**, a mode under **Team**, and add **Custom metadata**.
> 5. Click **Launch session**.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -H 'Idempotency-Key: weekly-risk-review-2026-09-25' \
>   -d '{
>     "agent_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
>     "environment_id": "4c8e2a61-9b3f-4d70-a5e2-1f6b8c9d0e47",
>     "message": "Review the open incidents and write a risk summary named risks.md.",
>     "metadata": {"customer_id": "acme-042", "run": "weekly"}
>   }'
> ```

The session is accepted right away and starts in the background. The response is `202 Accepted`:

```json theme={"theme":"css-variables"}
{
  "session_id": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
  "status_path": "/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53"
}
```

Keep `session_id`. `202` means the session was accepted, not that it is running. `status_path` is relative to `https://api.recursion.labelbox.com` and already starts with `/managed-agents`, as does the `Location` response header.

The `Idempotency-Key` header is required. Use a value that identifies the work, such as a job id, and send it again on every retry: the same request with the same key returns the same session instead of starting a second one.

> [accordion] All start fields
>
> | Field | Required | Description |
> | - | - | - |
> | `agent_id` | Yes | The agent to run. The session starts on the agent's current version and reports it as `agent_version_id`. You cannot choose an older version here. To change the version later, see [Move a session to another version](#move-a-session-to-another-version). |
> | `environment_id` | Yes | The environment the sandbox is built from. If it has a setup script without a current passing setup run, the request fails with `422 environment_not_verified`. |
> | `message` | No | The opening message: the task and what done looks like. It stays in the agent's context for the whole run, so context compaction cannot summarize it away. A message of only whitespace returns `400`. With neither `message` nor `outcome`, the session is created idle with `stop_reason: awaiting_input` and runs nothing, and costs nothing, until you [send it a message](https://docs.labelbox.com/recursion/events.md). It counts toward your tenant's working root session limit from creation until its first message. |
> | `resources` | No | Up to 500 files to mount read-only in the sandbox before the first turn, as `[{ "type": "file", "file_id" }]`. One unknown file id refuses the whole request with `404`. See [Files](https://docs.labelbox.com/recursion/files.md). |
> | `vault_ids` | No | Vaults to grant. Omit to use the agent's default vaults. `[]` grants none. See [Vaults](https://docs.labelbox.com/recursion/vaults.md). |
> | `credential_refs` | No | `[{ "vault_id", "credential_id" }]`. Narrows access to exactly these credentials across the granted vaults. `[]` with non-empty `vault_ids` is rejected. |
> | `referenced_session_ids` | No | Up to 10 earlier sessions the agent may read. If you cannot read one of them, the request fails with `404` and nothing starts. See [Referenced sessions](https://docs.labelbox.com/recursion/referenced-sessions.md). |
> | `metadata` | No | Your own string key/value pairs, such as a customer id. Up to 32 entries. Keys are up to 64 characters of letters, digits, `_`, `.`, and `-`. Values are 1 to 512 characters without control characters. Set only at start: it's returned on the root session by `getSession` and `listSessions`, you can filter on it, and there is no call to change it. See [Session operations](https://docs.labelbox.com/recursion/session-operations.md) for metadata search. |
> | `outcome` | No | A definition of done for this session, as `{ "description", "rubric" }` with an optional `max_iterations`. The work is graded against the rubric, and the agent keeps revising until the rubric is met or the passes run out. Omit to use the agent's `defaultRubric`, graded against `message`. See [Outcome rubrics](https://docs.labelbox.com/recursion/outcomes.md). |
> | `skip_default_outcome` | No | `true` starts the session ungraded when the agent has a `defaultRubric`. |
> | `team` | No | `{ "mode": "auto" \| "on" \| "off" }`. Omit to keep the agent's setting, which is `auto` unless the agent sets another. See [Teams](https://docs.labelbox.com/recursion/teams.md). |

> [accordion] Retry a start safely
>
> | You send | Result |
> | - | - |
> | No key | `400 invalid_request`. |
> | A key that is empty, longer than 256 characters, has non-visible characters, or is sent more than once | `400 invalid_request`. |
> | The same key, exact HTTP method, escaped path, raw query, and raw body bytes | The original `202` response again, with `Idempotency-Replayed: true`. No second session starts. The first response carries `Idempotency-Replayed: false`. |
> | The same key with any different request-identity bytes | `409 idempotency_conflict`. |
> | The same key while the first request is still being processed | `409 idempotency_in_progress` with `Retry-After`. Wait, then resend the same request byte for byte. |
> | The same key after the first attempt failed with a non-2xx response | The key is released. The retry runs as a new attempt. |
> | The key cannot be checked or reserved | `503 idempotency_unavailable`. The request did not run, so resend the same request with the same key. |
>
> Keys share one namespace across keyed mutations in your organization, so include the operation and work identity. Completed receipts last about 24 hours, pending claims can be reclaimed after about 1 hour, and deduplication is not guaranteed after expiry. The session id is derived deterministically from the durable receipt, so an exact replay returns the same `session_id`. See [Idempotent mutations](https://docs.labelbox.com/recursion/api.md#idempotent-mutations).

## Watch it work

Stream the session's events to follow along as the agent works. The stream replays what already happened, then stays open for new events, and closes when the session reaches a terminal status.

> [tab] Console
>
> Open the session from **Sessions**. The transcript updates live, and the status badge shows the current state.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -N 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events/stream' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

You see the agent's steps as they happen. This output is abridged; each `data` line carries the full event.

```text theme={"theme":"css-variables"}
event: session.status_running
event: agent.tool_use
event: agent.tool_result
event: agent.message
data: {"type":"agent.message","content":[{"type":"text","text":"Found 12 open incidents."}]}
event: agent.artifact
event: session.status_idle
data: {"type":"session.status_idle","stop_reason":"end_turn"}
```

[Events](https://docs.labelbox.com/recursion/events.md) lists every frame type and shows how to resume a dropped stream. To poll instead, read the session with `view=summary` and stop on any terminal status, not only `completed`, and also when the session needs you.

> [!WARNING]
>
> An interrupted or sleeping session stays `active`. An interrupted session waits for Resume or a new message. A sleeping session may also continue at its wake time. A loop that waits only for a terminal status keeps waiting through these pauses.

## What success means

When the agent loop finishes, `status` becomes `completed` whether or not the task succeeded. Read the final message and open the files it saved to judge the work.

To have the work checked against a rubric before the session is done, see [Write outcome rubrics](https://docs.labelbox.com/recursion/outcomes.md).

| You see | Result |
| - | - |
| `status: completed`, `execution_state: idle`, `stop_reason: end_turn` | The agent finished. Check its final message and deliverables against your task. |
| `status: failed` | The session hit an error. Read `failure`. |
| `status: cancelled` | The session was cancelled. Events and deliverables stay readable. |
| `status: active`, `execution_state: idle`, `stop_reason: interrupted` | Stopped until Resume or a new message. Queued inputs stay saved. |
| `status: active`, `execution_state: idle`, `stop_reason: sleeping` | Waiting for a message or its wake time. |
| `status: active`, `execution_state: idle`, `stop_reason: requires_action` | Not finished. The session needs your review before it continues. |
| `status: active`, `execution_state: idle`, `stop_reason: out_of_credit` | Not finished. Your tenant ran out of credit. Buy credits; it continues on its own within about a minute if it paused in the last 72 hours. |
| `status: active`, `execution_state: idle`, `stop_reason: budget_reached` | Not finished. The session reached its budget. Raise the budget to continue. |

When a session fails, `failure` holds `phase`, `code`, `message`, `retryable`, `category`, and `at`. `category` is `transient` (retry), `caller_error` (fix the request or setup), or `internal`.

Deliverables appear in the session's **Files** tab. Files the agent leaves elsewhere stay in `/workspace` for later turns, even after a stopped sandbox is released, and can be used when the workspace reopens successfully, but they aren't captured as deliverables. Deleting the session removes access to its workspace. See [Deliverables and artifacts](https://docs.labelbox.com/recursion/artifacts.md) and [Download session deliverables](https://docs.labelbox.com/recursion/files.md#download-session-deliverables). To give a session input files, attach them in **Launch session**, with `resources` at start, or in the session's **Files** tab while it runs.

> [accordion] Read a session's details
>
> In **Sessions**, click a session. The **Session** tab shows its state, agent, environment, and **Custom metadata**. A session an automation started also shows **Started by**: the **Automation**, the **Trigger** that fired, and the **Run**, each linking back to the automation. See [Automations](https://docs.labelbox.com/recursion/automations.md).
>
> With the API, `view=full` (the default) returns the whole session, including the agent and model snapshots and the resolved configuration. `view=summary` omits `agent_snapshot`, `model_snapshot`, and `config`, which makes polling cheaper. Any other `view` value returns `400`.
>
> ```bash theme={"theme":"css-variables"}
> curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53?view=summary' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```
>
> ```json theme={"theme":"css-variables"}
> {
>   "session_id": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
>   "root_session_id": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
>   "session_path": "/",
>   "kind": "chat",
>   "status": "completed",
>   "execution_state": "idle",
>   "stop_reason": "end_turn",
>   "agent_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
>   "agent_version_id": "9d2f7b1e-6c43-4a85-b0e9-3a7c5d8f2e16",
>   "environment_id": "4c8e2a61-9b3f-4d70-a5e2-1f6b8c9d0e47",
>   "metadata": { "customer_id": "acme-042", "run": "weekly" },
>   "costUsd": "0.418204",
>   "costState": "final",
>   "created_at": "2026-09-25T14:02:11Z",
>   "updated_at": "2026-09-25T14:19:48Z",
>   "last_activity_at": "2026-09-25T14:19:48Z"
> }
> ```
>
> | Field | Description |
> | - | - |
> | `root_session_id`, `parent_session_id`, `session_path` | Where the session sits in its tree. A root has `session_path` `/` and no parent. |
> | `kind` | `chat` for sessions you start, `subagent` for sessions an agent starts, `session_analyst` for the [session analyst](https://docs.labelbox.com/recursion/session-operations.md). |
> | `agent_version_id` | The agent version the session runs. It changes only when you [move the session to another version](#move-a-session-to-another-version). |
> | `metadata` | Set at start. Present on root sessions only. |
> | `wake_at` | When a sleeping session wakes on its own. |
> | `concurrency_slot_held` | Whether the session counts against the agent's `maxConcurrentSessions`. |
> | `costUsd`, `costState` | What the whole session tree cost, and whether that is `final` or `so_far`. See [Usage and cost](https://docs.labelbox.com/recursion/usage-and-cost.md). |
> | `failure` | Present only after a failure. |

## Continue the conversation

Send a follow-up to add to the task or ask for changes. A running session reads it at its next turn. An idle or finished root session picks the work up again, and applies a [version move](#move-a-session-to-another-version) that is waiting before it does. The full send options, including the delivery states in the response, are in [Events](https://docs.labelbox.com/recursion/events.md).

> [tab] Console
>
> Open the session, type in **Message the agent…**, and click **Send**. While the agent is working the button reads **Queue**.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/events' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -d '{"message": "Also add a mitigation for each high-severity item."}'
> ```

```json theme={"theme":"css-variables"}
{ "ok": true, "delivery_state": "resumed", "events_accepted": 1 }
```

Only root sessions resume. A message to a subagent session in a terminal status returns `409 conflict`; message the root session instead.

To change direction immediately, use the same `sendSessionEvents` operation with `interrupt: true`. The console's **Interrupt & send** action does this. The session starts a replacement turn while delegated work continues, and the agent can coordinate any changes that your instruction requires. See [Interrupt and send with the same operation](https://docs.labelbox.com/recursion/events.md#interrupt-and-send-with-the-same-operation) for REST, CLI, SDK, and MCP examples.

### Interrupt and resume

**Interrupt** stops the session without adding a new instruction. It cancels the current model call, gives a running tool a short grace period to stop, and stops delegated work. The session stays `active`, with `execution_state: idle` and `stop_reason: interrupted`. Accepted queued messages remain saved. Helper reports, timers, and board updates do not resume it.

In the console, click **Interrupt** below the latest event. Once the session stops, click **Resume**, or send a new message. Resume continues without adding another message.

> [tab] REST
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/interrupt' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
>
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/resume' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H 'Idempotency-Key: resume-this-session-1'
> ```

> [tab] CLI
>
> ```bash theme={"theme":"css-variables"}
> recursion managed-agents interrupt-session --input-stdin <<'JSON'
> {"sessionId":"e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53"}
> JSON
>
> recursion managed-agents resume-session --input-stdin <<'JSON'
> {"sessionId":"e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53","Idempotency-Key":"resume-this-session-1"}
> JSON
> ```

> [tab] TypeScript
>
> ```typescript theme={"theme":"css-variables"}
> await client.managedAgents.interruptSession({
>   sessionId: "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
> });
> await client.managedAgents.resumeSession({
>   sessionId: "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
>   "Idempotency-Key": "resume-this-session-1",
> });
> ```

> [tab] MCP
>
> Discover each operation with `search_docs` and `read_doc`, then call `write_operation` with the corresponding `operationId` and `arguments`:
>
> ```json theme={"theme":"css-variables"}
> {
>   "operationId": "managedAgentsInterruptSession",
>   "arguments": { "sessionId": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53" }
> }
> ```
>
> ```json theme={"theme":"css-variables"}
> {
>   "operationId": "managedAgentsResumeSession",
>   "arguments": {
>     "sessionId": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
>     "Idempotency-Key": "resume-this-session-1"
>   }
> }
> ```

`resumeSession` returns `resumed` and `deliveryState`. A `stored` delivery state means the resume was accepted but starting work was not confirmed; keep observing the session.

An interrupt acknowledges durable acceptance before all in-flight work has settled. Keep observing the session until it is idle. Resume and a new message still apply the session's normal permissions, budget, and credit checks.

### Send an image

To show the agent a screenshot or chart, attach it to a message. The model sees the image when its model accepts images. In the session's message box, click **Attach image**, choose the image, write your message, and click **Send**. To use an image from your library, click **Attach from Files**. Send PNG, JPEG, or WebP; the type is detected from the bytes. An image the session's image limits refuse returns `400` with the reason. See [Limits](https://docs.labelbox.com/recursion/limits.md).

## Set a budget

A budget is the most a session may spend, counting its subagents. It covers model requests, tools and sandbox compute, at the price your credits pay. When the session reaches it, the session pauses before its next model request. It goes `idle` with `stop_reason: budget_reached`, keeping its work and sandbox. The request in flight when the budget is crossed completes and is charged, so the spend can end slightly over the budget.

> [!NOTE]
>
> Budgets are rolling out. Until they are on for your organization, **Launch session** has no **Budget** section, and the API refuses `budget` and the budget endpoints with `400`.

> [tab] Console
>
> **Launch session** sets a \$10 budget by default. Open **Budget** to pick \$5, \$25, \$50, **No limit**, or another amount. It shows about how long the budget lasts at the agent's typical cost. The session header shows what the session has spent of its budget.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H "Idempotency-Key: $(uuidgen)" \
>   -H 'Content-Type: application/json' \
>   -d '{"agent_id": "…", "environment_id": "…", "message": "Summarize the incidents.", "budget": {"maxCostUsd": "10"}}'
> ```

When the session first reaches 90% of its budget, its agents are told to wrap up, so they can finish cleanly instead of pausing mid-task. The session and each of its subagents get the notice once, with their next model request. Outcome graders aren't told. Each notice is a `user` message in that session's events, so you see it in event lists and the stream. You didn't send it: its `content.metadata.session_budget_nearly_reached` holds `budget_usd` and `warn_at_percent`. The root session also records one `session_status` event with `event_status: "warning"` and `content.metadata.code: "session_budget_nearly_reached"`, with `budget_usd`, `spent_usd`, and `message` beside the code. The event stream sends it as `session.status`. After you raise the budget, the warning comes again at 90% of the new amount.

A session started without a budget through the API has none, unless its agent sets `multiagent.limits.max_tree_cost_usd`. Then the agent's cap is the session's budget. To take that default, leave `budget` out of the request; it is an object, so the API does not accept `null` for it. A budget can be lower than the agent's cap, never higher. A session that reached its agent's cap can't be raised past it: start a new session to continue the work.

To continue a paused session, raise its budget. It continues on its own as soon as the new budget is saved, and the agent is asked to continue the subagents that paused. In the console, click **Raise to … and continue** under the last event. With the API:

```bash theme={"theme":"css-variables"}
curl -X PUT 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/budget' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"maxCostUsd": "20"}'
```

The response is the new budget. It must be more than the session has already spent. Send `DELETE` to the same path to remove the budget, unless the agent sets a cap. While a session is at its budget, a message that would start a new turn returns `403 session_start_not_admitted` with `details.reason: "budget_reached"`. Interrupts still work. A full read of the root session returns `budget.maxCostUsd`, `budget.spentUsd`, and, when the agent sets a cap, `budget.agentCapUsd`. A session bound to a Slack thread (`budget.continuesOnRaise: false`) is continued by the next reply in its Slack thread instead.

## Move a session to another version

A session runs the agent version it started on until you move it. Move it to give work in progress new instructions, tools, skills, or access without starting over: the transcript, sandbox, and files stay.

> [tab] Console
>
> 1. Open the session. When its agent has a newer version, a notice under the header names both, for example "This session runs Version 2 of backend-fixer. The agent is now on Version 3".
> 2. Click **Use Version 3**.
> 3. Read the comparison of the two versions, then click **Use Version 3** to confirm.
>
> The notice changes to "Moving to Version 3" and says when the move applies. Click **Withdraw** to cancel a move that hasn't applied yet. If the move is refused, the notice says why and offers **Try again**.
>
> To move several sessions at once, open the agent and choose the **Sessions** tab. Select the sessions marked **Older version**, click **Use Version 3**, and confirm. To move every live session of an agent, use [Move all of an agent's sessions](#move-all-of-an-agents-sessions).
>
> The console moves a session to its agent's latest version. To move to any other version, including an older one, use the API.

> [tab] cURL
>
> Send the version the session should run with `replaceSessionAgentVersion`:
>
> ```bash theme={"theme":"css-variables"}
> curl -X PUT 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/agent-version' \
>   -H "Authorization: Bearer $RECURSION_API_KEY" \
>   -H 'Content-Type: application/json' \
>   -d '{"agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15"}'
> ```

The request is asynchronous. It records the version to move to and answers at once, whatever the session is doing: the response is `200` with `state: pending`, and `pending` is your receipt. It doesn't interrupt the session, wake it, or start any work. The move applies on its own as soon as it can: right away for a session at rest, and before the next model call for a working one. See [When the move applies](#when-the-move-applies).

```json theme={"theme":"css-variables"}
{
  "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
  "currentAgentVersionId": "9d2f7b1e-6c43-4a85-b0e9-3a7c5d8f2e16",
  "currentVersion": 2,
  "state": "pending",
  "pending": {
    "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
    "version": 3,
    "requestedAt": "2026-09-25T15:04:09Z",
    "requestedByUserId": "usr_01a0867d1b0875be9f9a9938ffb90971"
  },
  "lastFailure": null,
  "latestAgentVersion": {
    "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
    "version": 3
  },
  "members": [
    {
      "sessionId": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
      "name": "",
      "role": "root",
      "adoption": "pending",
      "agentVersionId": "9d2f7b1e-6c43-4a85-b0e9-3a7c5d8f2e16",
      "version": 2
    }
  ]
}
```

The version must belong to the session's agent, and it can be older or newer than the one the session runs. The request needs no `Idempotency-Key`:

* **Repeating a move that is pending, or that the session already applied, changes nothing.** You get the current state back.
* **Repeating a move after it failed asks again.**
* **The later of two different requests wins.**
* **Sending the version the session runs now withdraws a pending move.**

This operation's fields are camelCase. The session itself still reports its version as `agent_version_id`.

> [accordion] Which sessions you can move, and who can move them
>
> * **Root sessions that run an agent.** That includes sessions you start in the console or through the API, and sessions an automation or Slack starts. A subagent session follows its root, so move the root. Sessions the service runs itself, such as the session analyst, stay on the version they started with, and so do pull request review sessions.
> * **Live sessions, and finished ones that can continue.** A session that a follow-up message can start again can be moved. A session that is still stopping, or that can no longer continue, can't.
> * **To any version of the same agent.** A version of another agent returns `404 not_found`.
> * **With create and update access.** A move can give the session the vaults a new session on that version would receive, so it needs both, and reading the state needs read access. The Developer and Admin roles have all three; the User role can read the state and can't move a session. See [Organizations and roles](https://docs.labelbox.com/recursion/organizations-and-roles.md).
> * **Through the API or the MCP server.** An agent that calls the API through the [Recursion MCP server](https://docs.labelbox.com/recursion/ai-coding-agents.md) can move a session with `replaceSessionAgentVersion` and read its state with `getSessionAgentVersion`, with the same access as the API key it uses.

### Check the move

`getSessionAgentVersion` returns the version the session runs, the move that is waiting, the agent's latest version, and how far each agent in the session's tree has followed. The state changes as the session works, so read it again instead of keeping a copy. A subagent session, or a session that wasn't started from an agent, answers `409 conflict`.

In the console, the transcript shows "Now on Version 3" once the session has moved, and the **Session** tab of the details panel shows the version in the **Agent version** row. For a session with subagents or teammates, **Agent version by member** on the same tab lists how far each one has followed.

```bash theme={"theme":"css-variables"}
curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/agent-version' \
  -H "Authorization: Bearer $RECURSION_API_KEY"
```

After the session has moved, the read shows the new version and nothing waiting:

```json theme={"theme":"css-variables"}
{
  "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
  "currentAgentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
  "currentVersion": 3,
  "state": "current",
  "pending": null,
  "lastFailure": null,
  "latestAgentVersion": {
    "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
    "version": 3
  },
  "members": [
    {
      "sessionId": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
      "name": "",
      "role": "root",
      "adoption": "current",
      "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
      "version": 3
    }
  ]
}
```

| `state` | Meaning | What to do |
| - | - | - |
| `current` | The session runs `currentAgentVersionId`. Nothing is waiting. | Nothing. |
| `pending` | A move is recorded and takes effect before the session's next model call. | Nothing. Send a message if the session is finished or you want it to move sooner. |
| `failed` | The last move was refused. The session still runs `currentAgentVersionId`, and `lastFailure` says why. | Fix the cause, then send the request again. |

> [accordion] Response fields
>
> | Field | Description |
> | - | - |
> | `agentVersionId` | The version the session is set to run: the pending version while a move is waiting, otherwise the version it runs now. The only field you send. |
> | `currentAgentVersionId`, `currentVersion` | The version the session runs now, as an id and a number. `currentVersion` is left out when the number can no longer be read. |
> | `state` | `current`, `pending`, or `failed`. |
> | `pending` | The move that is waiting: `agentVersionId`, `version`, `requestedAt`, and `requestedByUserId` when a user asked. `null` when nothing is waiting. |
> | `lastFailure` | Why the most recent move was refused: `agentVersionId`, `version`, `code`, `message`, and `at`. `null` when there is none, and while a newer move is pending. |
> | `latestAgentVersion` | The agent's newest version, as `agentVersionId` and `version`. `null` when the agent was deleted. |
> | `members` | The root session and every open thread in its tree, root first. Each has `sessionId`, `name`, `role`, and `adoption`, with `agentVersionId` when it runs an agent of its own, `version` when that agent is the root's, and `failure` when its move was refused. `name` is the name the thread was given, and is empty for the root. |
>
> | `role` | Where the member's configuration comes from |
> | - | - |
> | `root` | The session itself. |
> | `self` | A copy of its parent's own agent. Teammates are copies of the leader. |
> | `worker` | A thread with no agent of its own. It takes its parent's model and tools. |
> | `roster` | Another agent, named by its parent's roster. |
>
> | `adoption` | Meaning |
> | - | - |
> | `current` | Nothing to adopt. |
> | `pending` | The member is running and adopts before its next model call. |
> | `idle` | The member isn't running. It adopts when it is next given work. |
> | `failed` | The member's move was refused, and it keeps the configuration it had. `failure` says why. |
> | `retained` | The member keeps the configuration it has, because its parent is closed or couldn't adopt, or its roster entry was removed. |
>
> On the root, `adoption` follows `state`: `pending` while a move waits, and `failed` after a refused one.

### When the move applies

A move never cuts into a model call. A working session finishes the call it is making and the tool calls that came from it, then changes version before its next model call. A session at rest changes version in the background within seconds, and stays at rest.

* **A working session** moves before its next model call. A move requested during its last model call applies as soon as the turn ends.
* **A sleeping session** moves right away, in the background, and keeps sleeping. Its scheduled wake doesn't change.
* **A session that finished its turn**, or is waiting for your next message, moves right away and keeps waiting.
* **A session waiting on a tool call's result**, such as an approval, moves before its next model call, once the result arrives. Its tools don't change under a call that is still open.
* **A session whose subagents or teammates are still working** moves once they are done, or before its own next model call if that comes first. They share its sandbox and access, which don't change under them.
* **A cancelled, failed or completed session** moves when you send its next message.
* **A session retrying a failing model call** doesn't change model between retries of the same call. A move to a version with a different model applies before the session's next model call, once the retried call succeeds or you send the session a message. A move that keeps the model can apply at the next retry.

A session that moves while at rest gets everything a working session would: its instructions, model, tools, skills, grants and the notice to the agent are in place before its next turn. Two things wait for that turn:

* **A new model's summary of the earlier conversation** is written before the new model's first call, so nothing calls a model while the session sleeps.
* **Skill files** are copied into the sandbox the next time it's used, so nothing reaches the sandbox before the move is committed.

Moving a session to the version it already runs changes nothing: it doesn't resolve skills or list MCP tools again.

### What changes and what stays

| Follows the new version | Stays as it is |
| - | - |
| System prompt | Transcript and events |
| Model and model settings | Sandbox, `/workspace`, and running processes |
| Tool settings, such as web search, and custom tools | Environment |
| MCP servers, with their tools listed again | Attached files and referenced sessions |
| Skills, resolved again | Custom metadata |
| Granted apps and integrations | Team mode |
| Roster and delegation limits | Cost so far |
| [File history](https://docs.labelbox.com/recursion/agent-file-history.md) setting | |
| Default vaults and credentials. See **Credentials after a move**. | |
| An outcome taken from the agent's default rubric. See **Outcomes after a move**. | An outcome you defined, and one already graded |

The agent receives one notice about the move, a `message` event with `role: system` that you can read in the session's events. It names what changed: that its instructions were replaced, whether the model changed, and the skills, tools, MCP servers, integrations, credentials, and roster agents that were added or removed. It lists names only, never secret values. A skill that kept its name and changed its content is listed as updated, and the agent activates it again before relying on it. A session that hasn't done any work yet gets no notice, because it simply starts on the new version.

When the new version uses a different model, the earlier conversation is summarized for the new model before the session continues. A message the earlier model hadn't read yet stays as you wrote it, and the original events stay in the log.

> [accordion] Credentials after a move
>
> A move carries the new version's default credential changes onto the session:
>
> * **Vaults and credentials the new version adds are added.**
> * **Vaults and credentials the new version removes are removed.**
> * **What the person who launched the session changed is kept.** A vault they added stays, and a credential they unchecked stays out.
>
> Two cases differ:
>
> * **A session whose trigger set its own credentials keeps them.** When Slack or an automation started the session with its own grant, including an empty one, the move leaves that grant alone. The record of the move and the agent's notice both say that the version's defaults changed and the session kept its own.
> * **A session granted whole vaults gains an added vault whole.** A session started with `vault_ids` and no `credential_refs` holds every credential in each vault, so it receives every credential in a vault the new version adds, including any added to that vault later.
>
> A vault or credential the new version names that no longer exists is skipped, and the session's events record a warning.
>
> When each kind of credential takes effect:
>
> | Credential | After the move |
> | - | - |
> | Token for an MCP server | Immediately. An added token is sent from the session's next MCP request, and a removed one is no longer sent. |
> | Granted apps and integrations | At the move. Access is issued for the new version's apps. |
> | Environment-variable secret, added | On the session's next sandbox. A running sandbox doesn't receive it. |
> | Environment-variable secret, removed | Still present in a running sandbox until that sandbox is replaced. Its value stays masked in tool output while it is there, as long as the credential is still in its vault with the same value. |
>
> > [!WARNING]
> >
> > Removing an environment-variable secret from a version doesn't take it out of a sandbox that is already running. To revoke it, rotate the secret at its provider. See [Rotate a credential](https://docs.labelbox.com/recursion/vaults.md#rotate-a-credential).

> [accordion] Outcomes after a move
>
> When the new version changes the agent's `defaultRubric`, a session graded against the old default follows it. This happens before the session's next model call, also for a session that moved at rest:
>
> * **An outcome the session took from the old default is replaced.** It ends with result `interrupted`, and a new outcome with the new version's rubric takes its place, with the same objective. When the new version has no default rubric, the old outcome ends and nothing replaces it.
> * **A session that has never had an outcome gets the new default**, as a new session on that version with the same opening message would. A session started with `skip_default_outcome` stays ungraded.
> * **An outcome you defined stays.** That includes an `outcome` sent at start and one you set later with `defineSessionOutcome`.
> * **A graded outcome stays.** An outcome that has finished is never changed. One that a grader is checking right now is left until that check ends, and is replaced afterwards if it is still open.
>
> An outcome counts as taken from the default when it has no rubric file or evaluator of its own and the session took it from the agent at start. On a session started before the platform recorded where an outcome came from, it counts when its rubric is exactly the old default and its objective is the opening message.

> [accordion] Subagents and teams
>
> Every open thread in the session's tree follows the move before its own next model call, after its parent has followed. A thread that is running finishes its current model call first, and one that isn't running follows when it is next given work. Each receives its own notice.
>
> | Member | After the move |
> | - | - |
> | A copy of its parent's agent, including teammates | Its parent's new configuration in full: prompt, model, skills, tools, MCP servers, and grants. |
> | A general worker with no agent of its own | Its parent's new model, skills, tools, MCP servers, and grants. It keeps the general worker prompt. |
> | A different agent from the roster | What the new roster says. A changed `version` moves it to that version, and an entry without `version` moves it to that agent's latest version. |
> | An agent the new roster no longer lists, or lists under the same name for another agent | Keeps the configuration it has and finishes its work. |
>
> A thread whose parent is closed, or whose parent couldn't adopt, also keeps the configuration it has. `members` reports it as `retained`.
>
> Team mode and seats are fixed when the session starts. A move never adds seats or removes a teammate, and the board keeps its tasks, claims, and notes. Seats can shrink: when the new version's `max_concurrent_threads` is lower than the team size, the team fills only that many seats from then on, and teammates already working stay.

### If a move fails

A move that can't be applied never stops the session. The session keeps the version it has and keeps working, `state` becomes `failed`, and `lastFailure` gives a `code` and one fixed sentence in `message`. Fix the cause and send the request again.

> [accordion] Failure codes
>
> | `code` | Meaning |
> | - | - |
> | `agent_unavailable` | The session's agent no longer exists. |
> | `agent_version_unavailable` | The requested version no longer exists. |
> | `agent_changed` | The agent changed while the session was moving. Send the request again. |
> | `session_not_eligible` | The session can no longer move to another version. |
> | `evaluation_toolset` | The version uses a toolset this kind of session can't run. |
> | `model_not_allowed` | The version's model isn't available to this session. |
> | `model_unavailable` | The version's model couldn't be found. |
> | `model_config_invalid` | The version's model settings aren't valid for its model. |
> | `project_required` | The version's model requires a project, and the session has none. |
> | `configuration_invalid` | The version's configuration can't run in this session. |
> | `temporarily_unavailable` | A temporary problem stopped the move. Send the request again. |
>
> The list can grow, so accept codes that aren't in it.

A temporary problem doesn't fail a move at once. The session tries again before its next model calls, and after three attempts records `temporarily_unavailable`. An MCP server that is new in the version and can't be reached, or that refuses its token, doesn't fail the move either: the session moves without that server's tools and records a warning, as it does at start.

Each move is recorded in the session's events as a `session_status` event:

| Outcome | `event_status` | `content.metadata` |
| - | - | - |
| Moved | `agent_version_changed` | `fromAgentVersionId`, `toAgentVersionId`, `fromVersion`, `toVersion`, `requestId`, `requestedByUserId` when a user asked, a `message`, and `changes`: the names of what was added, updated, and removed. |
| Refused | `warning` | `code` is `agent_version_change_failed`, `reason` is the failure code, and `message` is its sentence, with the same version ids. |
| A thread kept its configuration | `agent_version_changed` | `retained` is `true`. |

A thread's events carry `applyId` in place of `requestId`.

> [accordion] Limits of a move
>
> * **Team mode and seats are fixed at start.** A move doesn't turn team mode on or off, and seats can shrink but never grow.
> * **A running sandbox keeps its environment variables.** Environment-variable secrets, and the network destinations a sandbox may reach for granted integrations, are set when a sandbox is created. A move changes them on the session's next sandbox.
> * **A thread adopts after its parent.** A thread whose parent hasn't followed yet waits for it.
> * **A session doesn't change model between retries of one model call.** While a session retries a failing model call, a move to a version with a different model waits for its next model call, which comes once the retried call succeeds or you send a message.
> * **Moving to the current version does nothing.** It isn't a way to load a newer skill version or list an MCP server's tools again.
> * **The environment never changes.** To use another environment, start a new session.

## Move all of an agent's sessions

After you publish a new version, you can move every live session of the agent to it with one request. Each session moves exactly as [moving one session](#move-a-session-to-another-version) does, and the request runs in the background, so it works the same for five sessions or thousands.

Start the upgrade with `startAgentSessionUpgrade`. It has no body and needs an `Idempotency-Key`:

```bash theme={"theme":"css-variables"}
curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents/7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14/upgrade-sessions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

The response is `202` at once, with a `Location` header that points to the upgrade:

```json theme={"theme":"css-variables"}
{
  "upgradeId": "c4d8f2a1-6b3e-4a97-8e15-2f9b7d3c5a60",
  "agentId": "7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14",
  "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
  "statusUrl": "/managed-agents/v1/agents/7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14/session-upgrade",
  "state": "running",
  "requestedAt": "2026-11-03T15:04:09Z",
  "requestedByUserId": "usr_01a0867d1b0875be9f9a9938ffb90971",
  "finishedAt": null,
  "counts": { "scanned": 0, "requested": 0, "alreadyCurrent": 0, "skipped": 0, "failed": 0 },
  "issues": []
}
```

* **The target is the agent's latest version when the request is accepted.** A version you publish while the upgrade runs isn't picked up; start another upgrade after this one finishes.
* **Every live root session of the agent is asked:** active, queued, idle, and awaiting input. Sessions that can't move are counted as skipped and left as they are. Which sessions those are is in [Which sessions you can move](#move-a-session-to-another-version).
* **One upgrade runs per agent at a time.** Starting another while one runs returns the running upgrade and starts nothing. Upgrades of different agents run side by side.
* **Replays return the original response.** The same `Idempotency-Key` on the same request returns the first `202` again, with `Idempotency-Replayed: true`.
* **It needs create and update access**, like moving one session. An agent of another organization, or one that doesn't exist, returns `404 not_found`, and an agent with no version returns `409 conflict`.

### Follow the upgrade

Read the upgrade with `getAgentSessionUpgrade` until `state` is no longer `running`:

```bash theme={"theme":"css-variables"}
curl 'https://api.recursion.labelbox.com/managed-agents/v1/agents/7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14/session-upgrade' \
  -H "Authorization: Bearer $RECURSION_API_KEY"
```

```json theme={"theme":"css-variables"}
{
  "upgradeId": "c4d8f2a1-6b3e-4a97-8e15-2f9b7d3c5a60",
  "agentId": "7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14",
  "agentVersionId": "5a0c8e37-1f94-4b2d-a6c3-7e9d2b4f8a15",
  "statusUrl": "/managed-agents/v1/agents/7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14/session-upgrade",
  "state": "completed",
  "requestedAt": "2026-11-03T15:04:09Z",
  "requestedByUserId": "usr_01a0867d1b0875be9f9a9938ffb90971",
  "finishedAt": "2026-11-03T15:06:41Z",
  "counts": { "scanned": 1284, "requested": 1203, "alreadyCurrent": 62, "skipped": 19, "failed": 0 },
  "issues": [
    {
      "sessionId": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
      "outcome": "skipped",
      "code": "conflict",
      "message": "pull request review sessions stay on the version they started with"
    }
  ]
}
```

`completed` means every session has been asked, not that every session has moved. Each session applies its move [as a single move does](#when-the-move-applies): sessions at rest move right away without waking, and working sessions before their next model call. Each reports its own progress on `getSessionAgentVersion`. The read returns the agent's newest upgrade, and `404 not_found` when the agent has none or the last one is past retention.

> [accordion] Response fields
>
> | Field | Description |
> | - | - |
> | `upgradeId` | The upgrade. |
> | `agentId` | The agent whose sessions it moves. |
> | `agentVersionId` | The version every session is asked to move to: the agent's latest version when the upgrade was accepted. |
> | `statusUrl` | Where `getAgentSessionUpgrade` reads the upgrade. |
> | `state` | `running`, `completed` (every session in scope has been asked), or `cancelled` (stopped; sessions already asked still move). |
> | `requestedAt`, `requestedByUserId` | When the upgrade was accepted, and who asked. `requestedByUserId` is left out when no user asked. |
> | `finishedAt` | When the upgrade completed or was cancelled. `null` while it runs. |
> | `counts` | Sessions handled so far. `scanned` is the sum of the others. `requested`: now set to the new version. `alreadyCurrent`: running it already, with nothing pending. `skipped`: can't move, and asking again gives the same answer. `failed`: couldn't be asked for a passing reason; a later upgrade asks them again. |
> | `issues` | Up to 50 sessions that were skipped or failed, in the order the upgrade met them, each with `sessionId`, `outcome`, `message`, and usually a `code`. The counts are complete; this list is a sample. Accept `code` values you don't recognize. |

### Stop an upgrade

`cancelAgentSessionUpgrade` stops the agent's running upgrade before it asks any more sessions:

```bash theme={"theme":"css-variables"}
curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents/7b1e4c2a-9d35-4f86-a0c7-5e2d8b3f6a14/session-upgrade/cancel' \
  -H "Authorization: Bearer $RECURSION_API_KEY"
```

The response is the upgrade, as the read returns it. `state` becomes `cancelled` once the batch of sessions in progress finishes. Sessions already asked keep their move; to undo one, [move that session](#move-a-session-to-another-version) back to the version it ran. With no upgrade running for the agent, the request returns `409 conflict`.

All three operations are also tools of the [Recursion MCP server](https://docs.labelbox.com/recursion/ai-coding-agents.md): an agent can start, follow and stop an upgrade with the same access as the API key it uses.

## Stop or delete a session

| Action | What happens | Console |
| - | - | - |
| Cancel | Stops the session now. In-flight work is abandoned, the sandbox is torn down, and the status becomes `cancelled` with `stop_reason: interrupted`. Events and deliverables stay readable, and a follow-up message to a cancelled root session starts it again in a new sandbox. | **Session actions** › **Force stop…** › **Stop now** |
| Delete | Removes the session and all its subagent sessions from lists and reads, stops any running work, and tears down the sandbox. The transcript is retained, not erased. There is no undo. | **Session actions** › **Delete session…** › **Delete** |

> [tab] Cancel
>
> ```bash theme={"theme":"css-variables"}
> curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/cancel' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

> [tab] Delete
>
> ```bash theme={"theme":"css-variables"}
> curl -X DELETE 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

Cancel answers `{ "cancelled": true }` and delete `{ "deleted": true }`. You can cancel any session that is not completed, failed, or already cancelled, including an idle one. The cancel response is the same when the session was already finished, so it is safe to repeat. Sandbox teardown can finish shortly after the response.

## Find sessions

`listSessions` returns sessions in your organization, most recently updated first. Filter by status, kind, agent, agent tags, or your metadata.

> [tab] Console
>
> In the sidebar, click **Sessions**. The **Status**, **Agent**, **Agent tags**, and **Metadata** filters cover every session. The search box matches id, agent, state, or metadata on the page shown; paste a full session id to find a session on any page. Click the **ID**, **Status**, **Created**, or **Last activity** header to sort the whole list, not just the page shown.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions?status=failed&metadata=customer_id:acme-042&root_only=true&limit=50' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

`root_only=true` returns one row per run, without the subagent sessions under it. List rows are summaries: they leave out snapshots, `config` is empty, and token totals aren't included. Each row carries the session tree's `costUsd` and `costState` (see [Usage and cost](https://docs.labelbox.com/recursion/usage-and-cost.md)).

> [accordion] List parameters and paging
>
> | Parameter | Description |
> | - | - |
> | `status` | One status, such as `failed`. |
> | `kind` | Comma-separated kinds, matched as OR: `chat`, `subagent`, `session_analyst`. Analyst sessions appear only when you name `session_analyst`. |
> | `agent_id` | Sessions of one agent. |
> | `tag_ids` | Comma-separated agent tag ids, up to 32. A session matches only if its agent currently has every tag. An unknown tag id returns `404`. |
> | `metadata` | `key:value`, repeatable up to 32 times. All pairs must match. The value is everything after the first colon. Child sessions of a matching root also match, so add `root_only=true` for one row per run. |
> | `metadata_key` | A key that must be present, repeatable up to 32 times. |
> | `root_only` | `true` returns root sessions only. |
> | `limit` | Page size. Default 100, maximum 1000. Larger values are reduced to 1000. |
> | `page_token` | The `next_page_token` from the previous page. |
>
> A page token is valid for one hour and only with the same filters and `limit`. Changing either returns `400 invalid_request`; start again without a token. Because the list is ordered by last update, a session that changes while you page can appear twice or be skipped. Deduplicate by `session_id`, or filter on a value that does not change.

## How a session runs

Two fields describe a session. `status` says whether it's still live. While it's `active`, `execution_state` says what the agent loop is doing. When the loop isn't running, `stop_reason` says why.

| `stop_reason` | Meaning | What to do |
| - | - | - |
| `end_turn` | The agent finished its turn with nothing left to do. | Read the final message and deliverables. |
| `requires_action` | The session was stopped for review after failing the same way repeatedly, or it is waiting on a browser hand-off (`status: awaiting_human`). | After a review stop, fix what blocked it, then reply to continue. |
| `awaiting_input` | The session was created without a `message` or `outcome` and has not been given one. Nothing has run and nothing is billed. | Send the first message. |
| `sleeping` | The agent chose to wait. The session stays `active`. | Nothing, or send a message to wake it before `wake_at`. |
| `awaiting_subagents` | A coordinator is waiting for subagents to report back. | Nothing. See [Multi-agent sessions](https://docs.labelbox.com/recursion/multi-agent.md). |
| `out_of_credit` | Your tenant ran out of credit. The session paused before its next model request. Requests already in flight for the tenant complete and are charged, so the balance can end slightly below zero. Its subagents pause the same way. | Buy credits. A session paused in the last 72 hours continues on its own within about a minute, subagents included; send a message to continue it sooner or after that. See [Billing](https://docs.labelbox.com/recursion/billing.md#when-credits-run-out). |
| `tenant_suspended` | Your account is suspended. The session paused without finalizing its work. | Contact support to restore the account, then send a message to continue. |
| `budget_reached` | The session reached its [budget](#set-a-budget) and paused before its next model request. Its subagents pause the same way. | Raise the budget with `PUT /managed-agents/v1/sessions/{sessionId}/budget`; the session continues on its own. A session bound to a Slack thread continues on your next reply there. |
| `interrupted` | Someone interrupted or cancelled the run. | Resume an interrupted session, or send a message to continue. |
| `error` | The loop stopped on an error. | Read `failure`. |

> [accordion] Statuses and execution states
>
> | `status` | Meaning |
> | - | - |
> | `active` | The session is live. Check `execution_state` for what it is doing. |
> | `completed` | The agent loop finished. This does not by itself mean the task succeeded. See [What success means](#what-success-means). |
> | `failed` | The session stopped on an error. The `failure` object explains it. |
> | `cancelled` | Someone cancelled the session. Its sandbox is torn down. |
> | `awaiting_human` | The agent asked a person to handle a step in its browser display, such as a sign-in, which can happen only when the environment has computer use on. `active_handoff` describes the request. The agent resumes when you send a `handoff_resolved` event (see [Events](https://docs.labelbox.com/recursion/events.md)), or on its own when the hand-off deadline passes: 30 minutes unless the agent set another, at most 4 hours. Interrupting or cancelling the session also ends the hand-off. `execution_state` is `idle` with `stop_reason: requires_action`. |
>
> | `execution_state` | Meaning |
> | - | - |
> | `provisioning` | The sandbox is starting. This normally takes under a minute. After 5 minutes the session fails with `sandbox_provision_timeout`. |
> | `queued` | Waiting for a free slot under the agent's `maxConcurrentSessions`, or for sandbox capacity. |
> | `running` | The agent is working. |
> | `idle` | The loop is not running. `stop_reason` is always set. |
>
> `provisioning`, `queued`, `running`, and `idle` are execution states of a session whose `status` is `active`. `completed`, `failed`, and `cancelled` are terminal statuses: the session does not change on its own after reaching one. A follow-up message to a root session in a terminal status starts it again from `provisioning`, or from `queued` when the agent is at its cap. After a cancel, the session gets a new sandbox. After a completed or failed run, the sandbox is reused when possible.
>
> Agents already know when their previous run was cut short and when a resumed run starts on a new sandbox. A run is cut short when it fails partway through, is cancelled, or stops unexpectedly. The session's events then hold a message with `role` `system`, which you didn't send. It says how the run ended, including the error. A run that failed before its first step, such as during setup, gets no such message.
>
> When a root session is stopped for review and no subagent is working, its sandbox is stopped with `/workspace` preserved, and restored from `/workspace` before the agent's next tool call; processes it started are gone. A session whose setup ran on its own compute keeps its sandbox until the environment's idle stop.

> [accordion] Every state transition
>
> | From | When | To |
> | - | - | - |
> | Start | The start request is accepted | `provisioning`, or `queued` when the agent is at its `maxConcurrentSessions` cap |
> | Start | The start request carries neither `message` nor `outcome` | `idle` (`awaiting_input`) |
> | `idle` (`awaiting_input`) | The first message | `provisioning`, or `queued` when the agent is at its `maxConcurrentSessions` cap |
> | `queued` | A slot or sandbox capacity frees up | `provisioning` |
> | `provisioning` | The sandbox is ready | `running` |
> | `provisioning` | No sandbox capacity is free yet | `queued` |
> | `provisioning` | The sandbox isn't ready within 5 minutes | `failed` |
> | `running` | The run is interrupted, the agent sleeps or waits for subagents, the session is stopped for review, your tenant runs out of credit, or the session reaches its budget | `idle`, with a `stop_reason` |
> | `running` | The agent finishes its work | `completed` |
> | `running` | The agent asks a person for a browser hand-off | `awaiting_human` |
> | `running` | An unrecoverable error | `failed` |
> | `running` | A message arrives after the run stopped unexpectedly | `provisioning`, or `queued` at the cap |
> | `idle` (`sleeping` or `awaiting_subagents`) | A message, the wake time, a subagent's report, or a notice that every subagent it's waiting on has gone silent | `running` |
> | `idle` (`awaiting_subagents`) | Every subagent it was waiting on turns out to have finished or closed already, and `multiagent.interventionist.mode` is `shadow` or `off`, so there is no notice to read | `completed` |
> | `idle` (any other `stop_reason`) | A follow-up message | `provisioning`, or `queued` at the cap |
> | `awaiting_human` | A `handoff_resolved` event or the hand-off deadline | `running` |
> | Any live state | Cancel | `cancelled` |
> | `completed`, `failed`, `cancelled` | A follow-up message to a root session | `provisioning`, or `queued` at the cap |

## What can go wrong

The most common problems:

* **The session stays `queued`.** The agent is at `maxConcurrentSessions`, or a slot freed while your tenant was out of credit. A queued session starts only when a slot is free and credit is available. Wait, cancel other sessions, raise the agent limit, or add credits.
* **`422 environment_not_verified` on start.** The environment's setup script has not passed a current setup run. Run environment setup, then start again. See [Environments](https://docs.labelbox.com/recursion/environments.md).
* **A version move stays `pending`.** A move applies before the session's next model call, and a finished or sleeping session makes none until it gets a message or wakes. Send a message. See [When the move applies](#when-the-move-applies).
* **`status: completed` but the task is not done.** The loop finishing does not mean the task succeeded. Read the final message, then send a follow-up with what is missing.

> [accordion] Every session error
>
> | Symptom or code | Cause | Fix |
> | - | - | - |
> | `400 invalid_request` on `Idempotency-Key` | The header is missing, malformed, or sent twice. | Send exactly one key of 1 to 256 visible characters. |
> | `409 idempotency_conflict` | The key was used for a different request. | Use a new key for different work. |
> | `409 idempotency_in_progress` | The first request with this key is still running. | Wait for `Retry-After`, then retry with the same key. |
> | `404 not_found` on start | An agent, environment, vault, or referenced session is missing or not visible to you. | Check each id and your access. |
> | `400 invalid_request` on `metadata` | Too many entries, a bad key, or an empty or too-long value. | Keep to 32 entries and the key and value rules in **All start fields**. |
> | `400 invalid_request` on `page_token` | The token expired or the filters changed. | List again without a token. |
> | The session stays `provisioning`, then fails with `sandbox_provision_timeout` | The sandbox did not start within 5 minutes. | Start again. If it repeats, check the environment. |
> | A poller never returns | The session is interrupted or sleeping and stays `active`. | Stop on `idle` states you care about, or send a message. |
> | `409 conflict` when messaging or deleting | A cancel is still finishing. | Retry after a few seconds. |
> | `409 conflict` when messaging a subagent | Subagent sessions in a terminal status do not resume. | Message the root session. |
> | `404 not_found` when moving a session | The session or the version is missing, deleted, or not visible to you, or the version belongs to another agent. Any `agentVersionId` that isn't a version of the session's agent answers this, including a value that isn't an id at all. | Send a version of the session's own agent. |
> | `409 conflict` on `session_id` when moving a session | The session is a subagent session, a session the service runs itself, a pull request review session, or one that is still stopping or can no longer continue. A session whose agent was deleted has no other version to move to. | Move the root session. A session that can't continue can't be moved. |
> | `409 conflict` on `session_id` when reading a session's version state | The session is a subagent session, or it wasn't started from an agent. | Read the root session. A session that wasn't started from an agent has no version to read. |
> | `409 conflict` on `agentVersionId` | The version uses a toolset a running session can't adopt. | Send another version. |
> | `409 conflict` with `details.retryable: true` when moving a session | Other requests kept changing the session's pending move while yours was recorded. | Send the request again. |
> | `400 invalid_request` on `agentVersionId` | The field is missing or empty, or the version's model runs only for a named project and the session has none. | Send one version id from `listAgentVersions`. |
> | `400 invalid_request` on `model` when moving a session | The version's model isn't available to this session. | Send a version whose model the session can run. |
> | `403 forbidden` when moving a session | Your role or key doesn't have both create and update access. | Use the Developer or Admin role. |
> | A move stays `pending` | The session hasn't made its next model call yet: it is finished or sleeping, or it is retrying a failing model call and the version changes the model. | Send the session a message, or wait for the retried call to succeed. |
> | A move shows `failed` | The version can't run in this session. The session keeps its earlier version. | Read `lastFailure`, fix the cause, and send the request again. |
> | `429 rate_limit_exceeded` | Too many requests. | Wait for `Retry-After`. Retry only when the operation's retry strategy in **Endpoints** permits replay. |
>
> Every error is a flat object with required `code` and `message` fields and optional `details`, which can include `field`, `requestId`, and `retryable`. See [Errors](https://docs.labelbox.com/recursion/errors.md).

Limits on metadata, referenced sessions, concurrency, and provisioning are in [Limits](https://docs.labelbox.com/recursion/limits.md).

## Next steps

> [card] [Events](https://docs.labelbox.com/recursion/events.md)
>
> Stream, send, and read every kind of session event.

> [card] [Session operations](https://docs.labelbox.com/recursion/session-operations.md)
>
> Search metadata, inspect compute, ask the analyst, and read the tree.

> [card] [Files](https://docs.labelbox.com/recursion/files.md)
>
> Give a session input files and download its outputs.

> [card] [Deliverables and artifacts](https://docs.labelbox.com/recursion/artifacts.md)
>
> Ask for deliverables and see how they're kept.
