> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openfunnel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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-auth/agent-auth/agent-sign-up) 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.



## OpenAPI

````yaml agent-primitives/openapi.json POST /api/v1/account/search-lookalikes-bulk
openapi: 3.1.0
info:
  title: OpenFunnel Agent Primitives
  version: 1.0.0
servers:
  - url: https://api.openfunnel.dev
security: []
paths:
  /api/v1/account/search-lookalikes-bulk:
    post:
      tags:
        - Company Search
      summary: Search Lookalikes Bulk
      description: >-
        **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-auth/agent-auth/agent-sign-up) 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.
      operationId: search_lookalikes_bulk_api_v1_account_search_lookalikes_bulk_post
      parameters:
        - name: X-API-Key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkLookalikeSearchRequest'
      responses:
        '200':
          description: Job accepted. Returns a `job_id` to poll for status and results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLookalikeSubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit reached for this API key or user.
        '503':
          description: >-
            Bulk lookalike search is temporarily unavailable. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableResponse'
      x-codeSamples:
        - lang: bash
          label: Submit a bulk job
          source: >-
            curl -sS -X POST
            "https://api.openfunnel.dev/api/v1/account/search-lookalikes-bulk" \
              -H "X-API-Key: YOUR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"query": "Healthcare companies building with voice AI", "limit": 2000, "min_employees": 50, "max_employees": 500, "funding_stages": ["Series A", "Series B"], "locations": ["USA"]}'
components:
  schemas:
    BulkLookalikeSearchRequest:
      type: object
      title: BulkLookalikeSearchRequest
      description: >-
        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.
      properties:
        query:
          anyOf:
            - type: string
              minLength: 1
              maxLength: 200
            - type: 'null'
          title: Query
          description: >-
            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:
          anyOf:
            - type: array
              items:
                type: string
              maxItems: 10
            - type: 'null'
          title: Seed Domains
          description: >-
            Up to 10 seed company websites/domains. When provided, OpenFunnel
            synthesizes the lookalike query for you.
        limit:
          type: integer
          minimum: 1
          maximum: 10000
          default: 100
          title: Limit
          description: >-
            Maximum number of companies to return. Default 100, max 10000. Large
            input set can take a few minutes to process.
        min_employees:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Min Employees
          description: Minimum employee count, inclusive.
        max_employees:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Employees
          description: Maximum employee count, inclusive.
        funding_stages:
          anyOf:
            - type: array
              items:
                type: string
                enum:
                  - Pre-Seed
                  - Seed
                  - Series A
                  - Series B
                  - Series C
                  - Series D
                  - Series E
                  - Series F
                  - Series G
                  - Series H
                  - Acquired
                  - Private
                  - Public
            - type: 'null'
          title: Funding Stages
          description: Funding stages to include.
        locations:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Locations
          description: >-
            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.
    BulkLookalikeSubmitResponse:
      type: object
      title: BulkLookalikeSubmitResponse
      description: Returned immediately when a bulk lookalike job is submitted.
      required:
        - job_id
        - message
        - requested_top_k
      properties:
        job_id:
          type: string
          title: Job Id
          description: >-
            Async job id. Poll `GET
            /api/v1/account/search-lookalikes-bulk/{job_id}` for status and
            results.
        status:
          type: string
          default: pending
          title: Status
          description: Job status at submit time (always `pending`).
        message:
          type: string
          title: Message
          description: Human-readable next-step hint.
        requested_top_k:
          type: integer
          title: Requested Top K
          description: The requested result limit.
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    ServiceUnavailableResponse:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable explanation of why the service is unavailable.
      title: ServiceUnavailableResponse
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string

````