# Agentic Search

## Use case

Use Agentic Search to find people whose fit depends on a specific combination of experience, expertise, and accomplishments. Describe your ideal persona in detail, including what matters most and who to exclude. The agent researches potential matches and returns evidence explaining why each person fits.

- **Find B2B leads for a specific customer profile.** Look for engineering leaders at robotics companies who have taken autonomous warehouse systems into production, or finance executives with experience expanding a business internationally. Explain the experience that makes someone relevant to your product.
- **Source candidates for hard-to-fill roles.** Search for founding engineers who have built developer tools, operations leaders who have scaled manufacturing, or researchers with both academic and industry experience. Spell out the background your hiring team needs beyond a job title.
- **Find experts for interviews, advisory work, and research.** Identify practitioners who have implemented a particular technology or solved a specific operational problem. Use the returned fit summaries, proof points, and source evidence to assess whom to contact.

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

## Endpoint

```http
POST https://api-public.clodo.ai/api/public/v1/agentic-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).

Clodo's canonical agentic people search endpoint. Describe your target persona in plain language and get as specific as you want: their current role, past experience, technical expertise, location, the kind of company they work at, or something particular they have done. Combine criteria, explain what matters most, and include exclusions or examples to clarify who you are looking for.

For example: “Find engineering leaders at US robotics companies who have personally worked on autonomous warehouse systems. Prioritize people who previously took a robotics product from prototype to production, and exclude consultants and recruiting firms.” Clodo searches people data and the open web, researches potential matches against your criteria, and returns people with fit summaries, proof points, and source evidence. The `query` field supports up to 2,000 characters.

## Availability

Agentic Search is enabled per account. Once enrolled, all your API keys can use it, including newly created keys. Accounts that are not enrolled receive `404`. [Contact support](mailto:hello@clodo.ai) to request access.

## Credit budget

Set `max_credits` to control the maximum charge for a job: **300–2,000 credits**, with a default of **500**. The cap is reserved when the job is accepted. At completion, only the final charge is retained; the unused reservation is released or refunded.

The final charge depends on the research performed and leads delivered, and never exceeds your cap. A completed search that performs work but finds no qualifying leads costs **100 credits**. Internal failures and cancellation before paid work starts are not charged. Partial deliveries remain billable within the same cap. A webhook delivery failure does not undo the charge; retrieve the result by polling.

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | Yes | Describe the people you want to find in plain language, up to 2,000 characters. Be as specific as you like about their role, background, expertise, company, location, or experiences. Include priorities, exclusions, and any evidence you want checked. Must not be empty. |
| `target_results` | integer | No | Desired number of leads, from 1 to 50. Default: `50`. This is a target, not a guaranteed result count. |
| `max_credits` | integer | No | Maximum charge, from 300 to 2,000 credits. Default: `500`. |
| `webhook_url` | string | Yes | Public HTTPS receiver URL, up to 2,048 characters. Must resolve to a public IP address. |

Create an active [webhook signing secret](https://docs.clodo.ai/guides/webhook-secrets) before submitting a request. Without one, the endpoint returns `409`.

## Request examples

```bash
curl --request POST 'https://api-public.clodo.ai/api/public/v1/agentic-search/' \
  --header "x-api-key: $CLODO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: agentic-search-example-001' \
  --data '{
    "query": "Find engineering leaders at US robotics companies with evidence of deploying autonomous warehouse systems.",
    "target_results": 25,
    "max_credits": 500,
    "webhook_url": "https://your-app.example/webhooks/clodo"
  }'
```
```python
import os
import requests

response = requests.post(
    "https://api-public.clodo.ai/api/public/v1/agentic-search/",
    headers={
        "x-api-key": os.environ["CLODO_API_KEY"],
        "Idempotency-Key": "agentic-search-example-001",
    },
    json={
        "query": "Find engineering leaders at US robotics companies with evidence of deploying autonomous warehouse systems.",
        "target_results": 25,
        "max_credits": 500,
        "webhook_url": "https://your-app.example/webhooks/clodo",
    },
    timeout=30,
)
response.raise_for_status()
job = response.json()
print(job["id"])
```
```javascript
const response = await fetch("https://api-public.clodo.ai/api/public/v1/agentic-search/", {
  method: "POST",
  headers: {
    "x-api-key": process.env.CLODO_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "agentic-search-example-001",
  },
  body: JSON.stringify({
    query: "Find engineering leaders at US robotics companies with evidence of deploying autonomous warehouse systems.",
    target_results: 25,
    max_credits: 500,
    webhook_url: "https://your-app.example/webhooks/clodo",
  }),
});
if (!response.ok) throw new Error(`Clodo returned ${response.status}: ${await response.text()}`);
const job = await response.json();
console.log(job.id);
```

Run these examples on your server to keep your API key private. Replace the example webhook URL with your receiver and use a new idempotency key for each new search.

## Accepted response

HTTP `202 Accepted`:

```json
{
  "id": "dj_a1b2c3d4e5f6478890abcdef123456789",
  "status": "pending",
  "created_at": "2026-09-07T12:00:00Z"
}
```

## Results and webhook events

The `agentic_search.completed` event contains the final result, including successful searches with zero leads:

```json
{
  "id": "dj_a1b2c3d4e5f6478890abcdef123456789",
  "event_type": "agentic_search.completed",
  "partial": false,
  "completion_reason": "",
  "total_returned": 1,
  "results": [
    {
      "full_name": "Alex Morgan",
      "current_job_title": "VP of Engineering",
      "headline": "Building warehouse robotics",
      "location": "Boston, Massachusetts, United States",
      "professional_url": "https://www.linkedin.com/in/example-alex-morgan",
      "company": {
        "name": "Example Robotics",
        "domain": "robotics.example",
        "industry": "Robotics",
        "employee_count_range": "51-200"
      },
      "experience": [
        {"company": "Example Robotics", "title": "VP of Engineering", "date_range": "2022-present"}
      ],
      "fit_summary": "Leads engineering for a US company deploying autonomous warehouse systems.",
      "proof_points": ["Company team page identifies Alex as VP of Engineering."],
      "evidence": [
        {"headline": "Leadership team", "url": "https://robotics.example/team"}
      ],
      "tier": "perfect"
    }
  ]
}
```

The response above is illustrative. Individual person fields may be empty or omitted when unavailable. Evidence entries can include `headline`, `description`, and `url`. Source URLs are only included after retrieval during the job.

| Field | Meaning |
|---|---|
| `results` | Delivered people, with professional details, company, experience, fit summary, proof points, evidence, and a fit tier when available. |
| `total_returned` | Number of people delivered. A zero-result search returns `0` and an empty `results` array. |
| `partial` | `true` when the job stopped early and returned the results saved so far. |
| `completion_reason` | Empty on normal completion; `budget_exhausted`, `deadline_exceeded`, or `user_cancelled` when stopped early. |

An internal failure emits `agentic_search.failed`:

```json
{
  "id": "dj_a1b2c3d4e5f6478890abcdef123456789",
  "event_type": "agentic_search.failed",
  "error": {"code": "error", "message": "Internal error — you were not charged."}
}
```

Verify [webhook signatures](https://docs.clodo.ai/guides/webhook-signing) before processing results. See [Webhook Events](https://docs.clodo.ai/guides/webhook-events) for additional failure codes.

## Polling

Use `GET /api/public/v1/agentic-search/{job_id}/` with your API key. Poll every 30–60 seconds until the status is `completed`, `failed`, or `cancelled`.

The [polling envelope](https://docs.clodo.ai/guides/async-polling) includes `status`, timestamps, `tier: "agentic_search"`, `leads_returned`, `result`, and `error`. On completion, `result` contains the same result fields as the webhook, without `id` or `event_type`. Polling consumes no credits.

## Cancellation

Send `POST /api/public/v1/agentic-search/{job_id}/cancel/` with your API key. No request body is required. It returns `202` with the job's current `id`, `status`, and `created_at`.

- A pending job cancels immediately and releases its entire credit reservation.
- A running job stops at the next safe point and completes with `partial: true`, `completion_reason: "user_cancelled"`, and any saved results. Work already performed remains billable within your cap.
- Cancelling an already terminal job returns its current state. It does not restart the job or refund completed work.

Poll after requesting cancellation to confirm the terminal state. The cancellation request is idempotent.

## Idempotency

The optional `Idempotency-Key` header is scoped to your API key. Repeating the same key and validated request body returns the existing job, without another dispatch or reservation. Changing the body—including `webhook_url`—while reusing the key returns `409`. Use a fresh key for every new logical request, including requests to other endpoints.

## Rate limits

| Operation | Sustained requests per minute | Burst |
|---|---|---|
| Create search | 2 | 2 |
| Poll search | 3,600 | 100 |
| Cancel search | 60 | 10 |

At most **2 Agentic Search jobs per API key** and **3 per account** can be pending or running. New requests beyond these concurrency limits return `429`. Replays of existing idempotent requests do not create a new job.

## Status codes

| HTTP | Meaning |
|---|---|
| `202` | Search accepted, existing job replayed, or cancellation acknowledged. |
| `400` | Invalid query, target, cap, or webhook URL. |
| `402` | Billing cannot authorize the requested credit reservation. |
| `403` | API key is missing, invalid, revoked, or the account is ineligible for API access. |
| `404` | Account is not enrolled for Agentic Search, or the requested job is unavailable to your account. |
| `409` | No active webhook signing secret, or an idempotency key was reused with a different body. |
| `429` | Request rate or in-flight job limit exceeded. |
| `500` | Internal admission or dispatch failure; the reservation is released or refunded. |

For other platform errors and response formats, see [Handling Errors](https://docs.clodo.ai/api-reference/errors).