How to use durable sessions
List sessions
List OrchaJS durable sessions with .list() and filter by status or metadata.
Use .list() to show sessions created by one registered agent:
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:
const paused = await orcha.supportAgent.list({
status: "paused",
});Find sessions attached to one application record:
const customerSessions = await orcha.supportAgent.list({
metadata: {
customerId: "cus_123",
},
});Filters can be combined:
const work = await orcha.supportAgent.list({
status: "active",
metadata: {
customerId: "cus_123",
priority: "high",
},
});Example response
{
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
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;
};pagedefaults to1.pageSizedefaults to50and accepts1through100.statusmatches the durable session status, notrunStatus.metadatamatches sessions containing the supplied key-value pairs.itemscontains completeSessionSnapshotobjects.totalis the total number matching the filters, not just this page.hasMoreindicates 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.