Pagination
Some endpoints may return a large number of results, so we provide pagination to help you request only a subset of the results at a time.
Types of pagination
There are two types of pagination we use underneath:
- Page-based pagination: This method uses a paging parameter to indicate the starting point of records to return.
- Cursor-based pagination: This method utilizes a unique identifier to determine the position in the data set.
There are different advantages and disadvantages to each method, but performance wise cursor-based pagination is generally more efficient.
Currently, most of the endpoints are offset-based, but we are working on migrating all of them to be cursor-based. To make it transparent to you, we have standardized pagination in the response object to work with both methods.
Pagination in responses
When an endpoint supports pagination, the response will include a pagination
object with the following properties:
next
: The URL to the next page. This property will be omitted if the result set is empty or if the next page has no results.previous
: The URL to the previous page. This property will be omitted if the result set is empty or if there’s no previous page.first
: The URL to the first page. This property will be omitted if the result set is empty.
Here are a few examples of how the pagination
object may look like in the response:
Number of results per page
To control how many results are returned per page, you can use the perPage
query parameter. For example, to request 100 results per page, you would add ?perPage=100
to the URL.
The perPage
parameter will automatically be included in the URLs in the pagination
object, so you don’t need to worry about it when following the pagination links.