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, Expert Discovery, and GTM Lead Generation.

#Endpoint

Send your API key in the x-api-key header. See Authentication.

This endpoint returns 202 Accepted. Create a webhook signing secret and supply a public HTTPS webhook_url before making your first request. See Async Polling for retrieving results.

#Pricing

See Credits & Pricing for credit costs and charging behavior.

#Errors

For error responses and retry guidance, see Handling 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 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

Create an active webhook signing secret before submitting a request. Without one, the endpoint returns 409.

#Request examples

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:

#Results and webhook events

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

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.

An internal failure emits agentic_search.failed:

Verify webhook signatures before processing results. See 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 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

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

For other platform errors and response formats, see Handling Errors.