Skip to main content
Every deep, filter, and lookalike search produces a search_id. These endpoints read its results: poll a task with GET /search/status/{task_id}, page through rows with POST /search/query, build a CSV with POST /search/export, download it with GET /search/download, and read your result ceiling with GET /search/limits.

API Reference

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

Get search status

Poll the progress and result of a deep search or an export.
task_id is the value returned by Start Deep Search (agentic_search_{search_id}) or by Export (search_export_{search_id}). Lookalike tasks use GET /search/lookalike/{task_id}; this endpoint refuses them. A task answers the person, API key or OAuth app that started it, the team it was started in (its members, and organization admins and API keys working in that team), and anyone who can open its search. Anyone else gets 404, as for a task that does not exist. GET /job-status/{job_id} answers these tasks the same way.
GET /search/deep-search-status/{task_id} is deprecated and returns a Deprecation header. Use GET /search/status/{task_id}, which returns the same response.

Task statuses

running is the only in-progress status. Poll every 10 seconds or slower, and stop on any other status, including values not listed here. A search that finds nothing does not always end completed:
  • A query_only deep search with no matches ends completed with total_results: 0.
  • A CSV deep search or an export with no rows to write ends failed, with a message in error. This includes searches whose every row was excluded.
A deep search started above your organization’s concurrency limit also ends failed. See Concurrency limits.

Status response

Fields without a value are returned as null.
For a complete polling loop that honors Retry-After and stops at a deadline, see Deep Search → Example usage.

Query search results

Page through the results of a completed search as JSON.
Send the search_id on the first request, then send only {"cursor": "..."} for each next page:
POST /search/query also runs new searches from filters or a natural language query. For those inputs, see Filter Search → Search query. A request with search_id runs the saved search’s query again and starts a new set of pages under the same search_id. A replay carries:
  • The saved query and its mode.
  • For a lookalike search, its ranking and its seed people, who stay excluded from results.
A replay does not carry:
  • max_results. It defaults to 1,000, whatever the original search used. Send it again.
  • page_size, output_shape, and exclusions. Send them on the first request.
The saved search must be completed. Replaying a search that is still running, or one that failed, returns an error. A replay does not save a new search. A person replays the searches they can open in the app. An API key or OAuth app replays the searches it ran, those of the team it works in, and those shared with that team. Replaying any other search fails as if it did not exist; see Search errors. Export and exclusion lists built from a search follow the same rule.

Paginate with cursors

Each page returns has_more and, while more rows remain, a next_cursor. Send {"cursor": "..."} alone to get the next page. Mode, page size, output shape, and exclusions carry over.
  • Stop when has_more is false. The last page omits next_cursor and cursor_expires_in_seconds; they are not returned as null.
  • A page can hold fewer rows than page_size, even zero, while has_more is true. Keep paging.
  • Each cursor works once.
  • Send each cursor only after the previous response arrives.
  • A cursor expires cursor_expires_in_seconds after it is issued (30 minutes), or when an exclusion list it applies is deleted. When a cursor fails, start again from the search_id.
  • A 429 or 503 does not use up a cursor: send it again after Retry-After, or after a few seconds if the header is absent.
  • A cursor request accepts only cursor. Sending a query, paging, or exclusion field with it fails the request. mode, persist_history, and location_expansion_enabled are ignored, as are fields sent as null or false.
  • A cursor works only for the organization that created it.

Query response

Fields without a value are omitted from the response, not returned as null. Inside results, rows keep their null values.

Constraints the search did not apply

unmet_constraints lists the parts of the query the search did not apply, usually as field names: Sixtyfour has no data for the field, or dropped the constraint because the full query matched too few rows. Results can include rows outside these constraints. GET /search/filter-capabilities lists every field you can filter on.

Export search results

Generate a CSV from any completed search: deep, filter, or lookalike.
An export runs the saved query again, as a replay does, so its rows can differ from the CSV a deep search wrote.
  1. Call POST /search/export and save the task_id.
  2. Poll GET /search/status/{task_id} until it is completed, then read resource_handle_id.
  3. Download the CSV with GET /search/download.
One export per search_id runs at a time; while it runs, poll search_export_{search_id} instead of starting another. An export with parsed_query gets a new ID each time.

CSV columns

A CSV has one row per result, with the same columns as output_shape: "workflow" rows.

Download search results

Get a signed URL for the CSV of a completed CSV deep search or export.
The response contains url.
Fetch the returned url with your x-api-key header; the signed token does not replace authentication. Disable redirects when sending your API key.
Signed URLs expire after 15 minutes. Download the file right away or request a new URL.

Spreadsheet-safe CSV

By default, the file is escaped so that opening it in a spreadsheet never runs a formula:
  • Every field is quoted.
  • A cell that starts with =, +, -, @, a tab, or a line break (or a full-width =, +, -, or @) gets a leading '. A phone number +14155550123 arrives as '+14155550123. Negative numbers such as -12.5 are left as they are.
  • The response carries the header X-Spreadsheet-Safe: 1.
To read the file as data, append ?spreadsheet_safe=false to the url. The file then arrives exactly as stored, without the header. A file that cannot be escaped (not valid CSV, or too large) downloads only with ?spreadsheet_safe=false.

Search limits

Return the maximum number of results your credential can request, retrieve, or export in one search.
API keys get 5,000 unless your organization has a custom ceiling. The ceiling applies to max_results on POST /search/start-deep-search, POST /search/query, and POST /search/export; a higher value fails the request.

Rate limits

For per-endpoint limits, see Rate Limits.

Pricing

See Credit Costs for more information.
For new integrations, see Search Results.