Pagination

In this guide, we will look at how to work with paginated responses when querying the TimeZest API.

When an API response returns a list of entities, it will automatically paginate them into groups of 20 items. You can use the starting_after and ending_before parameters to request pages of items that begin and end before and after the ID of specific items. Only one of these parameters can be used at a time; using both will result in an error.

For convenience when working with the API, TimeZest will include next_page and previous_page metadata in the response. These two fields are URLs, and if their presence indicates that there are next/previous pages which are not empty. They will include any filter parameters specified for the request, so can be used directly to retrieve additional pages of results.

All results are sorted by the creation date of the records (with most recently created records first), and this sort order cannot be changed.

Example using cursors

In this example, we request the page that starts after the agent with id agnt_2FLuERxvOVglKiEzLbqW7. As a result, we get a list of three agents and can determine from the null value for next_page that we are at the end of the results.

Name
next_page
Type
string
Description
The URL of the next page of items in the response. This may be null if there are no further items.
Name
previous_page
Type
string
Description
The URL of the previous page of items in the response. This may be null if there are no further items.

Manual pagination using cURL

curl -G https://api.timezest.com/v1/agents \
  -H "Authorization: Bearer {API key}" \
  -d starting_after="agnt_2FLuERxvOVglKiEzLbqW7" \

Paginated response

{
  "object": "list",
  "next_page": null,
  "previous_page": "https://api.timezest.com/v1/agents?ending_before=agnt_pFpN9n1zwPMltSxGWRqNN",
  "data": [
    {
      "id": "agnt_pFpN9n1zwPMltSxGWRqNN",
      // ...
    },
    {
      "id": "agnt_kIOx9vDE6tR0jwS6Ay8A1"
      // ...
    },
    {
      "id": "agnt_4lzPkc8sHZJ3wuTRVxq4D"
      // ...
    }
  ]
}