Pagination

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.

Parameter	Type	Description
page[limit]	number	Specify how many items to return per page. The response might have fewer results than the default number. Default: 100 Maximum: 100
page[start_cursor]	string	A `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.

{
  "data": [...],
  "page": {
    "total_count": 200,
    "has_more": true,
    "next_cursor": "WyJjcmVhdGVkX2F0X2Rlc2MiLFsiMjAyMy0xMi0yMlQwNDoxNzoxOS44ODIyMjMrMDA6MDAiLCIwOGU5M2Y3ZS1jNDFiLTRkMTctOWY4ZC04ZWFkOTZjZTg1NDQiXV0"
  }
}

Field	Type	Description
page[total_count]	number	The 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]	boolean	Indicates whether the page returned is the last one.
page[next_cursor]	string	An 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

Send a request to a resource list endpoint.
Retrieve the page[next_cursor] value from the response (only available if there is more than one page of results).
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'