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

> Find people and companies from a natural language query.

Start the search here, then poll, download, and page through it with the [Search Results](https://docs.sixtyfour.ai/api-reference/legacy/search-results.md) endpoints. For the end-to-end flow, see the [Deep Search Overview](https://docs.sixtyfour.ai/api-reference/legacy/search-overview.md).

> [card] [API Reference](https://docs.sixtyfour.ai/api-reference/search/start-deep-search-async.md)
>
> See the full request/response schema and parameters in the API Reference.

## Start deep search

Submit a natural language query. Returns a `task_id` to poll with [`GET /search/status/{task_id}`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#get-search-status).

```http theme={null}
POST https://api.sixtyfour.ai/search/start-deep-search
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | string | required | Natural language description of the people or companies to find, up to 10,000 characters. |
| `mode` | string | `people` | `people` or `company`. |
| `max_results` | integer | `1000` | Total result cap, from 1 to your [ceiling](https://docs.sixtyfour.ai/api-reference/legacy/search-results.md#search-limits). |
| `output_mode` | string | `csv` | `csv` writes a downloadable CSV. `query_only` skips the CSV; page through results with [`POST /search/query`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#query-search-results). |
| `search_id` | string | generated | Optional UUID for the new search. It is not an idempotency key; see [Retry a start request](#retry-a-start-request). |
| `exclude_entity_ids` | string\[] | None | People or companies to leave out (max 1,000). See [Search Exclusions](https://docs.sixtyfour.ai/api-reference/search/search-exclusions.md). |
| `exclude_list_ids` | string\[] | None | Saved exclusion lists to apply. See [Search Exclusions](https://docs.sixtyfour.ai/api-reference/search/search-exclusions.md). |

```json theme={null}
{
  "query": "VP of Engineering at Series B SaaS startups in New York",
  "mode": "people",
  "max_results": 500
}
```

Response:

```json theme={null}
{
  "task_id": "agentic_search_e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "status": "running",
  "message": "Search started successfully"
}
```

The task ID is `agentic_search_` followed by the search's `search_id`.

### Concurrency and run time

Each organization runs up to 5 deep searches at a time; see [Concurrency limits](https://docs.sixtyfour.ai/api-reference/rate-limits.md#deep-search). A deep search runs for at most 15 minutes, then ends `timed_out`.

### Retry a start request

A start request that sends its own `search_id` (a UUID) can be checked after a timeout at `GET /search/status/agentic_search_{search_id}`:

* A status response means the search started.
* A `404` two minutes after the start means it did not start. A new start needs a new `search_id`.

Each `search_id` must be a new UUID; see [Search errors](https://docs.sixtyfour.ai/api-reference/legacy/errors.md#search).

## Get the results

| Step | Endpoint |
| - | - |
| Poll the task until it stops | [`GET /search/status/{task_id}`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#get-search-status) |
| Download the CSV (`output_mode: "csv"`) | [`GET /search/download`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#download-search-results) |
| Page through rows as JSON | [`POST /search/query`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#query-search-results) |
| Build a CSV from a `query_only` search | [`POST /search/export`](https://docs.sixtyfour.ai/api-reference/legacy/search-results#export-search-results) |

***

## Example usage

```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"
}

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}")

deadline = time.monotonic() + 20 * 60
while True:
    if time.monotonic() > deadline:
        raise TimeoutError(f"Search {task_id} did not finish within 20 minutes")
    status_response = requests.get(
        f"{BASE_URL}/search/status/{task_id}",
        headers=headers,
        timeout=30,
    )
    if status_response.status_code in (429, 503):
        time.sleep(int(status_response.headers.get("Retry-After", "10")))
        continue
    status_response.raise_for_status()
    status_data = status_response.json()

    print(f"Status: {status_data['status']}, {status_data.get('progress_message') or ''}")

    if status_data["status"] == "completed":
        resource_handle_id = status_data["resource_handle_id"]
        print(f"Total results: {status_data['total_results']}")
        break
    if status_data["status"] != "running":
        raise RuntimeError(f"Search {status_data['status']}: {status_data.get('error')}")

    time.sleep(10)

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}")

csv_response = requests.get(
    download_url,
    headers=headers,
    allow_redirects=False
)
if csv_response.status_code != 200:
    raise RuntimeError(f"Download failed: {csv_response.status_code}")
with open("search_results.csv", "wb") as f:
    f.write(csv_response.content)
print("Results saved to search_results.csv")
```

```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" };
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(`Failed to start: ${await startResponse.text()}`);
const { task_id } = await startResponse.json();
console.log(`Search started: ${task_id}`);

let resourceHandleId;
const deadline = Date.now() + 20 * 60_000;
while (true) {
  if (Date.now() > deadline) throw new Error(`Search ${task_id} did not finish within 20 minutes`);
  const statusResponse = await fetch(
    `${BASE_URL}/search/status/${task_id}`,
    { headers }
  );
  if (statusResponse.status === 429 || statusResponse.status === 503) {
    await sleep(Number(statusResponse.headers.get("Retry-After") ?? 10) * 1000);
    continue;
  }
  if (!statusResponse.ok) throw new Error(`Status check failed: ${statusResponse.status}`);
  const statusData = await statusResponse.json();

  console.log(`Status: ${statusData.status}, ${statusData.progress_message ?? ""}`);

  if (statusData.status === "completed") {
    resourceHandleId = statusData.resource_handle_id;
    console.log(`Total results: ${statusData.total_results}`);
    break;
  }
  if (statusData.status !== "running") {
    throw new Error(`Search ${statusData.status}: ${statusData.error}`);
  }

  await sleep(10_000);
}

const downloadResponse = await fetch(
  `${BASE_URL}/search/download?resource_handle_id=${resourceHandleId}`,
  { headers }
);
if (!downloadResponse.ok) throw new Error(`Download request failed: ${downloadResponse.status}`);
const { url } = await downloadResponse.json();
console.log(`Download URL: ${url}`);

const csvResponse = await fetch(url, { headers, redirect: "error" });
if (!csvResponse.ok) throw new Error(`Download failed: ${csvResponse.status}`);
const buffer = Buffer.from(await csvResponse.arrayBuffer());
const fs = await import("fs");
fs.writeFileSync("search_results.csv", buffer);
console.log("Results saved to search_results.csv");
```

## Rate limits

For per-endpoint limits, see [Rate Limits](https://docs.sixtyfour.ai/api-reference/rate-limits.md#search).

## Pricing

See [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md) for more information.

## Related

* [Batch Processing](https://docs.sixtyfour.ai/guides/batch-processing.md)
* [Async Jobs](https://docs.sixtyfour.ai/api-reference/async-jobs.md)
* [Handling Errors](https://docs.sixtyfour.ai/api-reference/errors.md)
* [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md)

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


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