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

# Semantic Search

> Find companies from natural-language intent using the Search endpoint.

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

## Overview

Semantic Search is the recall-first company search path over the Extruct index.
Start with a natural-language query, then narrow with firmographic filters such as country, city, size, and founded year.

## This Path Works Best When

* You want broad market coverage before narrowing.
* You want to explore a category, use case, ICP, or problem space quickly.
* You expect filters to do most of the refinement work.

## Choose Another Path If

* You already know the company and want its full profile. Use [Company Lookup](/api-reference/company-lookup).
* You already have a strong seed company and want similarity ranking instead. Use [Lookalike Search](/api-guides/search/lookalike-search).
* You need custom ranking criteria and evidence-backed evaluation. 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)
* [Search endpoint (`GET /v1/companies/search`)](/api-reference/search)
* [Lookalike endpoint (`GET /v1/companies/:company_identifier/similar`)](/api-reference/lookalike-search)

## Workflow

### 1) Run a broad semantic query

```bash theme={null}
curl --get "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "q=vertical SaaS for logistics procurement" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"
```

### 2) Narrow with filters

```bash theme={null}
curl --get "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "q=b2b treasury automation" \
  --data-urlencode 'filters={"include":{"country":["United States"],"size":["51-200","201-500"]},"range":{"founded":{"min":2018}}}' \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"
```

For supported filter fields and values, use [Search Filters Reference](/api-guides/search/search-filters-reference).

To exclude specific companies, add `exclude.domains` to your `filters`. For a list too large for a `GET` URL, use [`POST /v1/companies/search`](/api-reference/search-post).

### 3) Page through results

Use fixed increments for stable pagination:

* 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`.

### 4) Expand top seeds with lookalike

After selecting a high-quality company from search results, prefer `results[].domain` as `company_identifier` for lookalike.
Use `results[].id` only if `domain` is missing.
Use [Company Lookup](/api-reference/company-lookup) with the same identifier when you want the full company profile instead of similar companies.

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

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

### 5) Escalate to Deep Search when filters are not enough

Move to [Deep Search](/api-guides/search/deep-search) when you can describe the companies you want in natural language, but firmographic filters still do not produce the ranking quality you need.
Typical signs:

* Results are relevant but poorly ordered.
* The distinction you care about is qualitative, not just firmographic.
* You need explicit scoring and explanations for each candidate.

## 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}`.

### `422 Unprocessable Entity`

The `filters` JSON is malformed or includes unsupported keys. Use only keys listed in [Search Filters Reference](/api-guides/search/search-filters-reference).
Validate your filters JSON before sending: `echo '<filters-json>' | jq empty`.