List resources in the API are paginated to allow clients to traverse data over multiple requests. Dovetail’s API uses cursor-based pagination for efficient navigation through large datasets. By default, list resources return 100 items per API call which is also the maximum limit that can be requested.

​
Parameters for paginated requests

Include pagination parameters in the query string of the GET request.
ParameterTypeDescription
page[limit]numberSpecify how many items to return per page. The response might have fewer results than the default number.

Default: 100
Maximum: 100
page[start_cursor]stringA next_cursor value returned in a previous response. Treat this as an opaque value.

Not specifying this parameter will return results from the start of the list.

​
Pagination response object

If an endpoint supports pagination, the response object structure will look like the following.
JSON
{
  "data": [...],
  "page": {
    "total_count": 200,
    "has_more": true,
    "next_cursor": "WyJjcmVhdGVkX2F0X2Rlc2MiLFsiMjAyMy0xMi0yMlQwNDoxNzoxOS44ODIyMjMrMDA6MDAiLCIwOGU5M2Y3ZS1jNDFiLTRkMTctOWY4ZC04ZWFkOTZjZTg1NDQiXV0"
  }
}
FieldTypeDescription
page[total_count]numberThe total number of items contained in all pages. This number may vary as the client requests subsequent pages, owing to the possibility of new records being added or removed.
page[has_more]booleanIndicates whether the page returned is the last one.
page[next_cursor]stringAn opaque string usable for fetching the subsequent page of results by utilizing its value as the page[start_cursor] parameter in the same endpoint.
This value is null when there is no more result to fetch.

​
How to send a paginated request

  1. Send a request to a resource list endpoint.
  2. Retrieve the page[next_cursor] value from the response (only available if there is more than one page of results).
  3. Send a subsequent request to the endpoint adding the value from page[next_cursor] to the page[start_cursor] param in the query string.
curl -G --location --request GET \
  --data-urlencode "page[start_cursor]=WyJjcmVhdGVkX2F0X2Rlc2MiLFsiMjAyMy0xMi0yMlQwNDoxNzoxOS44ODIyMjMrMDA6MDAiLCIwOGU5M2Y3ZS1jNDFiLTRkMTctOWY4ZC04ZWFkOTZjZTg1NDQiXV0" \
  'https://dovetail.com/api/v1/projects' \
  --header 'Authorization: Bearer <DOVETAIL_API_TOKEN>' \
  --header 'Content-Type: application/json'