POST/campaigns
Maps search launch → creates a dashboard campaign. Discovery continues asynchronously.
0 credits at launch; 1 credit per email lead stored later. Rate class: create_campaign (default 6/min).
Request
POST /campaigns
X-API-Key: sk_live_...
Content-Type: application/json
{
"userQuery": "dentists in Austin TX",
"numberOfSearch": 50
}
| Field | Required | Notes |
|---|---|---|
userQuery | Yes | Business category + location; max 2000 chars |
numberOfSearch | No | 1–500, default 25 |
leadDuplicateProtectionAcrossCampaigns | No | boolean (optional; omit unless you need it) |
acceptedBroadening | No | boolean (optional; omit unless you need it) |
previewId | No | string, max 128 (optional; omit unless you need it) |
Response
{
"campaignId": "search-xyz",
"status": "CREATED",
"requestedLeadTarget": 50,
"creditsReservedEstimate": 50
}
Poll GET /campaigns/:id until ready with extensionStatus null (parent status may stay READY_TO_SEND while extend is "FINDING_LEADS"). Optionally peek GET …/leads. Via MCP, prefer wait_for_campaign_leads (no new REST route).
Errors
| Error code | When |
|---|---|
insufficient_credits | Not enough credits for discovery |
validation_error | Bad body |
conflict | Conflicting launch |
upstream_unavailable | Temporary failure |
MCP
Tool: create_campaign.