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:

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:

{
  "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 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, 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.