Skip to main content
GET
Retrieve a session

Authorizations

Authorization
string
header
required

Your Reason API key from Settings > API. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, knowledge:read, memory:read, memory:write, skills:read, skills:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, automations:read, automations:write, agent_auth:read. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:debug is privileged: it expands diagnostic session events only for organization owners/admins.

Path Parameters

orgId
string
required

Organization id or slug. Resolve it with GET /v3/self.

sessionId
string
required

The session id.

Response

The session.

Current lifecycle snapshot. Without sessions:debug, includes Session identity, status, timestamps, resolved session_policy, error_class, duration_ms, cost_usd and usage; excludes prompt, result content and diagnostic context.

session_policy
object
required

Server-resolved immutable Session policy. Enabled components remain subject to normal permissions and configuration.

benchmark_profile
string | null
Allowed value: "coding-benchmark-v1"
session_id
string
status
enum<string>

running, exit (completed), error, or suspended (cancelled/quota).

Available options:
running,
exit,
error,
suspended
url
string

Web URL to watch the session.

created_at
string<date-time>
started_at
string<date-time> | null
finished_at
string<date-time> | null
title
string | null
prompt
string | null

The opening instruction, truncated to 16 KiB. Check prompt_truncated; read the session messages for the full text.

prompt_truncated
boolean

True when prompt was cut to the 16 KiB echo limit.

prompt_bytes
integer | null

UTF-8 byte length of the full prompt, before truncation.

tags
string[]
project_id
string<uuid> | null

Project containing the session, or null for an unassigned session.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
repo
string | null
provider
enum<string> | null

Source-control provider for the session repository.

Available options:
github,
gitlab
model
string | null

Concrete model selected for this session, or null when inherited.

reasoning_effort
string | null
hands_mode
enum<string>

Durable physical execution policy. Brain-only sessions never acquire a shell, browser, sandbox, or physical secret environment.

Available options:
adaptive,
brain_only
branch
string | null
pr_url
string | null
pr_title
string | null
result_summary
string | null
outcome
enum<string> | null

Caller-facing task outcome. Null when execution did not produce a task outcome.

Available options:
success,
failure,
action_required
result
any

Caller-defined JSON result for a noninteractive completion, or the ordinary final summary for legacy Sessions.

error_class
string | null

Stable runtime failure class when execution did not produce a task outcome.

error_message
string | null

Redacted persisted error preview, bounded to 1000 characters; null when unavailable.

failure_diagnostics
object | null

Best-effort attribution from persisted failure signatures. Unknown stages and root causes remain null.

failure_stage
string | null

Execution stage where failure occurred.

reason_code
string | null

Specific machine-readable reason code for the failure.

root_cause
string | null

Root cause classification of the failure.

diagnostic_message
string | null

Fixed public message selected from an allowlisted persisted error class, never error prose, prompts or tool output. Null when unknown.

Maximum string length: 160
duration_ms
integer | null
cost_usd
number | null

Total model spend in USD across the session's turns. Null when usage was never reported.

usage
object

Token usage totals for the session. Fields are null for runs that predate usage persistence.

context
object

Live context occupancy after the latest turn (not billing throughput).

is_archived
boolean
session_type
enum<string>

Session, sidechat fork, or read-only subagent Session.

Available options:
session,
sidechat,
subagent
source_session_id
string | null

The fork source for a sidechat or spawning Session for a subagent; null for a normal Session.

read_only
boolean

True only for subagent Sessions.

repos
string[]

Every repository currently attached to the session, as owner/name. Present on Retrieve a session only, and only when recorded.

change_requests
object[]

Every change request the session opened, including ones in repositories other than repo. Present on Retrieve a session only, and only when recorded.