Pagination

Endpoints that return lists of data are paginated. There are two styles of pagination, and each endpoint's documentation tells you which one it uses:

• Page-based pagination, used by most endpoints. You ask for a page by its number.
• Cursor-based pagination, used by endpoints that can return very large result sets. You ask for the page that follows the one you just received.

Page-based pagination

Endpoints that use page-based pagination accept two parameters to control the windowing of a specific request:

size: number – the page size to apply. Analogous to SQL LIMIT {size}
page: number – the page index to apply, starting at 0. Analogous to SQL OFFSET {size * page}

Each endpoint has its own default page size and maximum page size, which its documentation describes.

Paginated responses include pagination metadata to allow clients to drive pagination correctly. These responses have the following shape:

{
      items: array, requested datatype
      pageNumber: number
      pageSize: number
      totalItems: number
      totalPages: number
      sortOrders: array, the sort applied to the results
}

To retrieve all the data, request page 0, then increase page by one for each request until you've requested totalPages pages.

Cursor-based pagination

Endpoints that use cursor-based pagination don't take a page number. Instead, each response includes a cursor that points to the end of the page you received, and you send that cursor back to get the next page. This keeps paging fast and consistent even when there are thousands of results.

These endpoints accept two parameters:

limit: number – the maximum number of items to return on a page. Each endpoint has its own default and maximum, which its documentation describes.
after: string – the nextCursor from the previous response. Leave it out to get the first page.

Cursor-paginated responses have the following shape:

{
      items: array, requested datatype
      pageSize: number, the number of items on this page
      hasNextPage: boolean
      hasPreviousPage: boolean
      nextCursor: string, present only when hasNextPage is true
}

To retrieve all the data, request the first page without after, then send each response's nextCursor as after in your next request. Stop when hasNextPage is false.

A few things to know:

• Treat a cursor as an opaque value, and pass it back exactly as you received it. Don't parse it or build your own.
• Results are returned in a stable order, which each endpoint's documentation describes.
• Paging only moves forward. These responses don't include a total count, so count items as you page if you need a total.
• Cursor-paginated responses don't include pageNumber, totalItems, or totalPages, and these endpoints don't accept page or size.