Sessions

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. The opening prompt is repeated on every read, in prompt (up to 16 KiB; prompt_truncated and prompt_bytes say when it was cut) and, for a Session without a title of its own, as the first 200 characters of title. To poll cheaply, pass fields (for example fields=status,outcome,result) and read the complete Session once. A response narrowed by fields carries only session_id and the named properties, so it omits properties the Session schema marks required.

<sub>Scope: sessions:read</sub>

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

Request

Base URL: https://api.reasonmachines.com
URL: https://api.reasonmachines.com/v3/organizations/{orgId}/sessions/{sessionId}
Auth: HTTP bearer

Query parameters

fieldsstring

Example:status,outcome,result

Comma-separated top-level properties of the Session to return, for example status,outcome,result,error_class,pr_url. session_id is always returned. Repeating the parameter (fields=status&fields=outcome) is read as the same list. Names are case-sensitive, and nested paths such as usage.input_tokens are not supported: name the top-level property (usage). A name that is not a Session property is refused with 400 invalid_request, whose unknown_fields and allowed_fields list what was wrong and what is accepted. A documented property this Session does not carry (for example machine) is left out. The narrowed response omits every other property, including ones the Session schema marks required. Omit fields for the complete Session; the complete read repeats prompt (up to 16 KiB) every time.

Response

The session.

benchmark_profile'coding-benchmark-v1' nullable

Always null: benchmark_profile is retired.

runtime_profile'runtime/reason-sync-yield-v1' nullable

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

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, runtime/reason-v7-2026-10 or runtime/reason-v7-2026-11 on a Session that runs it. Null otherwise.

experimental_runtime_featuresstring[] nullable

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

session_idstring required

origin'ui' | 'external:cli' | 'external:mcp' | 'external:api'

origin_agentstring nullable

agent_identity_source'self_reported' | 'credential' | 'device' nullable

status'running' | 'exit' | 'error' | 'suspended' required

Lifecycle state, not task success: running, exit (execution completed), error (execution failed), or suspended (cancelled/quota; suspended_reason says which). An exit can have outcome failure or action_required. The task succeeded if and only if outcome is success; check outcome, result, and diagnostics before treating work as successful.

suspended_reason'cancelled' | 'quota_exhausted' nullable

Why status is suspended: cancelled (an explicit cancel stopped the Session) or quota_exhausted (the Workspace ran out of quota). Null for every other status.

urlstring required

Web URL to watch the session.

created_atstring date-time nullable required

started_atstring date-time nullable

finished_atstring date-time nullable

titlestring nullable

promptstring nullable

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

prompt_truncatedboolean

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

prompt_bytesinteger nullable

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

tagsstring[]

project_idstring uuid nullable

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

repostring nullable

provider'github' | 'gitlab' nullable

Source-control provider for the session repository.

modelstring nullable

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

reason_versionstring nullable

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_shastring nullable

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_effortstring nullable

hands_mode'adaptive' | 'brain_only'

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

branchstring nullable

Name of the Session's working branch in its workspace. It is assigned when the machine starts, before any commit, so it exists on the remote only once the Session pushed to it: check pr_url and branch_has_commits.

branch_has_commitsboolean nullable

Whether the working branch reached the remote without a pull request: true when it has pushed commits, false when the Session ended without pushing any (the branch may not exist on the remote). Null while undetermined, and when pr_url is set.

pr_urlstring nullable

pr_titlestring nullable

result_summarystring nullable

outcome'success' | 'failure' | 'action_required' nullable

The task verdict, and the one field that says whether the work succeeded: the task succeeded if and only if outcome is success. Retrieve a session and List sessions report the same value. With completion_mode: run_outcome it is the verdict the agent recorded (success, failure, or action_required when a person or an unavailable dependency must act); a run that stops without recording one never reports success, normally action_required with its reply in result. Recording a verdict is a tool call, so a prompt that forbids tools gets action_required even when the reply is correct. Without completion_mode no verdict is recorded: an exit reports success because the execution completed (action_required when the turn ended waiting on a person), which does not say the work was checked. Null while running and when status is error or suspended without a verdict.

resultunknown

error_classstring nullable

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 runtime-internal and ara_cloud_ spellings, which the API no longer reports.

error_messagestring nullable

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

failure_stagestring nullable

Execution stage where failure occurred.

reason_codestring nullable

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

root_causestring nullable

Root cause classification of the failure.

diagnostic_messagestring nullable

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

duration_msinteger nullable

cost_usdnumber nullable

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

is_archivedboolean

session_type'session' | 'sidechat' | 'subagent'

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

source_session_idstring nullable

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

read_onlyboolean

True only for subagent Sessions.

reposstring[]

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

Changes

No recorded changes to this operation across all 1 revision of this API.