SDK

Pagination

Iterate through large result sets with cursor-based and offset-based pagination

View as Markdown
GETTING STARTED · SDK · PAGINATION

List endpoints return paginated results. The Clossir API uses two pagination styles depending on the endpoint.

Cursor-based pagination (primary)

Most list endpoints use cursor-based pagination. Pass cursor and limit as query parameters; the response includes a nextCursor field for the next page.

cursor-pagination.ts
1const firstPage = await signum.transfers.getTransfers({
2  limit: "50",
3});
4
5console.log(firstPage.transfers);  // Transfer[]
6console.log(firstPage.nextCursor); // "2026-07-01T12:00:00Z" or null
7
8// Fetch the next page
9if (firstPage.nextCursor) {
10  const secondPage = await signum.transfers.getTransfers({
11    limit: "50",
12    cursor: firstPage.nextCursor,
13  });
14}

Iterating all pages

iterate-all.ts
1async function getAllTransfers() {
2  const all = [];
3  let cursor: string | undefined;
4
5  do {
6    const page = await signum.transfers.getTransfers({
7      limit: "100",
8      cursor,
9    });
10
11    all.push(...page.transfers);
12    cursor = page.nextCursor ?? undefined;
13  } while (cursor);
14
15  return all;
16}

Defaults and limits

ParameterDefaultMaximum
limit50100
cursor—Opaque string from nextCursor

The cursor is typically the created_at timestamp of the last item, but treat it as an opaque token — don’t construct cursors manually.

Offset-based pagination

Some endpoints (notably ledger queries) use traditional offset-based pagination with a total count in the response:

offset-pagination.ts
1const page = await signum.organizations.getOrgsByOrgIdLedger({
2  orgId: "org_abc123",
3  limit: "25",
4  offset: "0",
5});
6
7console.log(page.entries); // LedgerEntry[]
8console.log(page.total);  // 142 — total matching records

Iterating with offset

offset-iterate.ts
1async function getAllLedgerEntries(orgId: string) {
2  const all = [];
3  let offset = 0;
4  const limit = 100;
5
6  while (true) {
7    const page = await signum.organizations.getOrgsByOrgIdLedger({
8      orgId,
9      limit: String(limit),
10      offset: String(offset),
11    });
12
13    all.push(...page.entries);
14
15    if (all.length >= page.total) break;
16    offset += limit;
17  }
18
19  return all;
20}

Which style does my endpoint use?

Check the endpoint’s request parameters:

  • Has cursor → cursor-based (most endpoints)
  • Has offset → offset-based (ledger, some analytics)

The API Reference documents the pagination parameters for each endpoint.

Next steps