Skip to main content

Use case

Turn natural language into a targeted list of people or companies — without manual prospecting. These endpoints let you submit a query, track progress asynchronously, and either browse results as paginated JSON or download them as a CSV.

API Reference

See the full request/response schema and parameters in the API Reference.

Pricing

See Credits & Pricing Guide for credit costs.

Errors

For error responses (400, 403, 404, 409, 429, etc.), see Handling Errors.
Submit a natural language query to start an agentic search. Returns a task_id for polling.

Example request

Save the task_id returned in the response — you’ll need it to poll for status.
Each organization can run up to 5 concurrent deep searches. Additional requests receive a 429 response until an in-flight search completes.

Get search status

Poll for progress and results of a running or completed search.
task_id is the value returned by Start Deep Search or Export.

Status values

Polling recommendations

  • Poll every 10–15 seconds for active searches
  • Stop polling when status is completed or failed
  • Use progress_message to show users what the agent is currently doing
Once status is completed, use search_id with /search/query for paginated JSON, or resource_handle_id with /search/download for the CSV.

Download search results

Get a signed URL to download the result CSV for a completed search.
Pass resource_handle_id (the value returned in the completed status response) as a query parameter.
The storage backend and URL format may vary. Use the url field in the response directly for downloading — it is always a valid signed URL regardless of the underlying storage provider.
Signed URLs expire after 15 minutes (900 seconds). Download the file immediately or request a new URL before it expires.

Query search results

Browse results from a completed deep search as paginated JSON.
This endpoint is shared with filter search. Pass search_id to browse a completed deep search, or use simple_filters/filters/parsed_query for fresh searches. For pagination semantics, request flow, and the effective result cap, see Filter Search → Search query.

Example: browse deep search results

Example: next page

Cursor requests must send only {"cursor": "..."}. Do not include search_id, page_size, or other fields.
/search/query also accepts exclude_entity_ids and exclude_list_ids on the first request to suppress known people or companies from results. A search_id stores the query, not exclusions — pass exclusions again when browsing its results. See Search Exclusions.

Export search results

Generate a CSV from a completed search. Runs asynchronously — poll for status, then download.
Provide search_id to export an existing search, or parsed_query for a direct query (advanced) — not both.

Export flow

  1. POST to /search/export with search_id — receive task_id.
  2. Poll GET /search/status/{task_id} until completed — response includes resource_handle_id.
  3. Download via GET /search/download?resource_handle_id=....
If an export is already in progress for the given search_id, the API returns 409. Poll the existing task_id instead of starting a new export.

Example usage