# Read a session

Read an OrchaJS session snapshot with .get() for status, output, and pending client actions.

Source: https://orcha.sh/docs/sessions/get
Markdown: https://orcha.sh/docs/sessions/get.mdx

Use `.get()` to read the latest session state without starting another run:

```ts
const session = await orcha.supportAgent.get(sessionId);

console.log(session.status);
console.log(session.lastOutput);
```

This is useful when restoring a page after a refresh, checking background
work, or finding a pending client action.

## Example snapshot

```ts
{
  sessionId: "ses_01K...",             // The durable session ID.
  agent: "supportAgent",               // Registered agent key.
  name: "Order ord_1001",              // Optional display name.
  status: "active",                    // Overall session state.
  metadata: { customerId: "cus_123" }, // Application data you attached.
  createdAt: "2026-09-28T12:00:00Z",   // ISO creation time.
  updatedAt: "2026-09-28T12:01:12Z",   // ISO time of the latest event.
  runStatus: "completed",              // State of the latest run.
  pendingClientActions: [],            // Client actions still waiting.
  lastOutput: "Your order has shipped.", // Latest assistant output.
  usage: {                              // Latest run token usage.
    inputTokens: 320,
    outputTokens: 42,
    reasoningTokens: null,
    cacheReadTokens: 0,
    cacheWriteTokens: 0,
  },
}
```

## Restore a pending action

```ts
const session = await orcha.supportAgent.get(sessionId);

if (session.runStatus === "waiting_for_client_action") {
  const call = session.pendingClientActions[0];

  console.log(call.name, call.arguments);
}
```

Resolve it with [`resume()`](/docs/sessions/resume).

## API reference

```ts
get(sessionId: string): Promise<SessionSnapshot>

type SessionSnapshot = {
  sessionId: string;
  agent: string;
  name?: string;
  status: "active" | "paused" | "completed";
  metadata: Record<string, string | number | boolean | null>;
  createdAt: string;
  updatedAt: string;
  runStatus?:
    | "running"
    | "waiting_for_subagent"
    | "waiting_for_client_action"
    | "paused"
    | "completed"
    | "failed";
  pendingClientActions: ClientToolCall[];
  lineage?: {
    origin: "delegated";
    parentAgent: string;
    parentSessionId: string;
    parentCallId: string;
  };
  lastOutput?: AgentOutput;
  usage?: Usage;
};

type ClientToolCall = {
  callId: string;
  name: string;
  arguments: Record<string, unknown>;
};

type Usage = {
  inputTokens: number;
  outputTokens: number;
  reasoningTokens: number | null;
  cacheReadTokens: number;
  cacheWriteTokens: number;
};
```

### Status fields

`status` describes the durable session:

- `active` — available, waiting for a client action, or currently running.
- `paused` — explicitly paused with `.pause()`.
- `completed` — its lifecycle is complete.

`runStatus` describes only the latest run:

- `running` — the model is working.
- `waiting_for_subagent` — a child agent is working.
- `waiting_for_client_action` — your client must return tool results.
- `paused` — work was explicitly paused.
- `completed` — the latest run finished normally.
- `failed` — the latest run failed.

### Optional fields

- `lineage` exists on delegated subagent sessions and points back to the
  parent.
- `lastOutput` is text for text agents or parsed data for JSON agents.
- `usage` can be absent before the session has recorded model usage.
- `runStatus` can be absent before the first run starts.

`.get()` throws `session_not_found` when the ID does not belong to this
registered agent.