Sessions

A session is one run of an agent against a task. It pins the agent version and environment at start, runs in its own sandbox, and keeps a transcript you can read, stream, and resume. The TypeScript samples assume the rl client from Client setup.

Before you begin

You need the organization developer or admin role to start, message, interrupt, cancel, or delete sessions. The organization user role can list and read sessions. The billing role cannot see sessions. See Organizations and roles.
For API calls, create a key under API keys. See API keys.
You need an agent and an environment. If the environment has a setup script, that script must have passed a current setup run.

How a session runs

Every session has two fields that change as it runs. status says whether the session is still live. execution_state says what the agent loop is doing right now. When the loop is not running, stop_reason says why. provisioning, queued, running, and idle are execution states of a session whose status is active. completed, failed, and cancelled are statuses. They are terminal: 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. After a cancel, the session gets a new sandbox. After a completed or failed run, the sandbox is reused when possible.

`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`.
`running`	The agent is working.
`idle`	The loop is not running. `stop_reason` is always set.
`completed`	A grader verified that the outcome was met. Always paired with `stop_reason: outcome_satisfied`.

`stop_reason`	Meaning	What to do
`end_turn`	The agent finished its turn with nothing left to do. Not a success signal on its own.	Read the final message and deliverables.
`outcome_satisfied`	The grader accepted the work.	Nothing. This is success.
`outcome_unmet`	The grader declined the work.	Read the outcome evaluation, then send guidance to try again.
`max_iterations`	The grader loop hit its revision limit.	Send guidance, or define a new outcome with a higher `max_iterations` or a refined rubric, then resume.
`grader_failed`	The grader produced no usable verdict. The work is ungraded.	Send a follow-up message to retry.
`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. For a hand-off, see `awaiting_human` above.
`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.
`interrupted`	Someone interrupted or cancelled the run.	Send a message to continue.
`error`	The loop stopped on an error.	Read `failure`.

Start a session

Console
TypeScript
cURL

In the sidebar, click Sessions, then click Launch session.
Under Agent, select an agent and an Environment.
Under Task, write the Opening message. To grade the run, turn on Grade this session against a rubric and enter a Rubric.
Optionally, choose vaults under Credential access, a mode under Team, and add Custom metadata.
Click Launch session.

const started = await rl.managedAgents.startSession({
  'Idempotency-Key': 'weekly-risk-review-2026-09-25',
  body: {
    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.',
    outcome: {
      description: 'risks.md lists every open incident with an owner and a severity.',
      rubric: '- risks.md lists every open incident.\n- Each incident has an owner and a severity.',
      max_iterations: 3,
    },
    metadata: { customer_id: 'acme-042', run: 'weekly' },
  },
});
const sessionId = started.session_id;

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.",
    "outcome": {
      "description": "risks.md lists every open incident with an owner and a severity.",
      "rubric": "- risks.md lists every open incident.\n- Each incident has an owner and a severity.",
      "max_iterations": 3
    },
    "metadata": {"customer_id": "acme-042", "run": "weekly"}
  }'

The response is 202 Accepted:

{
  "session_id": "e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53",
  "status_path": "/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53"
}

202 means the session was accepted, not that it is running. Use session_id with Get a session or stream its events. status_path is relative to https://api.recursion.labelbox.com/managed-agents. The Location response header carries the full path under /managed-agents/v1/.

Request 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. It stays in the agent’s context for the whole run. A grader never sees it, so put success criteria in `outcome`.
`outcome`	No	What the grader checks: `description` and `rubric` (both required), `max_iterations` (`0` or omitted means revise until satisfied), and `grader_model_ref_id` (defaults to the session’s model). If omitted, the agent’s default rubric applies. See Outcomes.
`skip_default_outcome`	No	`true` runs without the agent’s default rubric.
`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. Metadata is fixed once the session starts.
`team`	No	`{ "mode": "auto" \| "on" \| "off" }`. Omit to keep the agent’s setting, which is `auto` unless the agent sets another. See Teams.

Metadata can only be set at start. It is returned on the root session by getSession and listSessions, and you can filter on it. There is no call to change it later. See Session operations for metadata search.

Retry a start safely

startSession requires an Idempotency-Key header. Use a value that identifies the work, such as a job id, and reuse it on every retry of that start.

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 and the exact same request	The original `202` response again, with the header `Idempotency-Replayed: true`. No second session starts. The first response carries `Idempotency-Replayed: false`.
The same key with a different body, path, or query	`409 idempotency_conflict`.
The same key while the first request is still being processed	`409 idempotency_in_progress` with `Retry-After`. Wait and retry.
The same key after the first attempt failed with a non-2xx response	The key is released. The retry runs as a new attempt.

Keys are shared across your whole organization, so include something unique to the caller. A key is remembered for about 24 hours. After that, the same key may start a new session. The session id is derived from the key, so a replay always returns the same session_id.

What success means

When the agent loop finishes, status becomes completed whether or not the task succeeded. Read execution_state and stop_reason to know the result.

You see	Result
`status: completed`, `execution_state: completed`, `stop_reason: outcome_satisfied`	Success. The grader verified the outcome.
`status: completed`, `execution_state: idle`, `stop_reason: end_turn`	The agent finished without a grader. Check its final message and deliverables.
`status: completed`, `execution_state: idle`, `stop_reason: outcome_unmet`, `max_iterations`, or `grader_failed`	The run finished but the outcome was not verified. Resume with guidance or refine the outcome.
`status: failed`	The session hit an error. Read `failure`.
`status: cancelled`	The session was cancelled. Events and outcomes 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.

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.

Wait for a session to finish

Stream the session’s events for live progress; the stream closes when the session reaches a terminal status. See Stream events. To poll instead, stop on any terminal status, not only completed, and also stop when the session needs you.

Console
TypeScript
cURL

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

const terminal = new Set(['completed', 'failed', 'cancelled']);
let session = await rl.managedAgents.getSession({ session_id: sessionId, view: 'summary' });
while (
  !terminal.has(session.status) &&
  session.stop_reason !== 'requires_action'
) {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  session = await rl.managedAgents.getSession({ session_id: sessionId, view: 'summary' });
}
const succeeded = session.stop_reason === 'outcome_satisfied';

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

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.

Get a session

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.

Console
TypeScript
cURL

In Sessions, click a session. The Session tab shows its state, agent, environment, and Custom metadata.

const session = await rl.managedAgents.getSession({
  session_id: 'e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53',
  view: 'summary',
});

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": "completed",
  "stop_reason": "outcome_satisfied",
  "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" },
  "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`.
`failure`	Present only after a failure.

List sessions

listSessions returns sessions in your organization, most recently updated first.

Console
TypeScript
cURL

In the sidebar, click Sessions. Filter with Status, Agent, Agent tags, and Metadata, or search by id, agent, state, or metadata.

const page = await rl.managedAgents.listSessions({
  status: 'failed',
  agent_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38',
  metadata: ['customer_id:acme-042'],
  root_only: true,
  limit: 50,
});
const next = page.next_page_token
  ? await rl.managedAgents.listSessions({
      status: 'failed',
      agent_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38',
      metadata: ['customer_id:acme-042'],
      root_only: true,
      limit: 50,
      page_token: page.next_page_token,
    })
  : undefined;

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"

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. List rows are summaries. They leave out snapshots, and config is empty. Token and cost totals are not included; see Usage and cost.

Send a follow-up message

A message to a running session is read at its next turn. A message to an idle or finished root session resumes it. The full send options, including the delivery states in the response, are in Events.

Console
TypeScript
cURL

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

const sent = await rl.managedAgents.sendSessionEvents({
  session_id: 'e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53',
  body: { message: 'Also add a mitigation for each high-severity item.' },
});

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.

Send an image

To show the agent a screenshot or chart that isn’t in your Files library, upload it to the session, then reference it from a message. The model sees the image when its model accepts images.

Console
cURL

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.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53/files' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -F 'file=@error.png'
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 '{"events": [{"type": "user.message", "content": [
    {"type": "text", "text": "This error appears after sign-in. What causes it?"},
    {"type": "image", "uri": "<the uri from the upload>"}
  ]}]}'

The upload returns 201 with the stored image:

{
  "uri": "<private image URI>",
  "media_type": "image/png",
  "byte_size": 184233,
  "width": 1280,
  "height": 800,
  "sha256": "2d8b4e0a1c7f5d934f1c9a0e7b2d5836c1e04a9f7d3b6e2a8c5f0d1b9e7a3c6f"
}

Send PNG, JPEG, or WebP. The type is detected from the bytes. You can also send the bytes as the raw request body with an image Content-Type.
The uri works only in the session it was uploaded to. An upload that no message references is removed after a while.
An image the session’s image limits refuse returns 400 with the reason. See Limits.

Interrupt a session

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.

Console
TypeScript
cURL

While the agent is working, open the session and click Interrupt under the last event.

const { interrupted } = await rl.managedAgents.interruptSession({
  session_id: 'e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53',
  body: {},
});

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 '{}'

{ "interrupted": true }

interrupted: false means nothing was running to stop. That is not an error.

Interrupt and send a new message

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.

Console
TypeScript
cURL

Type your message in Message the agent… and click Interrupt & send. The button appears while the agent is working.

const sent = await rl.managedAgents.interruptAndSendSessionMessage({
  session_id: 'e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53',
  body: { message: 'Stop. Only cover incidents opened this week.' },
});

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.

Cancel a session

Cancelling stops the session now. In-flight work is abandoned, the sandbox is torn down, and the status becomes cancelled with stop_reason: interrupted. Events, outcomes, and deliverables stay readable. A follow-up message to a cancelled root session starts it again in a new sandbox.

Console
TypeScript
cURL

Open the session, then open Session actions and click Hard stop….
Click Stop now.

await rl.managedAgents.cancelSession({ session_id: 'e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53' });

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

{ "cancelled": true }

The response is the same when the session was already finished, so it is safe to repeat. Sandbox teardown can finish shortly after the response.

Delete a session

Deleting 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. You cannot undo a delete.

Console
TypeScript
cURL

Open the session, then open Session actions and click Delete session….
Click Delete.

await rl.managedAgents.deleteSession({ session_id: 'e3a91f5c-7d24-4b68-9c10-2f8e6b4d7a53' });

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

{ "deleted": true }

Get the deliverables

Ask for deliverables by name in your message, for example “write a risk summary named risks.md”. Agents already know where to save files so they are kept after the session ends. Only files saved there are kept; anything else in the sandbox is lost when it is torn down. Download them from the session’s Files tab, or with listFiles and getFileContent. See Deliverables and artifacts and Download session deliverables. To give a session input files, attach them at start with resources or while it runs. See Files.

What can go wrong

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.
`422 environment_not_verified`	The environment’s setup script has not passed a current setup run.	Run environment setup, then start again. See Environments.
`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 above.
`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.
The session stays `queued`	The agent is at `max_concurrent_sessions`.	Wait, cancel other sessions, or raise the agent limit.
`status: completed` but the task is not done	The loop finished without a satisfied outcome.	Check `stop_reason`. See What success means.
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.	Back off and retry after `Retry-After`.

Every error uses the same body: code, message, and details with field, requestId, and retryable. See Errors.

Limits

Metadata: 32 entries per session, 64-character keys, 512-character values.
Referenced sessions: 10 per start.
List page size: 1000.
Provisioning: 5 minutes.
Concurrency is set per agent with max_concurrent_sessions.

See Limits for the rest.

Next steps

Events

Send messages, read the transcript, and stream live events.

Session operations

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

Outcomes

Define what success means and let a grader check it.

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

Before you begin

How a session runs

Start a session

Request fields

Retry a start safely

What success means

Wait for a session to finish

Get a session

List sessions

Send a follow-up message

Send an image

Interrupt a session

Interrupt and send a new message

Cancel a session

Delete a session

Get the deliverables

What can go wrong

Limits

Next steps

Events

Session operations

Outcomes

Deliverables and artifacts

​Before you begin

​How a session runs

​Start a session

​Request fields

​Retry a start safely

​What success means

​Wait for a session to finish

​Get a session

​List sessions

​Send a follow-up message

​Send an image

​Interrupt a session

​Interrupt and send a new message

​Cancel a session

​Delete a session

​Get the deliverables

​What can go wrong

​Limits

​Next steps

Events

Session operations

Outcomes

Deliverables and artifacts

Before you begin

How a session runs

Start a session

Request fields

Retry a start safely

What success means

Wait for a session to finish

Get a session

List sessions

Send a follow-up message

Send an image

Interrupt a session

Interrupt and send a new message

Cancel a session

Delete a session

Get the deliverables

What can go wrong

Limits

Next steps