Pagination

How listings page, and the one that does not.

Listings answer with a Page. Iterate it to walk every item from that page onward, or follow the cursor by hand.

for await (const agent of await subako.agents.list({ limit: 100 })) {
	console.log(agent.name);
}

const page = await subako.sessions.listEvents(sessionId, { after_seq: 41 });
console.log(page.items, page.nextCursor);
const next = await page.nextPage(); // Page | null

Direction

Every listing answers newest first, and order: "asc" walks the other way. The cursor follows the direction of travel, so a walk continues past its last item whichever way it runs.

const oldest = await subako.agents.list({ order: "asc", limit: 100 });

Cursors

Cursors are plain values: a string id for most listings, a number seq for the session event log.

The event log is the one listing whose cursor changes name with the direction — before_seq descending, after_seq ascending — and the Page sends back whichever the listing asked for. Both bounds are exclusive, so a window is { after_seq, before_seq }:

const window = await subako.sessions.listEvents(sessionId, { after_seq: 100, before_seq: 200 });

The one that is not a Page

listSandboxes is the exception, and says so in its type. An agent’s config names the sandboxes it grants, so the set is bounded and the whole of it travels at once. It answers with { items } and no cursor:

const { items } = await subako.sessions.listSandboxes(sessionId);

A Page there would promise a second call that cannot be made — the route takes no cursor parameter at all. See Sandboxes.

What takes a cursor

Every other listing accepts limit, after, and order:

await subako.agents.list({ limit: 50, after: lastId, order: "asc" });
await subako.agents.listVersions(agentId, { limit: 50 });
await subako.apiKeys.list();
await subako.modelProviders.list();
await subako.organization.listMembers();
await subako.organization.listInvitations();
await subako.organization.listUsage({ limit: 100 });
await subako.sessions.list();
await subako.skills.list();
await subako.skills.listVersions(skillId);
await subako.vaults.list();
await subako.vaults.listCredentials(vaultId);
await subako.workspaces.list();
await subako.workspaces.listMembers(workspaceId);
await subako.workspaces.listUsage(workspaceId);

sessions.listEvents is the same, with after_seq and before_seq in place of after.