Retrieving particular ranges of data

API endpoints which are expected to return large numbers of results will use pagination to return a limited number of items at a time.

We use two parameters to provide pagination functionality: limit and offset.

  • limit controls the maximum number of results that an endpoint can return. The default value for limit is documented on each specific endpoint.
  • offset controls how many results to skip over in your results. By default, it is always 0.

When querying all results, your initial call should pass an offset of 0. If the number of results you receive is less than the limit you passed (or the default limit if none was passed explicitly), you have reached the end of the result set and can end pagination. Otherwise, make another API call with a new offset, set to the previous offset + limit to get the next page, and then repeat until you are at the end of the list.

For example, if there were 122 records available, your queries would look something like this:

GET /v2/objects/people/records?limit=50             # Results 1 to 50
GET /v2/objects/people/records?limit=50&offset=50   # Results 51 to 100
GET /v2/objects/people/records?limit=50&offset=100  # Results 101 to 122, less than limit, stop here