Sessions

A session is one run of an agent on a task. It runs in its own sandbox, pins the agent version and environment it started with, and keeps a transcript you can stream, read, and continue.

You need an agent and an environment. If the environment has a setup script, it must have passed a current setup run. Starting, messaging, and stopping sessions needs the Developer or Admin role; the User role can list and read them. API calls use a key from API keys.

Start a session

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

Console
cURL

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

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:

{
  "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.

All start fields

Field	Required	Description
`agent_id`	Yes	The agent to run. The session pins the agent’s current version at start and reports it as `agent_version_id`. You cannot choose an older version here.
`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`.
`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.
`vault_ids`	No	Vaults to grant. Omit to use the agent’s default vaults. `[]` grants none. See Vaults.
`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.
`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 for metadata search.
`team`	No	`{ "mode": "auto" \| "on" \| "off" }`. Omit to keep the agent’s setting, which is `auto` unless the agent sets another. See Teams.

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.

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.

Console
cURL

Open the session from Sessions. The transcript updates live, and the status badge shows the current state.

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.

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

An interrupted or sleeping session stays active. A loop that waits only for a terminal status keeps waiting until someone sends a message, the wake time arrives, or the session is cancelled.

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.

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` or `sleeping`	Not finished. The session is paused and waits 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.

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 and 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.

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

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53?view=summary' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "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.
`agent_version_id`	The agent version pinned at start.
`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 `max_concurrent_sessions`.
`costUsd`, `costState`	What the whole session tree cost, and whether that is `final` or `so_far`. See Usage and cost.
`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. The full send options, including the delivery states in the response, are in Events.

Console
cURL

Open the session, type in Message the agent…, and click Send. While the agent is working the button reads Queue.

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."}'

{ "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 mid-turn, interrupt instead:

Interrupt stops the current model call and gives a running tool a short grace period to stop. The session waits, with its sandbox, for your next message.
Interrupt and send stops the current turn and starts a new one with your message, in one call.

Interrupt, and interrupt and send

An interrupt stops the current model call right away and gives a running tool a short grace period to stop. If messages are queued, the newest starts a fresh turn. Otherwise the session stays active and goes idle with stop_reason: interrupted, ready for your next message. The sandbox stays up. In the console, click Interrupt under the last event while the agent is working.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/interrupt' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

The response is { "interrupted": true }. A session with nothing running (idle and not sleeping or waiting on its subagents, or already finished) answers 409 conflict, and nothing is recorded. interrupted: false means the stop was recorded but reaching the running work was not confirmed, usually because the run ended as the request arrived.interruptAndSendSessionMessage stops the current turn and starts a fresh one with your message in one call. Send message for plain text, or content for content blocks; content wins if you send both. In the console, type your message and click Interrupt & send, which appears while the agent is working.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/interrupt-and-send' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"message": "Stop. Only cover incidents opened this week."}'

The response has the same shape as a send, with events_accepted: 2: the interrupt and your message.

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.

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

Cancel
Delete

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/cancel' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

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.

Console
cURL

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 a column header to sort the page.

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).

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.
`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.
`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.
`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.
`interrupted`	Someone interrupted or cancelled the run.	Send a message to continue.
`error`	The loop stopped on an error.	Read `failure`.

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.
`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), 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 `max_concurrent_sessions`, 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.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.

Every state transition

From	When	To
Start	The start request is accepted	`provisioning`, or `queued` when the agent is at its `max_concurrent_sessions` 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, or your tenant runs out of credit	`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`
`idle` (`sleeping` or `awaiting_subagents`)	A message, the wake time, or a subagent’s report	`running`
`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 max_concurrent_sessions, 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.
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.

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.
`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.

Limits on metadata, referenced sessions, concurrency, and provisioning are in Limits.

Next steps

Events

Stream, send, and read every kind of session event.

Session operations

Search metadata, inspect compute, ask the analyst, and read the tree.

Files

Give a session input files and download its outputs.

Deliverables and artifacts

Ask for deliverables and see how they’re kept.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Start a session

Watch it work

What success means

Continue the conversation

Send an image

Stop or delete a session

Find sessions

How a session runs

What can go wrong

Next steps

Events

Session operations

Files

Deliverables and artifacts

​Start a session

​Watch it work

​What success means

​Continue the conversation

​Send an image

​Stop or delete a session

​Find sessions

​How a session runs

​What can go wrong

​Next steps

Events

Session operations

Files

Deliverables and artifacts

Start a session

Watch it work

What success means

Continue the conversation

Send an image

Stop or delete a session

Find sessions

How a session runs

What can go wrong

Next steps