On this page

POST/campaigns/lookalike

Purpose

Create a new Lookalike campaign, or add more Lookalike leads to an existing campaign (campaignId), from a LinkedIn profile URL or identifier. Reserves Lookalike allowance (not normal lead credits), enqueues the worker, then poll campaign/leads until ready. Website/domain seeds are not accepted.

Caps and filters depend on the active Lookalike provider for the workspace deploy (current: Ocean). Ocean supports optional titles/countries and up to 10_000 leads. AgentEnrich mode is seed + lead count only (max 25); non-empty titles/countries → validation_error. Extending a campaign started under a different upstream → lookalike_provider_mismatch.

Same-seed extend continues from the last cursor when job title keywords and countries also match; exhausted same-seed+filters returns lookalike_exhausted. Different titles/countries on the same seed starts fresh. A different LinkedIn profile on extend returns alternate_seed_requires_new_campaign — create a new campaign.

Not available on some plans (plan_required).

Request

POST /campaigns/lookalike
X-API-Key: sk_live_...
Content-Type: application/json
Idempotency-Key: optional-uuid

{
  "seed": "https://www.linkedin.com/in/jane-doe/",
  "jobTitleKeywords": ["Chief Revenue Officer", "CRO"],
  "countries": ["us", "gb"],
  "numberOfLeads": 50,
  "leadDuplicateProtectionAcrossCampaigns": true
}

Extend (add more):

{
  "seed": "https://www.linkedin.com/in/jane-doe/",
  "jobTitleKeywords": ["Chief Revenue Officer", "CRO"],
  "countries": ["us", "gb"],
  "numberOfLeads": 50,
  "campaignId": "lookalike_abc123"
}

Field	Required	Notes
`seed`	yes	LinkedIn profile URL or identifier (e.g. `linkedin.com/in/…`)
`jobTitleKeywords`	no	Ocean: include titles (string or string[], max 15 × 80 chars). Partial match. Omit / empty for broad lookalike. AgentEnrich: must omit or empty (`validation_error` otherwise).
`countries`	no	Ocean: person countries (ISO 3166-1 alpha-2 string[], max 25). Omit for worldwide. AgentEnrich: must omit or empty.
`numberOfLeads`	no	Ocean default 50 / hard cap 10_000; AgentEnrich default 25 / hard cap 25. Clamped to available Lookalike.
`campaignId`	no	Existing campaign to extend
`leadDuplicateProtectionAcrossCampaigns`	no	Default true

Create mints campaignId server-side. Do not send a client-generated id for new campaigns.

Response 200

{
  "campaignId": "lookalike_…",
  "status": "PENDING",
  "extended": false,
  "extensionBatchId": null,
  "requestedLeadTarget": 50,
  "lookalikeReserved": 50,
  "resume": null,
  "message": "Lookalike campaign queued."
}

resume is fresh or continue on extend; null on create. Unused reserved Lookalike is refunded by the worker after insert.

202 may be returned if extend enqueue outcome is ambiguous — check campaign progress before retrying.

Request logs keep creditsCharged at 0 (normal lead-credit flag only). The reserved Lookalike amount is only in lookalikeReserved.

Errors

`error.code`	HTTP	When
`validation_error`	400	Bad body / seed
`lookalike_exhausted`	400	No more results for this profile + titles/locations on this campaign
`alternate_seed_requires_new_campaign`	400	Different LinkedIn profile than this campaign’s seed — create a new Lookalike campaign
`lookalike_provider_mismatch`	400	Campaign was started under a different Lookalike upstream than the current deploy
`upstream_unavailable`	503	Lookalike provider temporarily unavailable, including while Lookalike is under maintenance
`insufficient_lookalike_credits`	403	Lookalike balance too low (`details.available` / `required`)
`plan_required`	403	Ineligible plan, inactive plan without Lookalike top-up, or Lookalike blocked for workspace
`not_found`	404	Extend `campaignId` missing
`conflict`	409	Idempotency / extend in progress
`rate_limited`	429	Per-key Lookalike RPM
`upstream_unavailable`	503	Pipeline/queue failure or idempotency store down

MCP

Tool: create_lookalike_campaign.