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

# Lookalike Search

> Find companies similar to a reference company using the Lookalike endpoint.

<Note>
  New integrations should use [`POST /v1/companies/{company_identifier}/similar`](/api-reference/lookalike-search-post), which takes `filters` as a JSON object. The `GET` form shown below still works but is deprecated.
</Note>

## Overview

Lookalike Search ranks companies by similarity to a reference company from the same Extruct index used by Semantic Search.
It takes a company domain or UUID as input and blends what a company does, who it sells to, firmographics, and traffic into a single ranking.

## This Path Works Best When

* You trust one company as a good market proxy.
* You want expansion around a known winner, competitor, or target account.
* Filters should refine results, but the seed company should drive ranking.

## Choose Another Path If

* You do not yet have a strong seed company. Start with [Semantic Search](/api-guides/search/semantic-search).
* You need custom natural-language evaluation criteria instead of index-based similarity. Use [Deep Search](/api-guides/search/deep-search).

## Prerequisites

```bash theme={null}
export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"
```

Generate tokens in [Dashboard API Tokens](https://app.extruct.ai/api-tokens). For full setup, see [Authentication](/api-reference/authentication).

## Endpoints used

* [Company Lookup endpoint (`GET /v1/companies/:company_identifier`)](/api-reference/company-lookup)
* [Lookalike endpoint (`GET /v1/companies/:company_identifier/similar`)](/api-reference/lookalike-search)
* [Search endpoint (`GET /v1/companies/search`)](/api-reference/search)

## Workflow

### 1) Choose `company_identifier`

`company_identifier` can be:

* A domain, for example `stripe.com`
* A UUID

If you need a seed company first, use [Semantic Search](/api-guides/search/semantic-search) and prefer `results[].domain`.
Use `results[].id` only if `domain` is missing.

```bash theme={null}
COMPANY_IDENTIFIER="stripe.com"
```

### 2) Run lookalike query

```bash theme={null}
curl --get "https://api.extruct.ai/v1/companies/${COMPANY_IDENTIFIER}/similar" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"
```

### 3) Apply filters if needed

```bash theme={null}
curl --get "https://api.extruct.ai/v1/companies/${COMPANY_IDENTIFIER}/similar" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode 'filters={"include":{"country":["United States"]},"exclude":{"size":["1-10"]}}' \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"
```

For filter rules, use [Search Filters Reference](/api-guides/search/search-filters-reference).

To exclude specific companies (for example, ones you already have), add `exclude.domains` to your `filters`. For a list too large for a `GET` URL, use [`POST /v1/companies/:company_identifier/similar`](/api-reference/lookalike-search-post).

### 4) Page through results

* Page 1: `offset=0&limit=20`
* Page 2: `offset=20&limit=20`
* Page 3: `offset=40&limit=20`

Each request returns at most 250 results (the page size). Free tokens can read up to 25 results per query; paid plans (Starter, Pro) can page through up to 2,000. Keep advancing `offset` until you reach your plan ceiling or a page returns fewer rows than `limit`.

## Choosing a strong seed company

Lookalike quality depends heavily on the seed.
Use a company that clearly represents the market you want, not just a well-known brand in the general space.

Good seeds:

* Sell to the same buyer you care about.
* Have similar company shape or go-to-market motion.
* Are specific enough that "similar" means something useful.

Weak seeds:

* Very broad platforms with many unrelated products.
* Household names that dominate a category but are not representative.
* Companies that overlap only superficially with your target market.

If you do not trust any single seed, use [Semantic Search](/api-guides/search/semantic-search) first or move to [Deep Search](/api-guides/search/deep-search) for explicit criteria.
If you want the full profile for one known company instead of similar-company results, use [Company Lookup](/api-reference/company-lookup).

## Troubleshooting

### `401 Unauthorized`

The token is missing or invalid.
Check that `EXTRUCT_API_TOKEN` is set and the header is exactly `Authorization: Bearer ${EXTRUCT_API_TOKEN}`.

### `404 Not Found`

The reference company is not found in the index. Try another domain/UUID.
Reuse a known seed from semantic search (`results[].domain` or `results[].id`) to confirm identifier validity.

### `422 Unprocessable Entity`

The `filters` JSON is malformed or includes unsupported keys.
Validate your filters JSON before sending: `echo '<filters-json>' | jq empty`.