Skip to main content

​
Pagination parameters

You can control pagination using the following query parameters:
​
integer
The page of results you want to retrieve (starting from 1).
​
integer
The number of items to return per page.

​
Example usage

Here’s how to retrieve paginated results:
This retrieves the second page of team members, with 25 results per page.

​
Response structure

Paginated responses include metadata about the pagination:
Response example
​
integer
The total number of items across all pages.
​
integer
The current page number.
​
integer
The total number of pages available.
​
integer
The number of items per page.

​
Page-based lists

The other v2 lists take page and page_size instead, and return total_count, page, page_size, total_pages, next_page and prev_page at the top level, next to the array. These lists are clients, projects, project users, invoices and unbilled time entries. Invoices and unbilled time entries are always paginated: a page holds 30 items by default and 100 at most. Clients, projects and project users return every record when you send neither page nor page_size. The response still has the six pagination keys: it reports one page holding every record (page 1, page_size equal to total_count, total_pages 1, next_page and prev_page null). Send page or page_size to paginate; the default page size is then 30 and the maximum is 100.
Response example
The reports and the monthly PTO list are not paginated. They return the full set.

​
Default behavior

  • If you leave out page_number, you get the first page.
  • If you leave out page_size, each page has 30 items.

​
Best practices

  1. Start with reasonable page sizes: Use page sizes between 10-100 items for optimal performance.
  2. Handle empty results: Always check if the returned array is empty to detect the end of data.
  3. Use total_records: Use the pagination.total_records field to calculate the total number of pages needed.
  4. Implement error handling: Handle cases where the requested page doesn’t exist.