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

# Search Filters Reference

> Supported filters format for semantic and lookalike search.

## Overview

This page documents the `filters` JSON shape supported by semantic and lookalike 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

* [Search endpoint (`GET /v1/companies/search`)](/api-reference/search)
* [Lookalike endpoint (`GET /v1/companies/:company_identifier/similar`)](/api-reference/lookalike-search)
* [Search endpoint (`POST /v1/companies/search`)](/api-reference/search-post)
* [Lookalike endpoint (`POST /v1/companies/:company_identifier/similar`)](/api-reference/lookalike-search-post)

## Filters shape

On the `GET` endpoints, send `filters` as a JSON string (URL-encoded). On the `POST` endpoints, send `filters` as a native JSON object in the request body.

```json theme={null}
{
  "include": {
    "country": ["United States"]
  },
  "exclude": {
    "size": ["1-10"]
  },
  "range": {
    "founded": {
      "min": 2018,
      "max": 2024
    }
  }
}
```

All sections are optional.
`range.founded.max` shown here is an example value, not a product limit.

## Supported fields

| Field path          | Type       | Meaning                                                                            |
| ------------------- | ---------- | ---------------------------------------------------------------------------------- |
| `include.size`      | `string[]` | Keep these company size buckets.                                                   |
| `include.country`   | `string[]` | Keep these countries.                                                              |
| `include.city`      | `string[]` | Keep these cities.                                                                 |
| `exclude.size`      | `string[]` | Remove these company size buckets.                                                 |
| `exclude.country`   | `string[]` | Remove these countries.                                                            |
| `exclude.city`      | `string[]` | Remove these cities.                                                               |
| `exclude.domains`   | `string[]` | Remove companies by domain or URL (normalized server-side, alias-aware, max 1000). |
| `range.founded.min` | `integer`  | Keep companies founded on/after year.                                              |
| `range.founded.max` | `integer`  | Keep companies founded on/before year.                                             |

`exclude.domains` accepts company domains or full URLs; each is normalized to its registered domain, so `https://www.stripe.com/pricing`, `stripe.com`, and `blog.stripe.com` all exclude `stripe.com`. A large exclusion list does not fit a `GET` URL — use the `POST` endpoints for lists beyond a few hundred domains.

## Supported size values

Use exact values:

* `1-10`
* `11-50`
* `51-200`
* `201-500`
* `501-1000`
* `1001-5000`
* `5001-10000`
* `10001+`

## Copy-paste request example

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

For a large `exclude.domains` list, POST `filters` as a JSON object instead:

```bash theme={null}
curl -X POST "https://api.extruct.ai/v1/companies/search" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"q":"fintech treasury automation","filters":{"exclude":{"domains":["stripe.com","adyen.com"]}},"pagination":{"offset":0,"limit":20}}'
```

## Troubleshooting

### `422 Unprocessable Entity`

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

### Filter returns no results

Start broad, then narrow one filter dimension at a time.
Remove all but one filter group (`include`, `exclude`, or `range`) and re-run to find the limiting condition.