> ## 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

> Turn a natural language query into a list of people or companies, delivered as a CSV or as paginated JSON.

The search runs asynchronously: submit the query, poll for progress, then download a CSV or page through the results as JSON.

Use it for prospecting and list building when you can describe the audience in words. To query structured fields directly, use [Filter Search](https://docs.sixtyfour.ai/api-reference/legacy/filter-search.md). To find people similar to an existing list, use [Lookalike Search](https://docs.sixtyfour.ai/api-reference/legacy/lookalike-search.md).

## Core concepts

| Term | Description |
| - | - |
| `task_id` | Returned when a search or export starts. Poll `GET /search/status/{task_id}` with it. |
| `search_id` | Identifier for the saved search. Pass it to `POST /search/query` to page through results or to `POST /search/export` to generate a CSV. |
| `resource_handle_id` | Identifier for the generated CSV, returned when a CSV search or export completes. |
| `mode` | `people` (default) or `company`. |
| `max_results` | Total result cap. Defaults to 1,000. `GET /search/limits` returns your ceiling. |
| `output_mode` | `csv` (default) writes a downloadable CSV. `query_only` skips the CSV so you can page through results with `POST /search/query`. |

## Execution flows

### CSV download

```mermaid theme={null}
flowchart LR
  A["POST /search/start-deep-search"] --> B["GET /search/status/{task_id}"]
  B --> C["GET /search/download"]
```

1. Start a search with [`POST /search/start-deep-search`](https://docs.sixtyfour.ai/api-reference/legacy/search-endpoints#start-deep-search) and save the `task_id`.
2. Poll [`GET /search/status/{task_id}`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#get-search-status) until `status` is `completed`. The response includes `resource_handle_id`. Any status other than `running` or `completed` means the search stopped; see [Task statuses](https://docs.sixtyfour.ai/api-reference/legacy/search-results.md#task-statuses).
3. Request a signed URL with [`GET /search/download`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#download-search-results) and fetch the CSV. The URL expires after 15 minutes.

### Paginated JSON

```mermaid theme={null}
flowchart LR
  A["POST /search/start-deep-search<br/>output_mode: query_only"] --> B["GET /search/status/{task_id}"]
  B --> C["POST /search/query"]
  C --> D["POST /search/export (optional)"]
```

1. Start a search with `output_mode: "query_only"` and save the `task_id`.
2. Poll `GET /search/status/{task_id}` until `status` is `completed`, then read `search_id`.
3. Page through results with [`POST /search/query`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#query-search-results), sending each `next_cursor` until `has_more` is `false`. Send `max_results` again on the first request; see [Replay a saved search](https://docs.sixtyfour.ai/api-reference/legacy/search-results.md#replay-a-saved-search).
4. Optionally generate a CSV from the same `search_id` with [`POST /search/export`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#export-search-results).

## 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 "https://api.sixtyfour.ai/search/status/TASK_ID" \
  -H "x-api-key: YOUR_API_KEY"

# 3. Get a signed download URL (use resource_handle_id from step 2)
curl "https://api.sixtyfour.ai/search/download?resource_handle_id=RESOURCE_HANDLE_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

```python Python theme={null}
import time

import requests

BASE_URL = "https://api.sixtyfour.ai"
headers = {"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"}

start = 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.raise_for_status()
task_id = start.json()["task_id"]

deadline = time.monotonic() + 20 * 60
while time.monotonic() < deadline:
    status = requests.get(f"{BASE_URL}/search/status/{task_id}", headers=headers, timeout=30)
    if status.status_code in (429, 503):
        time.sleep(int(status.headers.get("Retry-After", "10")))
        continue
    status.raise_for_status()
    data = status.json()
    print(data["status"], data.get("progress_message") or "")
    if data["status"] == "completed":
        resource_handle_id = data["resource_handle_id"]
        break
    if data["status"] != "running":
        raise RuntimeError(data.get("error") or f"Search {data['status']}")
    time.sleep(10)
else:
    raise TimeoutError(f"Search {task_id} did not finish within 20 minutes")

download = requests.get(
    f"{BASE_URL}/search/download",
    headers=headers,
    params={"resource_handle_id": resource_handle_id},
)
download.raise_for_status()
print(download.json()["url"])
```

```javascript JavaScript theme={null}
const BASE_URL = "https://api.sixtyfour.ai";
const headers = { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

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(await startResponse.text());
const { task_id } = await startResponse.json();

let resourceHandleId;
const deadline = Date.now() + 20 * 60_000;
while (resourceHandleId === undefined) {
  if (Date.now() > deadline) throw new Error(`Search ${task_id} did not finish within 20 minutes`);
  const response = await fetch(`${BASE_URL}/search/status/${task_id}`, { headers });
  if (response.status === 429 || response.status === 503) {
    await sleep(Number(response.headers.get("Retry-After") ?? 10) * 1000);
    continue;
  }
  if (!response.ok) throw new Error(await response.text());
  const data = await response.json();
  console.log(data.status, data.progress_message ?? "");
  if (data.status === "completed") resourceHandleId = data.resource_handle_id;
  else if (data.status !== "running") throw new Error(data.error ?? `Search ${data.status}`);
  else await sleep(10_000);
}

const { url } = await fetch(
  `${BASE_URL}/search/download?resource_handle_id=${resourceHandleId}`,
  { headers },
).then((r) => r.json());
console.log(url);
```

> [!NOTE]
>
> For new integrations, see [Deep Search Overview](https://docs.sixtyfour.ai/api-reference/search/search-overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.