# Deep Search

## Use case

Use Deep Search to find and qualify people against a focused set of criteria. It returns a researched shortlist with professional details, work experience, and fit scores, giving your team more context for deciding whom to approach.

- **Qualify sales leads before outreach.** Search for decision-makers at companies in your target market—for example, technology leaders at regional banks or founders of climate-tech businesses in Germany. Review the returned company context and fit scores to prioritize prospects.
- **Build recruiting shortlists.** Find candidates whose roles, industry backgrounds, and career experience align with a position. For a healthcare product leadership role, describe the relevant product and sector experience, then use the returned work history to guide your review.
- **Identify subject-matter experts for a project.** Look for supply-chain leaders in manufacturing, executives in renewable energy, or operators in financial services. Compare their professional backgrounds when selecting potential interviewees, advisors, or research participants.

Choose standard or extended mode based on the size of the shortlist you want. Each mode has a fixed price per successful run, making it straightforward to budget recurring prospecting, candidate sourcing, and expert discovery workflows.

## Endpoint

```http
POST https://api-public.clodo.ai/api/public/v1/deep-search/
```

Send your API key in the `x-api-key` header. See [Authentication](https://docs.clodo.ai/api-reference/authentication).

> This endpoint returns `202 Accepted`. Create a [webhook signing secret](https://docs.clodo.ai/guides/webhook-secrets) and supply a public HTTPS `webhook_url` before making your first request. See [Async Polling](https://docs.clodo.ai/guides/async-polling) for retrieving results.

## Pricing

See [Credits & Pricing](https://docs.clodo.ai/guides/credits-and-pricing) for credit costs and charging behavior.

## Errors

For error responses and retry guidance, see [Handling Errors](https://docs.clodo.ai/api-reference/errors).

`POST /api/public/v1/deep-search/` — async (returns `202 Accepted`). Fixed price per run:

- `mode: "standard"` — 200 credits, ~25 qualified leads
- `mode: "extended"` — 400 credits, ~100 qualified leads

Wall time ~10-15 minutes. Results delivered via signed webhook POST. Polling fallback at `GET /api/public/v1/deep-search/{job_id}/`.

## Request

| Field | Type | Required | Notes |
|---|---|---|---|
| `query` | string | yes | Natural-language query. ≤500 chars. |
| `mode` | string | no | `"standard"` (default) or `"extended"`. |
| `webhook_url` | string | yes | HTTPS URL. Must resolve to a public IP. |

Pre-condition: an active webhook signing secret. See [Webhook Signing Secrets](https://docs.clodo.ai/guides/webhook-secrets).

`Idempotency-Key` header is supported. Same key returns the same job's current state.

## Response (202)

```json
{
  "id": "dj_a1b2c3d4...",
  "status": "pending",
  "created_at": "2026-05-01T12:00:00Z"
}
```

## Webhook events

`deep_search.completed`:

```json
{
  "id": "dj_a1b2c3d4...",
  "event_type": "deep_search.completed",
  "results": [
    {
      "first_name": "Patrick",
      "last_name": "Collison",
      "full_name": "Patrick Collison",
      "current_job_title": "CEO",
      "headline": "CEO at Stripe",
      "location": "San Francisco, California, United States",
      "professional_url": "linkedin.com/in/patrickcollison",
      "company": {
        "name": "Stripe",
        "domain": "stripe.com",
        "professional_url": "linkedin.com/company/stripe",
        "industry": "Financial Services",
        "employee_count": 8000
      },
      "email": "patrick@stripe.com",
      "experience": [
        {"company": "Stripe", "title": "CEO", "date_range": "2010–present"}
      ],
      "score": 92
    }
  ],
  "total_returned": 1
}
```

Company `professional_url` is optional and may be `null`.

`deep_search.failed`:

```json
{
  "id": "dj_a1b2c3d4...",
  "event_type": "deep_search.failed",
  "error": {"code": "error", "message": "Deep search failed; please retry."}
}
```

| `error.code` | `error.message` |
|---|---|
| `invalid_input` | `Invalid deep-search query.` |
| `error` | `Deep search failed; please retry.` |

A 0-result outcome ships as `deep_search.completed` with `total_returned: 0`.

Person and company `professional_url` values come back in bare-host form (no scheme, no `www.`, no trailing slash). Company `professional_url` is optional and may be `null`.

## Billing

Fixed charge per run. Customer pays the full mode price on a successful run regardless of `total_returned`. Pipeline errors and dispatch failures release the reservation (no charge).

## Example

```bash
curl -X POST https://api-public.clodo.ai/api/public/v1/deep-search/ \
  -H "x-api-key: ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Climate tech founders in Berlin",
    "mode": "standard",
    "webhook_url": "https://yourapp.com/webhooks/clodo"
  }'
```

## Rate limit

`POST /api/public/v1/deep-search/`:

| Limit | Value |
|---|---|
| Sustained rate | 4 requests / minute |
| Burst | 2 requests |

Polling `GET /api/public/v1/deep-search/{job_id}/`:

| Limit | Value |
|---|---|
| Sustained rate | 3,600 requests / minute |
| Burst | 100 requests |

Exceeding any returns `429`.

## See also

- [Expert Discovery](https://docs.clodo.ai/guides/expert-discovery)
- [GTM Lead Generation](https://docs.clodo.ai/guides/gtm-lead-generation)
- [Recruiting & Candidate Sourcing](https://docs.clodo.ai/guides/recruiting-candidate-sourcing)

- [Webhook Signing Secrets](https://docs.clodo.ai/guides/webhook-secrets)
- [Webhook Signature Verification](https://docs.clodo.ai/guides/webhook-signing)
- [Async Polling](https://docs.clodo.ai/guides/async-polling)
- [Idempotency](https://docs.clodo.ai/guides/idempotency)