---
title: "Search Lookalikes Bulk"
method: POST
path: "/api/v1/account/search-lookalikes-bulk"
tags: ["Company Search"]
---

# Search Lookalikes Bulk

`POST /api/v1/account/search-lookalikes-bulk`

**Asynchronous, high-volume variant of [Search Lookalikes](/agent-primitives/search-lookalikes).** Same lookalike engine and inputs, but it accepts up to **10000** companies and runs as a background job: the call returns a `job_id` immediately, and you poll a separate endpoint for status + paginated results.

<Info>**No API key yet?** [Sign up via Agent Auth](/agent-primitives/authentication) to get your `X-API-Key` - the only required header for this endpoint.</Info>

Find lookalike companies from either a natural-language description **or** a set of seed company websites, with optional firmographic filters.

Use it for queries such as:
- `Healthcare companies building with voice AI`
- `Companies that provide customer support software for B2C`
- `Companies that build workflow automation for non technical industries`

Or supply 1-10 seed company websites and let OpenFunnel synthesize the query for you.

## Two input modes

At least one of `query` or `seed_domains` is required. Both can be combined for a hybrid trait.

- **Natural language** (`query`): describe the kind of company you want.
- **Seed-based discovery** (`seed_domains`): pass up to 10 company websites and OpenFunnel uses them to synthesize the lookalike query for you. The response manifest echoes back the LLM-synthesized `derived_query`, plus `resolved_seed_domains` and `unresolved_seed_domains`.
- **Both together**: pass `seed_domains` AND `query` - the query becomes a must-have angle layered on top of the seeds.

## Omitting filters
If you omit filters, search runs across all company sizes, funding stages, and supported locations. Use the optional firmographic filters (`min_employees`, `max_employees`, `funding_stages`, `locations`) to restrict to your ICP.

## Discovering available firmographics
The `funding_stages`, `locations`, `min_employees`, and `max_employees` filters accept a fixed set of values. Fetch the current set via **`GET /api/v1/account/firmographic-options`** - it returns the accepted `funding_stages` labels, the supported HQ `locations` (code + name), and the min/max employee bounds.

## Polling for results
This endpoint responds immediately with a `job_id` and `status: "pending"`. **Poll `GET /api/v1/account/search-lookalikes-bulk/{job_id}`** ("Search Lookalikes Bulk Results", listed under Agent Helpers) until `status` is `completed`, then walk the result pages using `next_cursor`. A large `limit` can take minutes - polling avoids a long-held connection.

## Credits
**1 credit per company returned**, charged when the job completes. Empty result sets are free. The amount is echoed in the manifest's `credits_consumed`.

## Cancelling a job
If you need to stop a running or pending job early, call **`POST /api/v1/account/search-lookalikes-bulk/{job_id}/cancel`**. The job moves to a transient `cancelling` state and stops at its next checkpoint; whatever companies were already delivered stay readable via the poll endpoint, and you are charged **only for those** - nothing for the abandoned remainder.

The response returns a `job_id`; then poll `GET /api/v1/account/search-lookalikes-bulk/{job_id}` for status and results.

## Headers

- `X-API-Key` string, required

## Request body

- BulkLookalikeSearchRequest — Request body for the async bulk lookalike search. Same fields as Search Lookalikes, but `limit` accepts up to 10000. At least one of `query` or `seed_domains` is required.
  - `query` string, nullable — Describe the kinds of companies you want to find. Required unless `seed_domains` is provided. When both are supplied, used as a must-have angle on top of the seeds.
  - `seed_domains` string[], nullable — Up to 10 seed company websites/domains. When provided, OpenFunnel synthesizes the lookalike query for you.
  - `limit` integer — Maximum number of companies to return. Default 100, max 10000. Large input set can take a few minutes to process.
  - `min_employees` integer, nullable — Minimum employee count, inclusive.
  - `max_employees` integer, nullable — Maximum employee count, inclusive.
  - `funding_stages` string[], nullable — Funding stages to include.
  - `locations` string[], nullable — Headquarters country filter using ISO 3166-1 alpha-3 codes (e.g. USA, GBR, IND, DEU). Pass EU to expand to all 27 EU member states.

## Response `200`

Job accepted. Returns a `job_id` to poll for status and results.

- BulkLookalikeSubmitResponse — Returned immediately when a bulk lookalike job is submitted.
  - `job_id` string, required — Async job id. Poll `GET /api/v1/account/search-lookalikes-bulk/{job_id}` for status and results.
  - `status` string — Job status at submit time (always `pending`).
  - `message` string, required — Human-readable next-step hint.
  - `requested_top_k` integer, required — The requested result limit.

## Other responses

- `422` — Validation Error
- `429` — Rate limit reached for this API key or user.
- `503` — Bulk lookalike search is temporarily unavailable. Please try again shortly.

---

[API](https://skmtc.net/openfunnel/apis/openfunnel-agent-primitives.md) · [All operations](https://skmtc.net/openfunnel/apis/openfunnel-agent-primitives/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openfunnel/openfunnel-agent-primitives/revisions/68cc95acb1f2/schema)