Pagination

When listing large data sets through APIs, it needs a mechanism to paginate the list of resources. We support offset pagination or cursor pagination for these "list" APIs. For example, List webhook endpoints, List unsubscribers.

Offset pagination

Most pageable resources support offset pagination.

These APIs share a common structure and accept the following query parameters:

ParameterDescription
pagePage number of the results to be returned, 1-based.
Typically, maximum 100.
limitA limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
includeTotalReturn results inside an object that contains the total result count or not.
Only use it when you want to fetch a total count, as it takes more time to count.

And return a common JSON structure:

FieldDescription
itemsAn array containing objects returned in this page.
offsetThe position of the item this page starts from, zero-based. e.g., the 11th item is at offset 10.
This value is calculated by the request parameter page and limit: offset = (page - 1) * limit.
limitSame as the request parameter limit.
lengthThe actual number of items returned in this page. i.e., items.length.
It should be less or equal to limit.
totalThe total number of items (including those that may not be returned in this page).
This field is returned only when the request parameter includeTotal is set to true.

Note

  • Commonly, these APIs have a maximum of 100 for both page and limit, which means you could only query the first 10,000 items.

Cursor pagination

There are cases that you need to iterate over all the data sets. If possible, we provide cursor pagination for these resources.

Query parameters:

ParameterDescription
limitA limit on the number of results to be returned, or number of results per page, between 1 and 100, defaults to 10.
pageAfterA cursor to fetch the next page in cursor pagination.
For example, if you make a list request, receive 100 objects and cursor.after=id:foo, your subsequent call can include pageAfter=id:foo in order to fetch the next page of the list.

Response:

FieldDescription
itemsAn array containing objects returned in this page.
limitSame as the request parameter limit.
lengthThe actual number of items returned in this page. i.e., items.length.
It should be less or equal to limit.
cursorA cursor object.
Returned only if the endpoint you requested supports cursor pagination.
cursor.afterA cursor to fetch the next page in cursor pagination.
For example, if you make a list request, receive 100 objects and cursor.after=id:foo, your subsequent call can include pageAfter=id:foo in order to fetch the next page of the list.
This field is returned only if there are more items in the list.
Clients should not store or modify the cursor on their side.

Note

  • If the response length is 0, or cursor.after is not returned, it means that there are no more items or pages.
  • Refer to the API Reference to see if they support cursor pagination.