API Pagination

When you are working with large amounts of data the API will return the data paginated. This is most common for /list and /range endpoints that may return thousands of objects.

There are three types of pagination options;

1. Cursor : The original option for pagination which uses bookmarks to move forwards and backwards between response data pages for each API request.
2. Limits : A newer option introduced in Q4 of 2022 for pagination which uses page numbers to choose which set of response data to deliver for each API request.
3. Stream : A newer option introduced in Q4 of 2022 for pagination which simply returns all the data in one response.

All API requests that have pagination options will support Type 1 pagination option. This is the original structure of delivering packages of data from large lists.

Newer API requests will support both Type 1 and Type 2 pagination options. In the API request, you can choose which type you want to use and supply the relevant variables to obtain the wanted response data.

Cursor

This is the original option and used for all API requests that required pagination options.

Backwards compatibility is built into all new API endpoints.

If you see a parameter key called pagination_type, then this is a newer endpoint and you will need to also set the additional parameter pagination_type as cursor.

The cursor method has the following options available that will affect the response data.

Key	Default (when no value)	Description
page_size	20	Number of objects to be returned. Page size can be between 1 and 1000 objects.
starting_after	Will start at the beginning of the list.	An alphanumeric string to move to the next page of objects in the list. The alphanumeric string which are the bookmarks for the beginning and end of the current list is given in the previous JSON response value under the key pagination -> previous_page and pagination -> next_page respectively.The pagination -> next_page alphanumeric string should be used here to show a list of the next page of results.
ending_before	N/A	An alphanumeric string to move to the previous page of objects in the list. The alphanumeric string which are the bookmarks for the beginning and end of the current list is given in the previous JSON response value under the key pagination -> previous_page and pagination -> next_page respectively.The pagination -> previous_page alphanumeric string should be used here to show a list of the previous page of results.
sort_by	Depends on endpoint	Sort the results by one of the object parameters. Only one parameter can be selected. The parameter options will vary with each endpoint. Check the API documentation for available options.
sort_asc	Ascending	Sorting order for the results according to the sort_by parameter. There are two options; true (ascending order) and false (descending order).The default is true (ascending).

Limits

This is a newer pagination implementation that uses the parameter page instead of starting_after and ending_before.

Key	Default (when no value)	Description
pagination_type	Should be manually set to limits
page	1	An integer for the wanted page of results. The start of the data returned will be calculated using the page_size and page query parameters for the location to start and the query parameters sort_by and sort_asc will determine the order of the data.
page_size	20	Number of objects to be returned. Page size can be between 1 and 1000 objects. The default is 20 objects.
sort_by	Depends on endpoint	Sort the results by one of the object parameters. Only one parameter can be selected. The parameter options will vary with each endpoint. Check the API documentation for available options.
sort_asc	Ascending	Sorting order for the results according to the sort_by parameter. There are two options; true (ascending order) and false (descending order).The default is true (ascending).

Stream

This is also a newer pagination implementation that simply returns all the response data without any pagination.

Exercise caution when using this option as it may lead to speed and memory issues when processing a large amount of objects in the response data. To mitigate these concerns, you should use the pagination options cursor or limits.

Key	Default (when no value)	Description
pagination_type	Should be manually set to stream
sort_by	Depends on endpoint	Sort the results by one of the object parameters. Only one parameter can be selected. The parameter options will vary with each endpoint. Check the API documentation for available options.
sort_asc	Ascending	Sorting order for the results according to the sort_by parameter. There are two options; true (ascending order) and false (descending order).The default is true (ascending).