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:

Parameter

Location

Type

Description

$top

query

int

A 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.

$skip

query

int

The 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.

$expand

query

string

A comma-delimited list of expansion properties (see Expansion)

$orderby

query

string

A 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:

Property

Type

Description

items

array

An array of zero or more endpoint specific objects (e.g., an Activist Code)

count

int

Total number of items available at this endpoint using the filters specified. This can be greater than the number of items in the items array.

nextPageLink

string

An 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
}