> ## 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

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

<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>

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:
- `seed_domains=datadog.com&seed_domains=grafana.com&seed_domains=dynatrace.com`

You can also restrict results to your ICP by applying filters for company size, funding stage, and headquarters country.

## 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. Best when you can articulate the trait in 1-2 sentences.
- **Seed-based discovery** (`seed_domains`): pass up to 10 company websites and OpenFunnel uses them to synthesize the lookalike query for you. Best when you can name a few example customers but struggle to phrase what they have in common.
- **Both together**: pass `seed_domains` AND `query` - the query becomes a must-have angle layered on top of the seeds (e.g. seeds=[datadog.com, grafana.com] + query="cloud monitoring and observability tools" → synthesized trait targets cloud monitoring tools).

With `seed_domains`, the response echoes back the LLM-synthesized `derived_query`, plus `resolved_seed_domains` (seeds that landed in our index) and `unresolved_seed_domains` (seeds we couldn't find - skipped silently as long as at least one resolved).

## Omitting filters
If you omit filters, search runs across all company sizes, funding stages, and supported locations. Use the optional firmographic filters below to restrict results 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.

## Credits
**1 credit per company returned.** Empty result sets are free. The exact amount billed is echoed back in `credits_consumed` on the response. The LLM trait synthesis used by `seed_domains` is included - no extra charge.

The response includes a `derived_query` field with the LLM-synthesized trait so you can see exactly what was searched.



## OpenAPI

````yaml agent-primitives/openapi.json GET /api/v1/account/search-lookalikes
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:
    get:
      tags:
        - Company Search
      summary: Search Lookalikes
      description: >-
        Find lookalike companies from either a natural-language description
        **or** a set of seed company websites, with optional firmographic
        filters.


        <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>


        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:

        -
        `seed_domains=datadog.com&seed_domains=grafana.com&seed_domains=dynatrace.com`


        You can also restrict results to your ICP by applying filters for
        company size, funding stage, and headquarters country.


        ## 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.
        Best when you can articulate the trait in 1-2 sentences.

        - **Seed-based discovery** (`seed_domains`): pass up to 10 company
        websites and OpenFunnel uses them to synthesize the lookalike query for
        you. Best when you can name a few example customers but struggle to
        phrase what they have in common.

        - **Both together**: pass `seed_domains` AND `query` - the query becomes
        a must-have angle layered on top of the seeds (e.g. seeds=[datadog.com,
        grafana.com] + query="cloud monitoring and observability tools" →
        synthesized trait targets cloud monitoring tools).


        With `seed_domains`, the response echoes back the LLM-synthesized
        `derived_query`, plus `resolved_seed_domains` (seeds that landed in our
        index) and `unresolved_seed_domains` (seeds we couldn't find - skipped
        silently as long as at least one resolved).


        ## Omitting filters

        If you omit filters, search runs across all company sizes, funding
        stages, and supported locations. Use the optional firmographic filters
        below to restrict results 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.


        ## Credits

        **1 credit per company returned.** Empty result sets are free. The exact
        amount billed is echoed back in `credits_consumed` on the response. The
        LLM trait synthesis used by `seed_domains` is included - no extra
        charge.


        The response includes a `derived_query` field with the LLM-synthesized
        trait so you can see exactly what was searched.
      operationId: search_lookalikes_get_api_v1_account_search_lookalikes_get
      parameters:
        - name: query
          in: query
          required: false
          schema:
            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, the query is
            used as a must-have angle on top of the trait synthesized from the
            seeds.
        - name: seed_domains
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            maxItems: 10
            title: Seed Domains
          description: >-
            Up to 10 seed company websites/domains (e.g. `datadog.com`,
            `https://www.grafana.com`). When provided, OpenFunnel uses them to
            synthesize the lookalike query for you. Protocol / `www.` prefixes
            are normalized automatically. Unresolved seeds are skipped silently
            as long as at least one resolves. Repeat the parameter to send
            multiple values.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            title: Limit
          description: >-
            Maximum number of companies to return. Default `10`, max `100`. For
            larger result sets (up to 10000), use the async bulk endpoint `POST
            /api/v1/account/search-lookalikes-bulk`.
        - name: min_employees
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            title: Min Employees
          description: Minimum employee count, inclusive.
        - name: max_employees
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            title: Max Employees
          description: Maximum employee count, inclusive.
        - name: funding_stages
          in: query
          required: false
          style: form
          explode: true
          schema:
            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
            title: Funding Stages
          description: >-
            Funding stages to include. Repeat the parameter to send multiple
            values.
        - name: locations
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            title: Locations
          description: >-
            Headquarters country filter using ISO 3166-1 alpha-3 codes (e.g.
            `USA`, `GBR`, `IND`, `DEU`). Top 30 by company volume: USA, GBR,
            CHN, FRA, IND, DEU, BRA, BEL, ESP, CAN, AUS, NLD, ITA, NOR, ZAF,
            MEX, TUR, CHE, ARE, POL, SWE, IDN, ARG, PAK, COL, PRT, JPN, CHL,
            NGA, AUT. Pass `EU` to expand to all 27 EU member states. Repeat the
            parameter to send multiple values. Full list of 250 codes via `GET
            /api/v2/tech/country-options` (under Agent Helpers).
        - name: X-API-Key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstantTraitSearchResponse'
        '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: >-
            Lookalike search is temporarily unavailable. Please try again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableResponse'
      x-codeSamples:
        - lang: bash
          label: Query based
          source: >-
            curl -sS -G
            "https://api.openfunnel.dev/api/v1/account/search-lookalikes" \
              -H "X-API-Key: YOUR_API_KEY" \
              --data-urlencode "query=Healthcare companies building with voice AI" \
              --data-urlencode "limit=100" \
              --data-urlencode "min_employees=50" \
              --data-urlencode "max_employees=500" \
              --data-urlencode "funding_stages=Series A" \
              --data-urlencode "funding_stages=Series B" \
              --data-urlencode "locations=USA"
        - lang: bash
          label: Seed-based
          source: >-
            curl -sS -G
            "https://api.openfunnel.dev/api/v1/account/search-lookalikes" \
              -H "X-API-Key: YOUR_API_KEY" \
              --data-urlencode "seed_domains=datadog.com" \
              --data-urlencode "seed_domains=grafana.com" \
              --data-urlencode "seed_domains=dynatrace.com" \
              --data-urlencode "limit=25"
        - lang: bash
          label: Seeds + query
          source: >-
            curl -sS -G
            "https://api.openfunnel.dev/api/v1/account/search-lookalikes" \
              -H "X-API-Key: YOUR_API_KEY" \
              --data-urlencode "seed_domains=datadog.com" \
              --data-urlencode "seed_domains=dynatrace.com" \
              --data-urlencode "query=cloud monitoring tools" \
              --data-urlencode "limit=25"
components:
  schemas:
    InstantTraitSearchResponse:
      properties:
        query:
          type: string
          title: Query
          description: >-
            Original user query. May be an empty string when `seed_domains` was
            provided without a `query`.
        results:
          items:
            $ref: '#/components/schemas/InstantTraitSearchResult'
          type: array
          title: Results
          description: Matching companies
        total:
          type: integer
          title: Total
          description: Number of results returned
        credits_consumed:
          type: integer
          default: 0
          title: Credits Consumed
          description: >-
            Credits charged for this response. 1 credit per company returned.
            The LLM trait synthesis used by `seed_domains` is included - no
            extra charge.
        derived_query:
          anyOf:
            - type: string
            - type: 'null'
          title: Derived Query
          description: >-
            When `seed_domains` was provided, this is the LLM-synthesized trait
            query that was actually run against the lookalike pipeline. Null for
            pure-query requests.
        resolved_seed_domains:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Resolved Seed Domains
          description: >-
            Seed input strings that matched a company in the OpenFunnel
            companies index. Null when `seed_domains` was not provided.
        unresolved_seed_domains:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Unresolved Seed Domains
          description: >-
            Seed input strings that could not be resolved. Skipped silently as
            long as at least one seed resolved. Null when `seed_domains` was not
            provided.
      type: object
      required:
        - query
        - results
        - total
      title: InstantTraitSearchResponse
      description: Response for the public lookalike search.
    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
    InstantTraitSearchResult:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Company name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Primary company domain
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Url
          description: Company LinkedIn URL
        headquarters:
          anyOf:
            - type: string
            - type: 'null'
          title: Headquarters
          description: Best available headquarters location
        match_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Match Reason
          description: >-
            One-sentence LLM justification for why this company matches the
            trait query, with the supporting phrases from the company's
            description / industries wrapped in double quotes. Useful for human
            review of why a result was returned. May be null if the validator
            did not attach a reason.
        employee_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Employee Count
          description: >-
            Estimated employee count. ClickHouse firmographic enrichment; null
            when the company did not resolve in ClickHouse.
        funding_stage:
          anyOf:
            - type: string
            - type: 'null'
          title: Funding Stage
          description: Latest funding stage, e.g. 'Series C'.
        revenue_usd:
          anyOf:
            - type: integer
            - type: 'null'
          title: Revenue Usd
          description: Estimated annual revenue, in USD.
        industries:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Industries
          description: Industry tags.
        hq_city:
          anyOf:
            - type: string
            - type: 'null'
          title: Hq City
          description: HQ city.
        hq_region:
          anyOf:
            - type: string
            - type: 'null'
          title: Hq Region
          description: HQ state / region.
        hq_country:
          anyOf:
            - type: string
            - type: 'null'
          title: Hq Country
          description: HQ country.
        linkedin_follower_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Linkedin Follower Count
          description: LinkedIn follower count.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Short company description.
        tagline:
          anyOf:
            - type: string
            - type: 'null'
          title: Tagline
          description: Company tagline / LinkedIn headline.
      type: object
      title: InstantTraitSearchResult
      description: >-
        Single company returned by the public lookalike search endpoint,
        including best-effort ClickHouse firmographic enrichment (by domain).
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string

````