Skip to main content
GET
Get session

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

sessionId
string<uuid>
required

Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions.

Query Parameters

view
enum<string>

full (default) returns the whole session. summary omits agent_snapshot, model_snapshot and config, which are most of the session's bytes. agent_snapshot and model_snapshot change when the session moves to another agent version, which the summary's agent_version_id shows, and config can change at any time, so read the full view when you need them current.

Available options:
full,
summary
wait_seconds
integer

Block up to this many seconds while the session is active before responding, so a poll loop needs no client-side timer. The read returns as soon as status leaves active (completed, failed, cancelled, or awaiting_human). The server caps the wait at 20 seconds; larger values are accepted and clamped. 0 (the default) returns immediately.

Required range: 0 <= x <= 60

Response

One durable agent run: its lifecycle status (active, awaiting_human, completed, failed, cancelled), the agent version, environment, model, and credentials it was pinned to, and its place in a multi-agent tree. Returned when starting, reading, or listing sessions; imported RL rollouts appear as sessions too and run no agent loop.

One durable agent run: its lifecycle status (active, awaiting_human, completed, failed, cancelled), the agent version, environment, model, and credentials it was pinned to, and its place in a multi-agent tree. Returned when starting, reading, or listing sessions; imported RL rollouts appear as sessions too and run no agent loop.

computer_use
boolean
required

Whether this session has a computer-enabled environment and a display that passed its readiness probe.

config
object | null
required

Resolved per-session runtime settings written at start, including the snapshotted MCP servers and tool bindings, multi-agent roster, and delegation depth limits. The settings an agent version owns change only when the session moves to another version of its agent. Read-only to callers.

created_at
string<date-time>
required

RFC 3339 timestamp of when this record was created. Server-assigned.

credential_refs
object[] | null
required

Explicit allowlist of individual credentials the session may use; null or empty when none are listed. Read credential_refs_configured to tell an intentionally empty allowlist from a legacy session granted whole vaults.

credential_refs_configured
boolean
required

True when credential_refs is an explicit allowlist. False on legacy sessions granted every credential in their vaults, which would otherwise be indistinguishable from an empty allowlist.

kind
enum<string>
required

What produced the session: api_call, chat, subagent (delegated by another session), session_analyst (a platform-started read-only assistant), or evaluation (a root that inspects a captured target snapshot).

Available options:
api_call,
chat,
rollout,
subagent,
benchmark,
evaluation,
reflection,
session_analyst
organization_id
string
required

Organization that owns this record. Resolved from the API key; never accepted from the caller.

root_session_id
string
required

Root session of the multi-agent tree this session belongs to (UUID). Equal to session_id for a root session.

session_id
string
required

Identifier for this session (UUID). Server-assigned.

session_path
string
required

Position of this session within its tree, as a slash-delimited path of session ids. "/" for a root session.

status
enum<string>
required

Coarse session state shared with RL rollout imports: active, awaiting_human (for a rollout, carries no score), completed, failed, or cancelled. For where a running agent loop is, read execution_state instead.

Available options:
active,
awaiting_human,
completed,
failed,
cancelled
updated_at
string<date-time>
required

RFC 3339 timestamp of the last change to this record. Server-assigned.

access_policy
enum<string>

Present only when reading a platform-managed session directly; these sessions are omitted from session lists.

Available options:
platform_internal
active_handoff
object

Current browser handoff, including its exclusive driver claim and deadline. Absent when no browser handoff is active. Never contains the short-lived access URL.

agent_id
string

Agent this session runs (UUID). Empty for imported sessions that were not started from an agent.

agent_snapshot
object

The definition of the agent version this session runs, frozen so later edits to the agent cannot change this session's behavior. Written at start; it changes only when the session moves to another version of its agent, which agent_version_id shows.

agent_version_id
string

Agent version this session runs (UUID), pinned at start so a later edit to the agent cannot change a running session. It changes only when the session moves to another version of its agent.

budget
object

The session tree's budget and what the tree has spent toward it, on a root session read in full. Omitted when the session has none, and on summary and list reads.

concurrency_slot_held
boolean

Whether this root session currently occupies the agent's max_concurrent_sessions slot. True while admitted and non-terminal. False exclusively while an active queued root waits to start. Omitted for unlimited agents, child sessions, legacy rows, and terminal or deleted sessions.

costState
enum<string>

final once the session has ended, its sandbox has stopped, and every charge has settled: costUsd will not change unless the session is resumed. so_far while it can still grow. Present exactly when costUsd is.

Available options:
final,
so_far
costUsd
string

Billed cost of this session's whole tree as an exact canonical decimal USD string. On Recursion, a writer's cost also includes linked cloned outcome evaluation roots, counting each ledger charge once; manual evaluations remain independent. On other surfaces, cost remains tree-only. Compute still running is included as an estimate; the figure is final once every included tree has ended and settled. Returned by managedAgentsGetSession and managedAgentsListSessions only, and absent when it cannot be read.

Example:

"1.234567"

effective_model
string

Provider-qualified model string this session runs, including any per-session model override. Written at start; it changes only when the session moves to another version of its agent. Prefer this over resolving model_ref_id or the current agent version when displaying the model a session runs.

environment_id
string

Environment whose sandbox definition this session runs in (UUID).

execution_state
enum<string>

Where the agent loop is. Empty for sessions without a loop, such as imported rollouts. provisioning includes any automatic setup-image refresh before sandbox creation. A failure that can't be retried, such as a failed setup script, fails the session with the reason in failure. This field, read from the session itself, is the authoritative status -- a session's event stream is written on a separate path and can lag it, so an empty event list does not mean the session is still starting.

Available options:
provisioning,
queued,
running,
idle,
completed
external_source_id
string

Identifier of the session's counterpart in the external_source_type system, so a caller can find the session again from that side. Set together with external_source_type.

external_source_type
string

Kind of external system this session is correlated to, e.g. slack_thread. Set together with external_source_id and filterable when listing sessions.

failure
object

Structured terminal failure. Omitted for healthy sessions and legacy rows.

forked_at_event_id
string

Event in the parent session (UUID) this session was forked from, so the fork's starting context is identifiable. Set only on forks.

last_activity_at
string<date-time>

RFC 3339 timestamp of when the agent loop last made progress. Distinct from updated_at, which any metadata write touches. Absent for sessions that run no loop.

metadata
object

Caller-defined string key/value pairs supplied when the session was started, e.g. ids from your own system. Immutable, present on root sessions only, and filterable with metadata=key:value or metadata_key=key on GET /managed-agents/v1/sessions. At most 32 entries; keys use letters, digits, '_', '.', and '-' up to 64 characters; values are 1-512 characters.

model_ref_id
string

Model reference the session's turns run on (UUID), resolved from the agent version or the start request. Written at start; it changes only when the session moves to another version of its agent.

model_snapshot
object

The resolved model reference and inference settings this session runs, frozen for the same reason as agent_snapshot. Written at start; it changes only when the session moves to another version of its agent.

parent_session_id
string

Session that created this one (UUID) — the delegating session for a subagent, or the source session for a fork. Empty on a root session.

project_id
string

Billing project this session is attributed to: the project_id sent on session start, the default_project_id of its agent, or the project of the session it was started from. Omitted when the session names no project.

sandbox_instance_id
string

Provider-assigned id of the sandbox instance serving this session. Empty before provisioning finishes; historical self_hosted sessions may also have no instance id.

sandbox_provider
string

Sandbox runtime that provisioned this session's compute, from the supported sandbox providers list.

source_refs
object

Secondary provenance ids from the originating system beyond the primary external source, e.g. an imported rollout's problem, problem-version, and run ids.

stop_reason
string

Why the loop is not running. Set whenever execution_state is idle or completed. sleeping means the agent chose to wait and the session resumes on the next message or at wake_at; awaiting_subagents means a coordinator is waiting on delegated work; out_of_credit and tenant_suspended pause before new work and continue on the next message after the tenant is admitted again; an out_of_credit pause from the last 72 hours also continues on its own within about a minute once the tenant is admitted again; budget_reached means the session tree reached its budget and paused before its next model request, and raising or removing the session's budget continues it, except a session bound to a Slack thread, which continues on its next reply there.

user_id
string

User the session was started on behalf of, resolved from the request scope.

vault_ids
string[]

Vaults (UUIDs) the session may draw credentials from. Combine with credential_refs to narrow the grant to specific credentials.

wake_at
string<date-time>

RFC 3339 timestamp at which a sleeping session wakes itself if nobody messages it first. Absent unless the agent scheduled a timed wait.