Pagination
Most requests that return multiple records are paginated. If a response is paginated, the response will include values for page
, total_pages
, total_entries
, next_page
, and previous_page
, as well as a section of links
with URLs to retrieve the first
, next
, previous
, and last
pages of records.
links
section of a response instead of constructing pagination links yourself.
Paginated response example
For example, to retrieve the first page of clients, you would make the following request:

curl "https://api.harvestapp.com/v2/clients" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (yourname@example.com)"
Response:
{
"clients": [
"{2000 client objects}"
],
"page": 1,
"total_pages": 3,
"total_entries": 257,
"next_page": 2,
"previous_page": null,
"links": {
"first": "https://api.harvestapp.com/v2/clients?page=1&per_page=2000",
"next": "https://api.harvestapp.com/v2/clients?page=2&per_page=2000",
"previous": null,
"last": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000"
}
}
In that response, you can see the included pagination metadata values. To retrieve the next page of clients, use the next
URL provided in the links
section:

curl "https://api.harvestapp.com/v2/clients?page=2&per_page=2000" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (yourname@example.com)"
Response:
{
"clients": [
"{2000 client objects}"
],
"page": 2,
"total_pages": 3,
"total_entries": 257,
"next_page": 2,
"previous_page": 1,
"links": {
"first": "https://api.harvestapp.com/v2/clients?page=1&per_page=2000",
"next": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000",
"previous": "https://api.harvestapp.com/v2/clients?page=1&per_page=2000",
"last": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000"
}
}
To retrieve the final page of clients, use the last
URL provided in the links
section:

curl "https://api.harvestapp.com/v2/clients?page=3&per_page=2000" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (yourname@example.com)"
Response:
{
"clients": [
"{57 client objects}"
],
"page": 3,
"total_pages": 3,
"total_entries": 257,
"next_page": null,
"previous_page": 2,
"links": {
"first": "https://api.harvestapp.com/v2/clients?page=1&per_page=2000",
"next": null,
"previous": "https://api.harvestapp.com/v2/clients?page=2&per_page=2000",
"last": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000"
}
}
Pagination parameters
Paginated endpoints use the following optional parameters:
-
per_page
— The number of records to return per page.-
The default and maximum
per_page
value for API requests is2000
. If you want to receive the maximum number of records per page, do not provide a value — the default is always the maximum number supported. -
If you provide a value for
per_page
that is too large, you will receive a422 Unprocessable Entity
error code with anInvalid per_page parameter
error message.
-
-
page
— An indicator for which page of records should be returned.- If possible, you should avoid using the
page
parameter directly, and instead rely on the values provided by thefirst
,next
,previous
, andlast
URLs in thelinks
section of the response.
- If possible, you should avoid using the
per_page
parameter example
To retrieve fewer records than the maximum page size supported, add the per_page
parameter to the URL. For example, to retrieve the most recently created client:

curl "https://api.harvestapp.com/v2/clients?per_page=1" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (yourname@example.com)"
Response:
{
"clients": [
"{1 client object}"
],
"page": 1,
"total_pages": 257,
"total_entries": 257,
"next_page": 2,
"previous_page": null,
"links": {
"first": "https://api.harvestapp.com/v2/clients?page=1&per_page=1",
"next": "https://api.harvestapp.com/v2/clients?page=2&per_page=1",
"previous": null,
"last": "https://api.harvestapp.com/v2/clients?page=257&per_page=1"
}
}