Pagination

How list endpoints page results, and how to walk every page.

Pagination

List endpoints return a fixed-size page of results wrapped in a metadata envelope. The page size is capped at 100 items per request, there is no "unbounded" mode.

Response shape

Every paginated list endpoint returns the same wrapper:

{
  "data": [ /* up to pageSize items */ ],
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 137,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Field	Type	Description
`page`	`number`	1-indexed page number you just fetched.
`pageSize`	`number`	Number of items per page (max 100).
`total`	`number`	Total matching records across all pages.
`totalPages`	`number`	Total number of pages. Always `>= 1`.
`hasNextPage`	`boolean`	`true` when another page is available.
`hasPrevPage`	`boolean`	`true` when there is a page before this one.

Query parameters

Every paginated list endpoint accepts the same two query parameters:

Parameter	Type	Default	Notes
`page`	`integer`	`1`	1-indexed page number.
`pageSize`	`integer`	`50`	Items per page (1–100). Values above 100 are clamped to 100.

Filters (e.g. status, search) are applied before pagination, so pagination.total reflects the count of records matching your filters, not the total in the org.

Walking all pages

Loop until hasNextPage is false:

async function fetchAllLeads(token: string) {
  const out: Lead[] = [];
  let page = 1;
  while (true) {
    const res = await fetch(
      `https://your-host/api/v1/leads?page=${page}&pageSize=100`,
      { headers: { Authorization: `Bearer ${token}` } },
    );
    const body = await res.json() as {
      data: Lead[];
      pagination: { hasNextPage: boolean };
    };
    out.push(...body.data);
    if (!body.pagination.hasNextPage) return out;
    page++;
  }
}

Don't rely on pagination.totalPages snapshot from the first response, records can be created or deleted between requests. Always check hasNextPage on the page you just received.

cURL

# First page
curl -H "Authorization: Bearer $KEY" \
  'https://your-host/api/v1/leads?page=1&pageSize=100'

# Next page
curl -H "Authorization: Bearer $KEY" \
  'https://your-host/api/v1/leads?page=2&pageSize=100'

Performance tips

Use the largest pageSize (100) you can when bulk-exporting.
Combine pagination with filters (status, assignedToId, search) to keep pages small and queries fast.
Page reads are not strictly snapshot-isolated. If your data is mutating rapidly while you paginate, an item may move pages between calls. For one-shot exports, page through quickly and de-dupe by id on the client.