Retrieve a session

Returns the stable Session identity with current execution state, a bounded redacted error_message, and best-effort failure_diagnostics. Unknown diagnostic fields are null. A previously returned physical Attempt UUID remains accepted as a compatibility alias, but the response always carries the Session session_id and URL.

_{Scope: sessions:read}

GET /v3/organizations/{orgId}/sessions/{sessionId}

Retrieve a session

cURL

curl --request GET \
  --url https://api.reasonmachines.com/v3/organizations/{orgId}/sessions/{sessionId} \
  --header 'Authorization: Bearer <token>'

200

successful

{
  "benchmark_profile": null,
  "runtime_profile": null,
  "experimental_runtime_profile": null,
  "experimental_runtime_features": null,
  "session_policy": {
    "version": 1,
    "mode": "standard",
    "workspaceOwnership": "managed",
    "components": {
      "memoryRead": true,
      "memoryWrite": true,
      "skills": true,
      "inheritedInstructions": true,
      "integrations": true,
      "secretInjection": true
    }
  },
  "session_id": "ses_91af3c",
  "project_id": null,
  "status": "exit",
  "url": "http://127.0.0.1:3001/agents/ses_91af3c",
  "created_at": null,
  "started_at": null,
  "finished_at": null,
  "title": null,
  "prompt": null,
  "prompt_truncated": false,
  "prompt_bytes": null,
  "tags": [],
  "agent_id": null,
  "agent_name": null,
  "repo": null,
  "provider": null,
  "model": null,
  "reason_version": null,
  "reason_commit_sha": null,
  "reasoning_effort": null,
  "hands_mode": "adaptive",
  "branch": null,
  "pr_url": null,
  "pr_title": null,
  "result_summary": "Review finished.",
  "outcome": "success",
  "result": null,
  "error_class": null,
  "diagnostic_message": null,
  "error_message": null,
  "failure_diagnostics": null,
  "failure_stage": null,
  "reason_code": null,
  "root_cause": null,
  "trigger_source": null,
  "duration_ms": null,
  "cost_usd": null,
  "usage": {
    "input_tokens": null,
    "output_tokens": null,
    "total_tokens": null
  },
  "context": {
    "tokens": null,
    "window": null,
    "percent": null
  },
  "archived_at": null,
  "is_archived": false,
  "session_type": "session",
  "source_session_id": null,
  "read_only": false
}

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:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Path Parameters

orgId · string · required

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

sessionId · string · required

The session id.

Response

200

application/json

The session.

Current lifecycle snapshot. Without sessions:debug held by an organization owner/admin, 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.

Show child attributes

session_id · string · required

status · enum<string> · required

Lifecycle state, not task success: running, exit (execution completed), error (execution failed), or suspended (cancelled/quota). An exit can have outcome failure or action_required. Check outcome, result, and diagnostics before treating work as successful.

Available options: running, exit, error, suspended

url · string · required

Web URL to watch the session.

created_at · string<date-time> | null · required

benchmark_profile · string | null

Always null: benchmark_profile is retired.

Allowed value: "coding-benchmark-v1"

runtime_profile · string | null

runtime/reason-sync-yield-v1 on a retired isolated Session that requested it through the retired runtime_profile field. Null otherwise.

Allowed value: "runtime/reason-sync-yield-v1"

experimental_runtime_profile · enum<string> | null

The runtime profile the Session's latest Attempt runs: the default C2 harness on every Session that runs it, whether or not its request named it (a Session of the retired runtime/reason-capability-shell-v1 continues on it) — reported as runtime/reason-c2-tools-v7; runtime/reason-v7-sync-yield-v1 on a standard or ephemeral Session that runs it; runtime/reason-v7-sync-yield-machine-sdk-v1, runtime/reason-v7-stock-prompt-v1, runtime/reason-v7-docs-v1 or runtime/reason-v7-2026-10 on a Session that runs it. Null otherwise.

Available options: runtime/reason-c2-tools-v7, runtime/reason-v7-sync-yield-v1, runtime/reason-v7-sync-yield-machine-sdk-v1, runtime/reason-v7-stock-prompt-v1, runtime/reason-v7-docs-v1, runtime/reason-v7-stock-shape-v1, runtime/reason-v7-2026-10

experimental_runtime_features · enum<string>[] | null

The runtime features the Session's create named (experimental_runtime_features), in canonical order. Null when it named none.

Available options: banner, sdk_index, service_tier, output_cap, git_metadata, serial_reads, recovery_defer_idle_hands, fewer_tests_low, fewer_tests_medium, fewer_tests_high, fewer_tests_max

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

target · object

Present on GET: the execution target this Session was created with (cloud, or the Device and root it runs on). A later handoff is not reflected. A Machine target reads back as its placed headless worker; see machine.

Option 1

Option 2

Option 3

Show child attributes

machine · object

Present on GET for a Session attempt that targets a Machine: its queue state, live queue position while waiting, and the worker it was placed on.

Show child attributes

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.

reason_version · string | null

The Reason Agent version (X.Y, e.g. 1.4 for Reason Agent 1.4) of the server that executed the Session's latest turn. It names the daily release; reason_commit_sha is the exact build. During a rolling deploy this is the release that actually ran the turn, not the newest one. Null before the turn starts and for turns that ran before versions were recorded.

reason_commit_sha · string | null

The commit the server that executed the Session's latest turn was built from. Null when reason_version is null or the build carried no commit.

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. Runtime codes use the run_ prefix (for example run_error, run_timeout, run_cancelled) and cloud execution codes the cloud_ prefix (for example cloud_device_unavailable); since 2026-10 they replace the earlier pi_, pi_run_ and ara_cloud_ spellings, which the API no longer reports.

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.

Show child attributes

failure_stage · string | null

Execution stage where failure occurred.

reason_code · string | null

Specific machine-readable reason code for the failure. Runtime and cloud execution codes use the run_ and cloud_ prefixes, as in error_class.

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.

Show child attributes

context · object

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

Show child attributes

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.

Show child attributes