> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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`
## OpenAPI
````yaml /openapi.json get /v3/organizations/{orgId}/sessions/{sessionId}
openapi: 3.1.0
info:
title: Reason Machines API
version: 3.0.0
description: >-
The Reason HTTP API. Drive cloud software-engineering agents: open sessions
against your repositories, stream their work, and manage the secrets,
knowledge, skills, and automations they run with.
Authenticate with a Reason API key sent as a bearer token. New keys use
`reason_`; legacy `ara_` keys remain accepted. Every resource is scoped to
an organization; resolve your `org_id` once with `GET /v3/self`.
servers:
- url: https://api.reasonmachines.ai
security:
- araApiKey: []
tags:
- name: Devices
description: >-
Owned Mac and headless Device identity, bounded enrollment and root
grants.
- name: Account
description: Verify a key and resolve the organization it belongs to.
- name: Projects
description: >-
Discover existing workspace projects to target when creating and listing
sessions.
- name: Sessions
description: >-
A session is one run of an agent against a repository: it reproduces the
task, writes the code, verifies it, and opens a pull request or merge
request.
- name: Secrets
description: >-
Encrypted credentials injected into the agent's sandbox. Write-only:
values can be set but never read back.
- name: Knowledge
description: Durable notes the agent consults while it works.
- name: Memory
description: >-
Editable repository notes that are projected into native memory; generated
memory remains read-only.
- name: Skills
description: >-
Reusable instruction bundles Reason selects semantically from their
descriptions for matching agent tasks.
- name: Automations
description: Recurring or one-time triggers that open sessions on a timetable.
- name: Change Request Reviews
description: >-
Automated senior-engineer reviews posted on pull requests and merge
requests.
- name: Repositories
description: Connected repositories, their indexing state, and generated wikis.
- name: Git Connections
description: Linked source-control accounts and the repositories they expose.
- name: Consumption
description: 'Billing-aligned usage: daily consumption and billing cycles.'
- name: Metrics
description: Aggregate analytics over sessions, change requests, and usage.
- name: Audit Logs
description: An append-only record of changes made within the organization.
- name: Organizations
description: The top-level tenant. Create, read, update, and delete organizations.
- name: Members
description: People in an organization and their pending invites.
- name: Service Users
description: Machine principals that own API keys for headless access.
- name: Roles
description: Role assignments that govern what each member can do.
- name: Attachments
description: >-
Files uploaded to the organization and shared with sessions, downloaded
via short-lived signed URLs.
- name: Guardrails
description: >-
Per-repository automation limits and the violations recorded when a limit
is hit.
- name: MCP Servers
description: >-
Org-level Model Context Protocol servers exposed to the agent. Secret
values are write-only.
- name: Settings
description: 'Organization configuration: namespaced settings and the run tag policy.'
- name: Blueprints
description: >-
Read-only declarative manifests of an organization's agents (identity, run
config, triggers, suite), with credentials redacted.
- name: IP Access List
description: >-
Source-network allow-list that, when enabled, restricts the organization's
API surface to a set of CIDR ranges.
- name: Groups
description: Manually-curated member groups carrying optional per-day resource limits.
- name: Provider Credentials
description: >-
Configure Bring-Your-Own-Key (BYOK) API keys and subscription credentials
for model providers. Secret values are write-only.
paths:
/v3/organizations/{orgId}/sessions/{sessionId}:
parameters:
- $ref: '#/components/parameters/orgId'
- name: sessionId
description: The session id.
in: path
required: true
schema:
type: string
get:
tags:
- Sessions
summary: Retrieve a session
description: >-
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`
operationId: getSession
responses:
'200':
description: The session.
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
'404':
$ref: '#/components/responses/NotFound'
security:
- araApiKey:
- sessions:read
components:
parameters:
orgId:
name: orgId
in: path
required: true
description: Organization id or slug. Resolve it with `GET /v3/self`.
schema:
type: string
schemas:
Session:
description: >-
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.
type: object
properties:
benchmark_profile:
type:
- string
- 'null'
const: coding-benchmark-v1
session_policy:
type: object
properties:
version:
type: number
const: 1
mode:
type: string
enum:
- standard
- isolated
components:
type: object
properties:
memoryRead:
type: boolean
memoryWrite:
type: boolean
skills:
type: boolean
inheritedInstructions:
type: boolean
integrations:
type: boolean
secretInjection:
type: boolean
required:
- memoryRead
- memoryWrite
- skills
- inheritedInstructions
- integrations
- secretInjection
workspaceOwnership:
type: string
enum:
- ara-managed
- externally-managed
required:
- version
- mode
- components
- workspaceOwnership
description: >-
Server-resolved immutable Session policy. Enabled components remain
subject to normal permissions and configuration.
session_id:
type: string
status:
type: string
enum:
- running
- exit
- error
- suspended
description: running, exit (completed), error, or suspended (cancelled/quota).
url:
type: string
description: Web URL to watch the session.
created_at:
type: string
format: date-time
started_at:
type:
- string
- 'null'
format: date-time
finished_at:
type:
- string
- 'null'
format: date-time
title:
type:
- string
- 'null'
prompt:
description: >-
The opening instruction, truncated to 16 KiB. Check
prompt_truncated; read the session messages for the full text.
type:
- string
- 'null'
prompt_truncated:
type: boolean
description: True when prompt was cut to the 16 KiB echo limit.
prompt_bytes:
description: UTF-8 byte length of the full prompt, before truncation.
type:
- integer
- 'null'
tags:
type: array
items:
type: string
project_id:
description: Project containing the session, or null for an unassigned session.
type:
- string
- 'null'
format: uuid
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:
type:
- string
- 'null'
provider:
description: Source-control provider for the session repository.
type:
- string
- 'null'
enum:
- github
- gitlab
model:
description: Concrete model selected for this session, or null when inherited.
type:
- string
- 'null'
reasoning_effort:
type:
- string
- 'null'
hands_mode:
type: string
enum:
- adaptive
- brain_only
description: >-
Durable physical execution policy. Brain-only sessions never acquire
a shell, browser, sandbox, or physical secret environment.
branch:
type:
- string
- 'null'
pr_url:
type:
- string
- 'null'
pr_title:
type:
- string
- 'null'
result_summary:
type:
- string
- 'null'
outcome:
description: >-
Caller-facing task outcome. Null when execution did not produce a
task outcome.
type:
- string
- 'null'
enum:
- success
- failure
- action_required
result:
description: >-
Caller-defined JSON result for a noninteractive completion, or the
ordinary final summary for legacy Sessions.
error_class:
description: >-
Stable runtime failure class when execution did not produce a task
outcome.
type:
- string
- 'null'
error_message:
description: >-
Redacted persisted error preview, bounded to 1000 characters; null
when unavailable.
type:
- string
- 'null'
failure_diagnostics:
description: >-
Best-effort attribution from persisted failure signatures. Unknown
stages and root causes remain null.
type:
- object
- 'null'
properties:
failure_stage:
description: Execution stage where failure occurred.
type:
- string
- 'null'
reason_code:
description: Specific machine-readable reason code for the failure.
type:
- string
- 'null'
root_cause:
description: Root cause classification of the failure.
type:
- string
- 'null'
required:
- failure_stage
- reason_code
- root_cause
failure_stage:
description: Execution stage where failure occurred.
type:
- string
- 'null'
reason_code:
description: Specific machine-readable reason code for the failure.
type:
- string
- 'null'
root_cause:
description: Root cause classification of the failure.
type:
- string
- 'null'
diagnostic_message:
description: >-
Fixed public message selected from an allowlisted persisted error
class, never error prose, prompts or tool output. Null when unknown.
type:
- string
- 'null'
maxLength: 160
duration_ms:
type:
- integer
- 'null'
cost_usd:
description: >-
Total model spend in USD across the session's turns. Null when usage
was never reported.
type:
- number
- 'null'
usage:
type: object
properties:
input_tokens:
type:
- integer
- 'null'
output_tokens:
type:
- integer
- 'null'
total_tokens:
type:
- integer
- 'null'
required:
- input_tokens
- output_tokens
- total_tokens
description: >-
Token usage totals for the session. Fields are null for runs that
predate usage persistence.
context:
type: object
properties:
tokens:
description: Tokens in the model's context window after the latest turn.
type:
- integer
- 'null'
window:
description: The model's context window size.
type:
- integer
- 'null'
percent:
description: Context occupancy 0-100, rounded.
type:
- integer
- 'null'
required:
- tokens
- window
- percent
description: >-
Live context occupancy after the latest turn (not billing
throughput).
is_archived:
type: boolean
session_type:
type: string
enum:
- session
- sidechat
- subagent
description: Session, sidechat fork, or read-only subagent Session.
source_session_id:
description: >-
The fork source for a sidechat or spawning Session for a subagent;
null for a normal Session.
type:
- string
- 'null'
read_only:
type: boolean
description: True only for subagent Sessions.
repos:
type: array
items:
type: string
description: >-
Every repository currently attached to the session, as owner/name.
Present on Retrieve a session only, and only when recorded.
change_requests:
type: array
items:
type: object
properties:
url:
type: string
description: Pull request or merge request URL.
status:
type: string
enum:
- active
- completed
- retired
required:
- url
- status
description: >-
Every change request the session opened, including ones in
repositories other than `repo`. Present on Retrieve a session only,
and only when recorded.
required:
- session_policy
Error:
type: object
properties:
error:
type: string
message:
type: string
required_scope:
type: string
description: >-
The capability required when the request was denied for a missing
scope.
responses:
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: session_not_found
securitySchemes:
araApiKey:
type: http
scheme: bearer
bearerFormat: 'reason_ (legacy: ara_)'
description: >-
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.
````