Most requests that return multiple records are paginated. There will be a section of links with URLs to retrieve the first, next, previous, and last pages of records. Depending on how a response is paginated, it may include values for page, total_pages, total_entries, next_page, and previous_page. If the response is using cursor based pagination, page, next_page, and previous_page will always return null for all but the first and last pages.

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 ([email protected])"


Copy to Clipboard

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&ref=first",
    "next": "https://api.harvestapp.com/v2/clients?cursor=eyJhZnRlciI6eyJpZCI6MzAwN319&per_page=2000&ref=next_cursor",
    "previous": null,
    "last": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000&ref=last"
  }
}

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?cursor=eyJhZnRlciI6eyJpZCI6MzAwN319&per_page=2000&ref=next_cursor" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"


Copy to Clipboard

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&ref=first",
    "next": "https://api.harvestapp.com/v2/clients?cursor=eyJhZnRlciI6eyJpZCI6NDAwN319&per_page=2000&ref=next_cursor",
    "previous": "https://api.harvestapp.com/v2/clients?cursor=eyJiZWZvcmUiOnsiaWQiOjYwMDZ9fQ&per_page=2000&ref=previous_cursor",
    "last": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000&ref=last"
  }
}

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&ref=last" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"


Copy to Clipboard

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&ref=first",
    "next": null,
    "previous": "https://api.harvestapp.com/v2/clients?page=4&per_page=2000&ref=previous",
    "last": "https://api.harvestapp.com/v2/clients?page=3&per_page=2000&ref=last"
  }
}

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 is 2000. 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 a 422 Unprocessable Entity error code with an Invalid per_page parameter error message.

• page or cursor — An indicator for which page of records should be returned.

  • The page and cursor parameters are mutually exclusive and should not be used together. If both are provided, cursor will take precedence.

  • You should always avoid using these parameters directly, and instead rely on the values provided by the first, next, previous, and last URLs in the links section of the response. They will dynamically use page or cursor values to maximize performance of the endpoints for you.

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 ([email protected])"


Copy to Clipboard

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&ref=first",
    "next": "https://api.harvestapp.com/v2/clients?cursor=eyJhZnRlciI6eyJpZCI6ODAwNX19&per_page=1&ref=next_cursor",
    "previous": null,
    "last": "https://api.harvestapp.com/v2/clients?page=257&per_page=1&ref=last"
  }
}