GET
Get an agent session
See Agent sessions for what run_status means and how a session recovers from a run whose worker died mid-turn.

Authorizations

x-api-key
string
header
required

API key for authentication

Headers

Idempotency-Key
string

Accepted for client uniformity but IGNORED on this endpoint. It has no side effects, and a retry can legitimately return different results, so replaying a cached response would hand back stale data. Every request executes fresh: no 24h window, no replay, no Idempotent-Replayed header, and no key-reuse 422.

Path Parameters

session_id
string
required

Session to read.

Response

The session.

session_id
string
required

Opaque session identifier used by the other agent routes.

Example:

"665f1c2e8a1b4c0012ab34cd"

title
string
required

The submitted title, or the placeholder the agent replaces when it names the session on its first turn.

Example:

"New Chat"

created_at
string<date-time>
required
updated_at
string<date-time>
required
run_status
enum<string> | null
required

Status of this session's most recent run, or null if it has never run.

QUEUED and RUNNING mean a turn is in flight — asking again is a 409. COMPLETED, FAILED, STOPPED and STALE all mean the session is free. STALE is assigned on read when a run stopped reporting past its threshold, which is how a session recovers from a worker that died without sending a terminal event.

Available options:
QUEUED,
RUNNING,
COMPLETED,
FAILED,
STOPPED,
STALE
Example:

"COMPLETED"

last_active_at
string<date-time> | null

When a turn was last enqueued on this session.

job_id
string | null

Job handle for the most recent run, when it was started through this API. Null for a turn asked in the app.

Example:

"sajob_9f2c1a4b7e8d4c1fa0b3"