# Pagination

Search endpoints return **25 results per page** by default. Set `per_page` to `50` or `100` for
bigger pages. Whatever the page size, a search reaches its first **25,000 results**, so the deepest
page is 1,000 at 25 per page, 500 at 50 and 250 at 100.

`page` and `per_page` are top-level request fields (`page` is 1-based and defaults to `1`,
`per_page` defaults to `25`); every filter lives nested under `filters`:

```bash
curl --request POST \
  --url https://api.getprospect.com/v2/people/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "filters": {
    "person_job_title": {
      "include": [
        "CEO"
      ]
    }
  },
  "page": 2,
  "per_page": 50
}
'
```

The response `metadata.pagination` block tells you exactly where you are - use it instead of
guessing from the page size:

```json
{
  "success": true,
  "data": [
    ...
  ],
  "metadata": {
    "timestamp": "2026-07-25T14:02:31.000Z",
    "sort_by": "followers",
    "sort_direction": "desc",
    "pagination": {
      "page": 2,
      "per_page": 50,
      "total_pages": 4,
      "max_page": 500,
      "truncated": false,
      "total_count": 187,
      "total_is_estimate": false
    }
  }
}
```

`data` holds the page's results - 50 person objects here - elided above to keep the focus on the
pagination block. See the [Person object](https://getprospect.com/api-docs/person-object.md) reference for their shape.

Stop iterating once `pagination.page >= pagination.total_pages`, or once you have read
`pagination.total_count` results - do not rely on "this page came back short" as your stop
condition, since a page shorter than `per_page` only happens on the last page anyway once you're
tracking `total_pages`.

> **`truncated` and `max_page`**
>
> `max_page` is the deepest page you can request at this `per_page` (1,000, 500 or 250).
> `total_pages` never goes past it, while `total_count` is always the real number of matches. When
> a search matches more than 25,000 results, `truncated` is `true`: paging to `total_pages` reads
> only the first 25,000. Narrow the filters (for example by location, seniority or company) and run
> each slice to reach the rest.

> **`per_page` and enrichment**
>
> On People Search, `per_page` above `25` can't be combined with `enrich_email` or
> `enrich_phone`: the request fails with a validation error. Search at 50 or 100 per page, then
> reveal contacts with [People Bulk Enrich](https://getprospect.com/api-docs/people-bulk-enrich.md), or keep `per_page` at
> `25` when enriching in the search itself.

> **`total_is_estimate`**
>
> On People Search, `total_is_estimate` is `true` when a `max_person_per_company` cap made an
> exact count too expensive to compute over the full result set - treat `total_count` as an upper
> bound in that case. Company Search has no cap option, so its `pagination` block always reports
> an exact `total_count` and omits this field.