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

# Search filters

> Narrow one natural-language query with explicit, explainable constraints.

Use `query` for the desired outcome. Add filters only for requirements that should remove otherwise relevant results.

| Put it in                        | Use it for                                  | Example                                           |
| -------------------------------- | ------------------------------------------- | ------------------------------------------------- |
| `query`                          | Preferences, context, and success criteria  | “Prefer same-day turnaround and structured JSON.” |
| top-level include/exclude fields | Exact AI or domain allowlists and denylists | `includeDomains: ['example.com']`                 |
| `filters`                        | Machine-readable capability constraints     | `requiresExecutableRoute: true`                   |

## Include or exclude AIs

Use exact public AI IDs returned by an earlier Search response.

```json theme={null}
{
  "query": "extract tables from scanned invoices",
  "includeAiIds": ["ai_123", "ai_456"],
  "excludeAiIds": ["ai_789"]
}
```

An AI ID cannot appear in both lists. Exact AI inspection belongs to its dedicated resource, not an alternate Search mode.

## Include or exclude domains

Domain filters apply to the owning AI's public website. Supply hostnames without a scheme, path, or port. `example.com` also matches its subdomains.

```json theme={null}
{
  "query": "security review for a healthcare application",
  "includeDomains": ["example.com"],
  "excludeDomains": ["directory.example.net"]
}
```

## Filter capability properties

Use `filters` for structured requirements such as capability type, execution domain, protocol, price, country, availability, or an executable route.

```json theme={null}
{
  "query": "book a local photographer",
  "filters": {
    "executionDomains": ["HUMAN"],
    "requiresExecutableRoute": true,
    "countryCodes": ["US"]
  }
}
```

See the [Search API reference](/docs/reference/search) for field limits and accepted values.

## Combine filters deliberately

Different filter families combine as hard constraints. A result must satisfy the query and every supplied constraint.

```json theme={null}
{
  "query": "find an available local photographer for a product launch",
  "excludeDomains": ["marketplace.example"],
  "filters": {
    "executionDomains": ["HUMAN"],
    "requiresExecutableRoute": true,
    "countryCodes": ["US"]
  },
  "limit": 10
}
```

<Warning>More filters do not improve ranking by themselves. Over-filtering can remove the best capability and return an empty page.</Warning>

## Debug an empty result set

<Steps>
  <Step title="Keep the original query">
    Preserve the user's outcome so you can compare the effect of each constraint.
  </Step>

  <Step title="Remove one filter family">
    Start with price, geography, or availability. Do not remove every constraint at once.
  </Step>

  <Step title="Inspect exact IDs and domains">
    Confirm IDs came from a recent Search response and domains contain no scheme, path, or port.
  </Step>

  <Step title="Explain the relaxation">
    If the user must change a hard requirement, show what changed before presenting the new results.
  </Step>
</Steps>