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 is 100.
  • The default and maximum per_page value for Reports API requests is 1000.

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"
  }
}