Skip to main content
The search runs asynchronously: submit the query, poll for progress, then download a CSV or page through the results as JSON. Use it for prospecting and list building when you can describe the audience in words. To query structured fields directly, use Filter Search. To find people similar to an existing list, use Lookalike Search.

Core concepts

Execution flows

CSV download

  1. Start a search with POST /search/start-deep-search and save the task_id.
  2. Poll GET /search/status/{task_id} until status is completed. The response includes resource_handle_id. Any status other than running or completed means the search stopped; see Task statuses.
  3. Request a signed URL with GET /search/download and fetch the CSV. The URL expires after 15 minutes.

Paginated JSON

  1. Start a search with output_mode: "query_only" and save the task_id.
  2. Poll GET /search/status/{task_id} until status is completed, then read search_id.
  3. Page through results with POST /search/query, sending each next_cursor until has_more is false. Send max_results again on the first request; see Replay a saved search.
  4. Optionally generate a CSV from the same search_id with POST /search/export.

Quick start

For new integrations, see Deep Search Overview.