> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How list endpoints in the RevyOps API page through results.

Most list endpoints (contacts, companies, people) return paged results. A few endpoints, noted below, return everything in one response instead.

## Query parameters

| Parameter   | Type    | Default | Notes                                                                                                     |
| ----------- | ------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `page`      | integer | `1`     | 1-based. A non-integer value falls back to page 1.                                                        |
| `page_size` | integer | `100`   | Capped at 100. Values above 100 are silently clamped down to 100, and values below 1 are clamped up to 1. |

## Response shape

A paged response looks like this:

```json theme={null}
{
  "count": 842,
  "total_pages": 9,
  "current_page": 1,
  "page_size": 100,
  "results": [ ... ]
}
```

* `count` is the total number of matching records, not just the ones on this page.
* `total_pages` is `count` divided by `page_size`, rounded up.
* `current_page` echoes the page you requested (or 1, if what you sent wasn't a valid page number).
* `page_size` echoes the effective page size after clamping.

If you request a page number past the last page, the response is:

```json theme={null}
{ "status": "No contacts found" }
```

## Example

```bash theme={null}
curl "https://app.revyops.com/api/public/v2/contacts?page=2&page_size=50" \
  -H "X-API-KEY: your-api-key"
```

```json theme={null}
{
  "count": 842,
  "total_pages": 17,
  "current_page": 2,
  "page_size": 50,
  "results": [
    {
      "id": 1234,
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "job_title": "VP Sales",
      "company_id": 55,
      "updated_time": "2026-09-20T14:03:11Z"
    }
  ]
}
```

## Endpoints that paginate

This applies to the contacts, contacts-master-list, companies, companies-master-list, people, and lookup-by-custom-field list endpoints (v1 and v2).

## Endpoints that don't paginate

`GET /public/emails` returns every matching email in a single array with no `page` or `page_size` support. Narrow your results with the filter parameters described in [Filtering](/api-reference/filtering) instead.