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 download enriched results as a CSV. Use this reference for request/response schemas, parameters, status codes, and copy-paste examples.
| Name | Type | Required | Description |
|---|
| x-api-key | string | Yes | Your Sixtyfour API key |
| Content-Type | string | For POST requests | Must be application/json |
Start Deep Search
Submit a natural language query to start an agentic search. Returns a task_id for polling.
POST https://api.sixtyfour.ai/search/start-deep-search
Request Body
| Field | Type | Required | Description |
|---|
| query | string | Yes | Natural language description of the people or companies to find |
| mode | string | No | Search mode — currently "people" (default) |
| max_results | integer | No | Maximum number of results to return (default: 1000) |
| search_id | string | No | Optional custom identifier for the search task |
Example Request
{
"query": "VP of Engineering at Series B SaaS startups in New York",
"mode": "people",
"max_results": 500
}
Response (200)
{
"task_id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
"status": "queued",
"message": "Search started successfully"
}
Save the task_id — you’ll need it to poll for status.
Get Deep Search Status
Poll for progress and results of a running or completed search.
GET https://api.sixtyfour.ai/search/deep-search-status/{task_id}
Path Parameters
| Name | Required | Description |
|---|
| task_id | Yes | The task ID returned by Start Deep Search |
Response (200)
{
"task_id": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
"status": "completed",
"start_time": "2026-02-18T10:00:00Z",
"current_phase": 3,
"progress_message": "Finalizing results",
"close_time": "2026-02-18T10:04:32Z",
"resource_handle_id": "rh_7f3d29a1-4b22-4c88-a6f5-1234abcd5678",
"total_results": 187,
"exported_count": 187,
"error": null
}
Status Values
| Status | Description |
|---|
| queued | Search is waiting to start |
| running | Search is actively running |
| completed | Search finished — resource_handle_id is now available |
| failed | Search encountered an error — check the error field |
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, copy the resource_handle_id and pass it to the Download endpoint.
Download Search Results
Get a signed URL to download the result CSV for a completed search.
GET https://api.sixtyfour.ai/search/download
Query Parameters
| Name | Required | Description |
|---|
| resource_handle_id | Yes | The resource handle ID from the completed status response |
Response (200)
{
"url": "https://storage.googleapis.com/sixtyfour-results/signed-url-here",
"bucket": "sixtyfour-results",
"path": "org_abc123/search/e3b0c442-98fc-1c14-9afb-f4c8996fb924/results.csv"
}
The storage backend and URL format may vary. Use the url field 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.
Example Usage
# 1. Start a deep search
curl -X POST "https://api.sixtyfour.ai/search/start-deep-search" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "VP of Engineering at Series B SaaS startups in New York",
"mode": "people",
"max_results": 500
}'
# 2. Poll for status (use task_id from step 1)
curl -X GET "https://api.sixtyfour.ai/search/deep-search-status/TASK_ID" \
-H "x-api-key: YOUR_API_KEY"
# 3. Download results (use resource_handle_id from step 2)
curl -X GET "https://api.sixtyfour.ai/search/download?resource_handle_id=RESOURCE_HANDLE_ID" \
-H "x-api-key: YOUR_API_KEY"
