Pagination

Load more results from the same search

Reuse thread_id when loading more results. Changing the criteria starts a new search without thread_id.

  • When to offer Load more: Offer Load more when has_more_results is true. When false, do not request another page in the same thread. Do not infer availability from the result count or stop_reason alone.
  • Request the next page. Send the saved thread_id with limit and offset. Omit fixed search criteria or pass their saved values. To change those criteria, start a new search with no thread_id. Request pages sequentially and deduplicate by a stable profile ID.
  • Set options for this page. You can change profile inclusion and exclusion lists, contact filters and reveals, freshness, insights, response formatting, and the time budget. The API applies page filters before the offset. See all pagination options and errors.
  • Retry a page: Retry 429 and transient 5xx responses with backoff. Keep the same thread_id and pagination parameters when retrying a page; do not start a new search.

Why the search stopped

Use stop_reason to explain why this response stopped. A short page alone does not mean there are no more candidates.

stop_reasonWhat it meansWhat to show next
target_reachedThe initial search reached its target, or the saved page filled and another matching candidate is available.This does not mean the pool is exhausted.
time_budget_exhaustedThe search or page filter reached its time budget while work remained.Use has_more_results to decide whether to request another page.
candidate_pool_exhaustedThe available candidates have been evaluated and no additional matching results remain.Start a new search with broader requirements.

Request example

{
  "thread_id": "THREAD_ID_FROM_RESPONSE",
  "limit": 10,
  "offset": 10
}

Did this page help you?