> ## Documentation Index > Fetch the complete documentation index at: https://docs.sixtyfour.ai/llms.txt > Use this file to discover all available pages before exploring further. # Deep Search Overview > Run agentic deep searches with natural language queries to find people or companies at scale. ## Use case Use the Search API to find people or companies using a natural language query — no manual list building required. The search runs asynchronously: you submit a query, poll for progress, and either browse results as paginated JSON or download them as a CSV. Ideal for prospecting, building targeted lead lists, or discovering contacts that match specific criteria across the web. ## Core concepts | Term | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `task_id` | Unique identifier returned when a search starts; used to poll for status | | `resource_handle_id` | Identifier for the result file, available once the search completes | | `mode` | Search mode — currently `"people"` (default) to find individual contacts | | `max_results` | Upper bound on how many results to return (default: 1000) | | `output_mode` | Controls result delivery — `"csv"` (default) produces a downloadable file, `"query_only"` lets you browse results as paginated JSON via `/search/query` | | `search_id` | Identifier for a completed search. Use with `/search/query` to browse results or `/search/export` to generate a CSV | ## Execution flows ### CSV download ```mermaid theme={null} theme={null} flowchart LR A[Start Deep Search] --> B[Poll Status] B --> C[Download CSV] ``` 1. Start — `POST /search/start-deep-search`. See [Start Deep Search](/api-reference/search/search-endpoints#start-deep-search). Submit your natural language query and receive a `task_id`. 2. Poll — `GET /search/status/{task_id}`. See [Get Search Status](/api-reference/search/search-endpoints#get-search-status). Poll until `status` is `completed`; the response includes `resource_handle_id`. 3. Download — `GET /search/download`. See [Download Search Results](/api-reference/search/search-endpoints#download-search-results). Request a signed URL with `resource_handle_id`, then download the CSV. The signed URL expires in 15 minutes. ### Paginated JSON ```mermaid theme={null} theme={null} flowchart LR A[Start Deep Search] --> B[Poll Status] B --> C[Browse JSON] C --> D[Export CSV] ``` 1. Start — `POST /search/start-deep-search` with `output_mode: "query_only"`. See [Start Deep Search](/api-reference/search/search-endpoints#start-deep-search). Receive a `task_id`. 2. Poll — `GET /search/status/{task_id}`. See [Get Search Status](/api-reference/search/search-endpoints#get-search-status). When `status` is `completed`, note the `search_id` from the response. 3. Browse — `POST /search/query`. See [Query Search Results](/api-reference/search/search-endpoints#query-search-results). Send the `search_id` to get paginated JSON results and use `cursor` for next pages. 4. Export *(optional)* — `POST /search/export`. See [Export Search Results](/api-reference/search/search-endpoints#export-search-results). Generate a CSV from the same `search_id`. ## Quick start ```bash cURL theme={null} # 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/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" ``` ```python Python theme={null} import requests import time API_KEY = "YOUR_API_KEY" BASE_URL = "https://api.sixtyfour.ai" headers = { "x-api-key": API_KEY, "Content-Type": "application/json" } # 1. Start the search start_response = requests.post( f"{BASE_URL}/search/start-deep-search", headers=headers, json={ "query": "VP of Engineering at Series B SaaS startups in New York", "mode": "people", "max_results": 500 } ) start_response.raise_for_status() task_id = start_response.json()["task_id"] print(f"Search started: {task_id}") # 2. Poll until complete while True: status_response = requests.get( f"{BASE_URL}/search/status/{task_id}", headers=headers ) status_response.raise_for_status() status_data = status_response.json() print(f"Status: {status_data['status']} — {status_data.get('progress_message', '')}") if status_data["status"] == "completed": resource_handle_id = status_data["resource_handle_id"] break elif status_data["status"] == "failed": raise RuntimeError(f"Search failed: {status_data.get('error')}") time.sleep(10) # 3. Get signed download URL download_response = requests.get( f"{BASE_URL}/search/download", headers=headers, params={"resource_handle_id": resource_handle_id} ) download_response.raise_for_status() download_url = download_response.json()["url"] print(f"Download URL: {download_url}") ``` ```javascript JavaScript theme={null} const API_KEY = "YOUR_API_KEY"; const BASE_URL = "https://api.sixtyfour.ai"; const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" }; // 1. Start the search const startResponse = await fetch(`${BASE_URL}/search/start-deep-search`, { method: "POST", headers, body: JSON.stringify({ query: "VP of Engineering at Series B SaaS startups in New York", mode: "people", max_results: 500 }) }); if (!startResponse.ok) throw new Error(`Failed to start: ${await startResponse.text()}`); const { task_id } = await startResponse.json(); console.log(`Search started: ${task_id}`); // 2. Poll until complete let resourceHandleId; while (true) { const statusResponse = await fetch( `${BASE_URL}/search/status/${task_id}`, { headers } ); const statusData = await statusResponse.json(); console.log(`Status: ${statusData.status} — ${statusData.progress_message ?? ""}`); if (statusData.status === "completed") { resourceHandleId = statusData.resource_handle_id; break; } else if (statusData.status === "failed") { throw new Error(`Search failed: ${statusData.error}`); } await new Promise((r) => setTimeout(r, 10000)); } // 3. Get signed download URL const downloadResponse = await fetch( `${BASE_URL}/search/download?resource_handle_id=${resourceHandleId}`, { headers } ); const { url } = await downloadResponse.json(); console.log(`Download URL: ${url}`); ```