This is the current API V2 documentation. For the legacy API V1 documentation, click here.
Pagination
Parameters
All collection endpoints are paginated with the following optional parameters:
Parameter | Type | Default | Range | Description |
---|---|---|---|---|
page |
integer | 1 | 1 or more | The page number to use in pagination. |
per_page |
integer | (see below) | 1 to (see below) | The number of records to return per page. |
- The default and maximum
per_page
value for general API requests is100
. - The default and maximum
per_page
value for Reports API requests is1000
.
Paging 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": [
"{100 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=100",
"next": "https://api.harvestapp.com/v2/clients?page=2&per_page=100",
"previous": null,
"last": "https://api.harvestapp.com/v2/clients?page=3&per_page=100"
}
}
In that response, you can see that the total_pages
is 3
, and that the next_page
is 2
. To retrieve the next page of clients, add page=2
to the URL:

curl "https://api.harvestapp.com/v2/clients?page=2" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Harvest-Account-Id: $ACCOUNT_ID" \
-H "User-Agent: MyApp (yourname@example.com)"
Response:
{
"clients": [
"{100 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=100",
"next": "https://api.harvestapp.com/v2/clients?page=3&per_page=100",
"previous": "https://api.harvestapp.com/v2/clients?page=1&per_page=100",
"last": "https://api.harvestapp.com/v2/clients?page=3&per_page=100"
}
}
To retrieve the final page of clients, change the page
parameter to 3
:

curl "https://api.harvestapp.com/v2/clients?page=3" \
-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=100",
"next": null,
"previous": "https://api.harvestapp.com/v2/clients?page=2&per_page=100",
"last": "https://api.harvestapp.com/v2/clients?page=3&per_page=100"
}
}
Per page example
To decrease the number of records returned, 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"
}
}
Putting it together
You can add both the page
and the per_page
parameters to the URL to retrieve a specific number of objects from a specific page. For example, to get a single client from page 50
:

curl "https://api.harvestapp.com/v2/clients?page=50&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": 50,
"total_pages": 257,
"total_entries": 257,
"next_page": 51,
"previous_page": 49,
"links": {
"first": "https://api.harvestapp.com/v2/clients?page=1&per_page=1",
"next": "https://api.harvestapp.com/v2/clients?page=51&per_page=1",
"previous": "https://api.harvestapp.com/v2/clients?page=49&per_page=1",
"last": "https://api.harvestapp.com/v2/clients?page=257&per_page=1"
}
}