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 row's bytes. They are written at start and change only when the session moves to another version of its agent, which the summary's agent_version_id shows: a poller that already holds them should ask for summary and read the full view again when agent_version_id changes.

Available options:
full,
summary

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), or session_analyst (a platform-started read-only assistant that answers questions about another session tree).

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. The deployment's compute-ready timeout (five minutes by default) bounds sandbox readiness after refresh, not the setup run itself. A failed setup or sandbox timeout 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.

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.