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.
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_onlydeep search with no matches endscompletedwithtotal_results: 0. - A CSV deep search or an export with no rows to write ends
failed, with a message inerror. This includes searches whose every row was excluded.
failed. See Concurrency limits.
Status response
Fields without a value are returned as
null.
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.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.
Replay a saved search
A request withsearch_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.
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.
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 returnshas_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_moreisfalse. The last page omitsnext_cursorandcursor_expires_in_seconds; they are not returned asnull. - A page can hold fewer rows than
page_size, even zero, whilehas_moreistrue. Keep paging. - Each cursor works once.
- Send each cursor only after the previous response arrives.
- A cursor expires
cursor_expires_in_secondsafter it is issued (30 minutes), or when an exclusion list it applies is deleted. When a cursor fails, start again from thesearch_id. - A
429or503does not use up a cursor: send it again afterRetry-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, andlocation_expansion_enabledare ignored, as are fields sent asnullorfalse. - 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.
Example: page through a search
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.
- Call
POST /search/exportand save thetask_id. - Poll
GET /search/status/{task_id}until it iscompleted, then readresource_handle_id. - Download the CSV with
GET /search/download.
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 asoutput_shape: "workflow" rows.
Download search results
Get a signed URL for the CSV of a completed CSV deep search or export.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.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+14155550123arrives as'+14155550123. Negative numbers such as-12.5are left as they are. - The response carries the header
X-Spreadsheet-Safe: 1.
?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.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.Related
For new integrations, see Search Results.