Skip to navigation
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
const firstPage = await signum.transfers.getTransfers({
  limit: "50",
});
console.log(firstPage.transfers);  // Transfer[]
console.log(firstPage.nextCursor); // "2026-07-01T12:00:00Z" or null
// Fetch the next page
if (firstPage.nextCursor) {
  const secondPage = await signum.transfers.getTransfers({
    limit: "50",
    cursor: firstPage.nextCursor,
  });
}

Iterating all pages

iterate-all.ts
async function getAllTransfers() {
  const all = [];
  let cursor: string | undefined;
  do {
    const page = await signum.transfers.getTransfers({
      limit: "100",
      cursor,
    });
    all.push(...page.transfers);
    cursor = page.nextCursor ?? undefined;
  } while (cursor);
  return all;
}

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
const page = await signum.organizations.getOrgsByOrgIdLedger({
  orgId: "org_abc123",
  limit: "25",
  offset: "0",
});
console.log(page.entries); // LedgerEntry[]
console.log(page.total);  // 142 — total matching records

Iterating with offset

offset-iterate.ts
async function getAllLedgerEntries(orgId: string) {
  const all = [];
  let offset = 0;
  const limit = 100;
  while (true) {
    const page = await signum.organizations.getOrgsByOrgIdLedger({
      orgId,
      limit: String(limit),
      offset: String(offset),
    });
    all.push(...page.entries);
    if (all.length >= page.total) break;
    offset += limit;
  }
  return all;
}

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