Pagination
Work with cursor-based list responses.
List endpoints return one page of objects at a time. Results are returned in reverse chronological order, with the newest objects first.
Pagination is controlled by the API. Use the next_page_url and previous_page_url values returned in the response to move through the result set, and treat page tokens as opaque values. Do not parse, edit, or construct page tokens yourself.
Start with the collection URL as-is. The API returns the first page with its default page size, and the response tells you how to continue.
List response shape
{
"object": "list",
"data": [],
"next_page_url": "/v1/contacts?page_token=...",
"previous_page_url": null
}The data array contains the objects for the current page. If next_page_url is present, more results are available after this page. If it is null, you have reached the end of the list. previous_page_url can be used to move back toward newer results when it is present.
Request the first page
curl "https://api.getmateo.com/v1/employees" \
--header "Authorization: Bearer <your_api_token>" \
--header "hellomateo-version: 2026-07-01"Example response:
{
"object": "list",
"data": [
{
"id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
"display_name": "Mia Meyer",
"username": "mia.meyer",
"full_name": "Mia Meyer",
"email": "mia@example.com",
"user_id": "018f2f82-4f7a-7a2f-9c4e-1123456789ab",
"is_admin": false,
"signature": null,
"organisation_id": "018f2f82-4f7a-7a2f-9c4e-2123456789ab",
"locale": "de",
"enable_shortcuts": true,
"is_web_push_enabled": false,
"is_mobile_push_enabled": false,
"has_mobile_device": false,
"is_active": true,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
},
],
"next_page_url": "/v1/employees?page_token=<opaque_page_token>",
"previous_page_url": null,
}Request the next page
Use the returned next_page_url with the same API origin:
curl "https://api.getmateo.com/v1/employees?page_token=<opaque_page_token>" \
--header "Authorization: Bearer <your_api_token>" \
--header "hellomateo-version: 2026-07-01"Example response:
{
"object": "list",
"data": [],
"next_page_url": null,
"previous_page_url": "/v1/employees?page_token=<opaque_previous_page_token>",
}Prefer using the returned page URL directly. If your client needs to build the request URL itself, copy the returned page_token unchanged into the same endpoint with the same filters and includes. If you change filters, includes, or page size, a previously returned page token may no longer be valid for that request shape.
Optional query parameters
Most integrations do not need to pass pagination parameters on the first request.
| Parameter | Type | Description |
|---|---|---|
page_token | string | Opaque cursor returned by a previous page. Prefer using next_page_url or previous_page_url directly. |
limit | integer | Optional page-size override. Defaults to 10, maximum 100. Omit unless your integration needs a custom size. |
Endpoint-specific list parameters are documented in the API reference.
Count badges
The public API does not return exact total counts for list endpoints. If your UI needs a badge count, request a bounded page such as limit=50 and treat next_page_url as the has-more signal: show 50+ when it is present. See Show Count Badges for examples.