# Read conversation history

Render OrchaJS conversation history with .history() for messages, actions, and skills.

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

Use `.history()` to render a conversation in your application:

```ts
const history = await orcha.supportAgent.history(sessionId, {
  page: 1,
  pageSize: 25,
});

for (const item of history.items) {
  if (item.type === "message") {
    console.log(item.role, item.content);
  }

  if (item.type === "client_action") {
    console.log(item.name, item.callId, item.status);
  }
}
```

`history()` removes low-level provider bookkeeping. Its items represent
messages and useful agent activity such as actions, skills, subagents, and
evaluations.

## Example response

```ts
{
  items: [
    {
      id: "message:3",                     // Stable item ID.
      type: "message",                     // How to interpret this item.
      createdAt: "2026-09-28T12:00:04Z",   // ISO timestamp.
      role: "user",                        // "user" or "assistant".
      content: [
        { type: "text", text: "Where is my order?" },
      ],
    },
    {
      id: "client-action:call_123",
      type: "client_action",
      createdAt: "2026-09-28T12:00:09Z",
      name: "request_human_approval",
      callId: "call_123",
      status: "waiting",
      arguments: { amount: 750, currency: "USD" },
      summary: "request human approval is waiting for the client.",
    },
  ],
  page: 1,          // Current page.
  pageSize: 25,     // Maximum items on this page.
  total: 2,         // Total projected history items.
  hasMore: false,   // Whether an older page exists.

  // The current SessionSnapshot is also included here.
  sessionId: "ses_01K...",
  agent: "supportAgent",
  status: "active",
  metadata: {},
  createdAt: "2026-09-28T12:00:00Z",
  updatedAt: "2026-09-28T12:00:09Z",
  runStatus: "waiting_for_client_action",
  pendingClientActions: [
    {
      callId: "call_123",
      name: "request_human_approval",
      arguments: { amount: 750, currency: "USD" },
    },
  ],
}
```

## Pagination

Page 1 contains the newest page. Higher page numbers move backward through
the session:

```ts
const older = await orcha.supportAgent.history(sessionId, {
  page: 2,
  pageSize: 50,
});
```

Use [`events()`](/docs/sessions/events) when you need the canonical event log
instead of a user-facing history.

## API reference

```ts
history(
  sessionId: string,
  options?: {
    page?: number;
    pageSize?: number;
  },
): Promise<SessionHistory>

type SessionHistory = SessionSnapshot & {
  items: SessionHistoryItem[];
  page: number;
  pageSize: number;
  total: number;
  hasMore: boolean;
};
```

- `page` defaults to `1`.
- `pageSize` defaults to `50` and accepts `1` through `100`.
- Pages are newest-first: page 2 is older than page 1.
- Snapshot fields describe the session at the time of the request.

### History item

```ts
type SessionHistoryItem = {
  id: string;
  type:
    | "message"
    | "action"
    | "client_action"
    | "subagent"
    | "skill"
    | "evaluation"
    | "session_completed";
  createdAt: string;
  role?: "user" | "assistant";
  content?: MessageContent[];
  name?: string;
  status?: "running" | "waiting" | "paused" | "completed" | "failed";
  summary?: string;
  callId?: string;
  childSessionId?: string;
  arguments?: Record<string, unknown>;
  durationMs?: number;
  usage?: Usage;
  metrics?: EvaluationMetric[];
};
```

All items contain `id`, `type`, and `createdAt`. Other fields depend on
`type`:

- `message` — `role`, `content`, and assistant `usage` when available.
- `action` — `name`, `callId`, `status`, `arguments`, `durationMs`, and
  `summary` as available.
- `client_action` — `name`, `callId`, `status`, pending `arguments`, and
  `summary`.
- `subagent` — `name`, `childSessionId`, `callId`, `status`, `usage`, and
  `summary`.
- `skill` — `name`, `status`, and `summary`.
- `evaluation` — `name`, `status`, `metrics`, `durationMs`, and `summary`.
- `session_completed` — completion `status` and `summary`.

### Message content

```ts
type MessageContent =
  | { type: "text"; text: string }
  | {
      type: "image" | "video" | "audio" | "url";
      mimeType: string;
      fileUri: string;
    }
  | {
      type: "file";
      filePath: string;
      mimeType: string;
    };
```