What is Pagination?

Returning a large set of results can be taxing on both the client and server. To overcome this, pagination has been enabled by default on all queries. The maximum number of results that will be returned is 1000. If the API user wants to reduce the number of results, the user can pass along additional parameters to the endpoint.

limit: Integer

The number of results that are returned. As mentioned in the section above, the maximum limit is 1000 results. If the API user requests more than 1000 results, only the first 1000 results will be returned.

In the example below, the limit is set to 10, so only the first 10 results will be returned.

limit example:

Python
q={
  "limit": 10,
  ...
}

offset: Integer

The number of results that are skipped. If the API users wants to skip the first 40 results, they would set the offset to 40. If the API user does not want to skip any results, they would set the offset to 0 or not include it in the request.

If the given offset is larger than the number of available results, no results will be returned and no error will be given.

offset example:

Python

q={
  ...
  "offset": 40
}

Limit and Offset Parameters

In the example below, the results are set to a limit of 10, with an offset of 40. These parameters will cause the output to show the results on the fifth page, with each page containing 10 results.

The output will include the offset given to the query. This will help generate pagination queries for future requests.

Query parameters example:

Python
q={
  "limit": 10,
  "offset": 40
}

Query parameters output:

JSON
{
  "count": 10,
  "total_results": 15000,
  "offset": 40,
  "results": [{...}],
  "errors": null
}

To get the page numbers and number of pages available, the API user can use the following equations:

Equation Output
ceil( total_results / limit ) number_of_pages
( offset / limit ) + 1 current_page

The count and limit may not always be equal. The number of results may be less than the given limit. Therefore, do not use the count value to calculate the paging parameters.