Pagination

API responses that return collections are paginated to improve performance and response size control. You can manage pagination using the query parameters described below.

Query Parameters

Parameter	Type	Default	Max	Description
`page`	integer	`1`	—	Specifies the page number to retrieve (1-based indexing)
`page_size`	integer	`10`	`100`	Number of records returned per page

Default Behavior

Pagination is 1-based
If page is not provided, the first page is returned
If page_size is not provided, 10 records per page are returned
The maximum allowed value for page_size is 100

Example Request

curl -H 'Authorization: <Access-Token>' \
     --request GET 'https://api.timeero.app/api/public/users?page=2&page_size=3'

Pagination Response Structure

{
  "meta_data": {
    "pagination": {
      "current_page": 1,
      "first_page_url": "https://api.sandbox.timeero.com/api/public/users?page=1",
      "from": 1,
      "last_page": 2,
      "last_page_url": "https://api.sandbox.timeero.com/api/public/users?page=2",
      "next_page_url": "https://api.sandbox.timeero.com/api/public/users?page=2",
      "path": "https://api.sandbox.timeero.com/api/public/users",
      "per_page": 10,
      "prev_page_url": null,
      "to": 10,
      "total": 12,
      "options": true
    }
  }
}

Pagination Fields Explanation

Field	Type	Description
`current_page`	integer	The current page number being returned
`first_page_url`	string	URL to retrieve the first page
`from`	integer	The starting record number on the current page
`last_page`	integer	The total number of available pages
`last_page_url`	string	URL to retrieve the last page
`next_page_url`	string \| null	URL to retrieve the next page, or `null` if none
`path`	string	Base endpoint URL without pagination parameters
`per_page`	integer	Number of records returned per page
`prev_page_url`	string \| null	URL to retrieve the previous page, or `null` if none
`to`	integer	The ending record number on the current page
`total`	integer	Total number of records available
`options`	boolean	Indicates pagination options are enabled

Usage Guidelines

Always use pagination for endpoints that return collections
Avoid setting page_size to the maximum unless necessary
Clients should gracefully handle empty responses for pages beyond available data