API reference
Search, start tasks, run tools, follow progress and read saved leads.
Set up with your AI assistant
Paste the prompt into Claude Code. It includes setup steps and a read-only connection check.
Endpoints
Paths are relative to https://leadsagent.io/api/v1. JSON responses use { request_id, status, data, meta }. Exports return a file. A signed download link needs no API-key header. Anyone holding it can download that list version for one hour; keep the link private.
| Method | Path | Input | Output | Scope or access |
|---|---|---|---|---|
| POST | /find | categories, locations, max_research_leads, match?, enrich?, checks? | Structured search task (202) | leads:write |
| POST | /tasks | prompt, max_leads, idempotency_key?, allow_questions? | Task (202) | leads:write |
| GET | /tasks/{id} | — | Task: status, steps, reply, question, lead_count | leads:read |
| POST | /tasks/{id}/messages | answers[] or message | Task | leads:write |
| POST | /tasks/{id}/cancel | — | Task | leads:write |
| GET | /tasks | limit, before | Task summaries | leads:read |
| GET | /tasks/{id}/results | fields, limit, cursor, has_email, has_website, has_phone | rows, matching_count, next_cursor | leads:read |
| GET | /tasks/{id}/export | format=csv|json | Every lead (file) | leads:read |
| GET | /downloads/{token} | Signed token, format=csv|json | One saved list version (file) | Signed link |
| GET | /tools | query?, limit (1–8) | Tool names, inputs and output columns | Authenticated credential |
| POST | /tasks/{id}/tools/{tool} | arguments, wait_seconds? | Tool run (202) | leads:write; list_tasks uses read |
| POST | /tasks/{id}/share | — | Public share URL | leads:write |
| GET | /account | — | Credits left, limit, reset, rate limits | leads:read |
Task status
| Status | Meaning |
|---|---|
| queued | Accepted, not started yet. |
| running | The agent is working. |
| needs_input | The agent asked a question. Answer with answers[]. |
| completed | Done. Read results or send a follow-up. |
| failed | Stopped with an error. Read error.code and error.message. |
| cancelled | Stopped on request. |
Results
Default fields: business_name, category, address, phone, email, website, rating, reviews. Ask for more with fields (place_id, city, state, country, latitude, longitude, google_maps_url, verification_status, is_deliverable, linkedin, facebook, instagram, emails). Pages hold up to 1,000 rows; follow next_cursor. The export returns every lead.