Pagination

​

Manual Pagination

// First page — omit cursor
const page1 = await sdk.listRecords('tasks', {
  pageSize: 25,
  sort: 'created_at:desc',
});

// page1.meta.has_more     — true if more pages exist
// page1.meta.next_cursor  — pass to the next request; null on the last page

// Next page — pass cursor from previous response
if (page1.meta.has_more) {
  const page2 = await sdk.listRecords('tasks', {
    pageSize: 25,
    sort: 'created_at:desc',
    cursor: page1.meta.next_cursor,
  });
}

​

paginateRecords(entityKey, options?) — Async Generator

for await (const record of sdk.paginateRecords('tasks', {
  filter: { status: { eq: 'open' } },
  sort: 'due_date:asc',
  pageSize: 50,
})) {
  renderTask(record);
}

​

Options

​

Safety Limits

for await (const record of sdk.paginateRecords('tasks', {
  maxPages: 10,
  maxRecords: 500,
  signal: controller.signal,
})) {
  process(record);
}

​

Error Handling During Pagination

try {
  for await (const record of sdk.paginateRecords('tasks')) {
    process(record);
  }
} catch (error) {
  // error.message includes page number and cursor for debugging
  console.error('Pagination failed:', error.message);
}

​

Page Size Limits

​

How cursors behave

• Keyset, not offset. A cursor records the position of the last record on the page (its sort value and id), so records inserted while you page never shift or duplicate what you see, and page 1,000 costs the same as page 1.
• Opaque and bound to the sort. A cursor is encrypted — it reveals nothing about the record it points at. Repeat the same sort with every cursor. A cursor sent with a different sort, altered in any way, or issued before the sorted field changed type is rejected with 422 VALIDATION_FAILED (param: "cursor") rather than silently restarting at page one.
• Long sort values. A sort value too long to fit in a cursor (several kilobytes of text) is rejected up front with 422 (param: "sort"); sort on a shorter field.
• Null ordering. Records whose sort field is unset come last when sorting ascending and first when sorting descending.
• Index-served sorts. Sorting on a field declared indexed: true reads in index order instead of sorting the whole entity. See Indexing fields.