Skip to main content

Pagination

Instance search uses cursor-based pagination (keyset), not page/offset. This gives consistent results even when instances are being created or updated between pages.

Request​

{
  "page": {
    "limit": 50,
    "cursor": null
  }
}
  • limit: Results per page. Default: 50, maximum: 200.
  • cursor: Opaque string from the previous page's nextCursor. Omit or pass null for the first page.

Response​

{
  "results": [ ... ],
  "nextCursor": "eyJzdGFydGVkQXQiOiIyMDI2...",
  "stats": {
    "returned": 50,
    "limit": 50
  }
}
  • results: Current page of instances.
  • nextCursor: Pass as cursor on the next request. null when there are no more results.

Iterating all pages​

let cursor = null;

do {
  const response = await fetch('/v1/instances/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      filter: { "variables.status": "in_review" },
      page: { limit: 200, cursor },
    }),
  }).then(r => r.json());

  for (const instance of response.results) {
    // process instance
  }

  cursor = response.nextCursor;
} while (cursor !== null);

Why not offset?​

Offset-based pagination (page=2, offset=100) has two problems at scale:

  • Inconsistency: A new instance inserted while you're reading shifts pages — you may skip records or see duplicates
  • Performance: OFFSET 10000 forces the database to scan and discard 10,000 rows on every request

Cursor pagination avoids both by resuming exactly from where it left off using an indexed key comparison.

Approximate count​

The response does not include totalCount by default (counting all matching rows is expensive). Include "count": true in the request body to get an estimatedCount from the query planner — fast, but not exact.