# List sessions

List OrchaJS durable sessions with .list() and filter by status or metadata.

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

Use `.list()` to show sessions created by one registered agent:

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

for (const session of sessions.items) {
  console.log(session.name, session.status);
}
```

## Filter sessions

Find paused sessions:

```ts
const paused = await orcha.supportAgent.list({
  status: "paused",
});
```

Find sessions attached to one application record:

```ts
const customerSessions = await orcha.supportAgent.list({
  metadata: {
    customerId: "cus_123",
  },
});
```

Filters can be combined:

```ts
const work = await orcha.supportAgent.list({
  status: "active",
  metadata: {
    customerId: "cus_123",
    priority: "high",
  },
});
```

## Example response

```ts
{
  items: [
    {
      sessionId: "ses_01K...",
      agent: "supportAgent",
      name: "Order ord_1001",
      status: "active",
      metadata: { customerId: "cus_123" },
      createdAt: "2026-09-28T12:00:00Z",
      updatedAt: "2026-09-28T12:04:00Z",
      runStatus: "completed",
      pendingClientActions: [],
      lastOutput: "Your order has shipped.",
      usage: {
        inputTokens: 320,
        outputTokens: 42,
        reasoningTokens: null,
        cacheReadTokens: 0,
        cacheWriteTokens: 0,
      },
    },
  ],
  page: 1,         // Current page.
  pageSize: 25,    // Maximum items on this page.
  total: 1,        // Sessions matching the filters.
  hasMore: false,  // Whether another page exists.
}
```

## API reference

```ts
list(options?: {
  page?: number;
  pageSize?: number;
  status?: "active" | "paused" | "completed";
  metadata?: Record<string, string | number | boolean | null>;
}): Promise<SessionList>

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

- `page` defaults to `1`.
- `pageSize` defaults to `50` and accepts `1` through `100`.
- `status` matches the durable session status, not `runStatus`.
- `metadata` matches sessions containing the supplied key-value pairs.
- `items` contains complete
  [`SessionSnapshot`](/docs/sessions/get) objects.
- `total` is the total number matching the filters, not just this page.
- `hasMore` indicates whether the next page exists.

`.list()` is scoped to the registered agent it is called on.
`orcha.supportAgent.list()` does not return sessions owned by another
top-level agent.