Pagination

Integration APIs support two ways to paginate collections. The most common way to paginate is through offset-based pagination.

In some cases an API endpoint supports continuation-based pagination, as an alternative to offset-based pagination. Continuation-based pagination is often used in cases where the length of the total set of items is either changing frequently, or where the total length might not be known upfront.

All endpoints that support pagination presently support both methods of pagination.

Request parameters

📘

Continuation based requests should include the continuation token as a continuation=<continuation_token> query parameter. Limit/offset based requests should include those parameters as limit and offset query parameters respectively.

ParameterTypeDescription
continuationstringIf used, continuation token based paging will be employed. Clients MUST treat the continuation URL as opaque, which means that query options may not be changed while iterating over a set of partial results. Replace the continuation token with the value in the response to request the next page. A limit parameter may be used to limit the number of results in a page.
limitintegerRequests the result set to restrict the number of items in a page. This parameter may be used for both limit/offset and continuation based requests. If not specified, the endpoint will return a default number of items for its implementation. If a limit is requested which is greater than the maximum limit supported by the endpoint, the response will not exceed its maximum limit and will provide a pageCap in the response object which will report the maximum limit supported by the endpoint.
offsetintegerIf used, limit/offset based paging will be employed. If present, specifies the number of entries to skip for the initial page. If absent, a default value of 0 will be used. If the offset is greater than the total number of items, the response will contain no entries.

Response objects

ObjectTypeDescription
entriesarrayThe entry items in the page. If there are no entries in the page, the array will be empty.
totalCountintegerThe total number of items in the collection. In some cases the total may not be known and it is the clients responsibility to paginate the collection until no items are returned.
pageCapintegerIf a limit is requested which is greater than the maximum than the maximum limit for the endpoint, a pageCap will be present which states the actual limit asserted for the page.
limitintegerIf a limit is requested, that value will be specified here. If a limit is not requested, the default limit will be specified here.
offsetintegerIf a offset is requested, that value will be specified here.
continuationTokenstringIf another page is available after this one, this will not be null and will provide the continuation token which may be provided in the continuation query parameter of the next request to get that page.
nextPageLinkstringIf another page is available after this one, this will not be null and will provide a URL which may be called with an HTTP GET to request the next page. If limit/offset based paging is used, this link will be limit/offset based; if continuation token based paging is being used, it will be continuation based.