Pagination

Most API endpoints have “list” API methods that allow you to retrieve a large set of data (e.g. list Activist Codes, list Survey Question, etc.). These endpoints share a common pattern for requests and responses.

Paginated endpoints accept the following optional parameters:

ParameterLocationTypeDescription
$topqueryintA limit on the number of records to return in a single request, similar to a page size. This can be a value between 1 and the maximum $top value for a particular endpoint, typically 200. If no $top value is specified, an endpoint’s default $top size is used, typically 50. If an endpoint has a default $top but no maximum $top, you can retrieve all values by sending the $top parameter with no values (e.g., resources?$top=). The maximum and default values are documented for each endpoint.
$skipqueryintThe number of records in a collection that should be skipped and not included in the result. If specified, must be greater than or equal to 0. For example, if you have a collection of 100 items and specify a $skip value of 10, the endpoint will return resources starting at 11.
$expandquerystringA comma-delimited list of expansion properties (see Expansion)
$orderbyquerystringA comma-delimited list of properties and sort direction (asc or desc) to order results by before applying pagination filters. Defaults to asc.

Paginated endpoints share a common response format as well. The endpoints will return an object with the following properties:

PropertyTypeDescription
itemsarrayAn array of zero or more endpoint specific objects (e.g., an Activist Code)
countintTotal number of items available at this endpoint using the filters specified. This can be greater than the number of items in the items array.
nextPageLinkstringAn absolute URL at which additional records can be retrieved, if additional records are available. This will be the same as the request’s URL but with adjusted or appended $skip and $top values.

If no results are returned, an HTTP Status Code 200 OK is returned with the items array empty, count property equal to 0, and the nextPageLink null:

{
  "items": [],
  "nextPageLink": null,
  "count": 0
}