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

# Multi-query search

> Search multiple queries and providers with fanout or ordered fallback.

# Multi-query search

Kestrel Search accepts repeated queries and search engines. It normalizes and
deduplicates both lists while preserving their order.

## Add related queries

Use a positional primary query and repeat `--query` for related queries:

```bash theme={null}
kestrelsearch search "python typing" \
  --query "pyright documentation" \
  --query "mypy release notes"
```

You can also use `--query` for every query; a positional query is not required:

```bash theme={null}
kestrelsearch search \
  --query "python typing" \
  --query "pyright documentation" \
  --query "mypy release notes"
```

## Choose fanout mode

Fanout runs every query and engine pair. This maximizes coverage and tolerates
partial provider failures.

```bash theme={null}
kestrelsearch search "python typing" \
  --query "pyright documentation" \
  --engine duckduckgo \
  --engine bing \
  --mode fanout \
  --search-concurrency 4
```

The example can run up to four query-provider requests concurrently.

## Choose fallback mode

Fallback treats the engines as an ordered preference list. For each query,
Kestrel tries the next engine only when the previous engine fails.

```bash theme={null}
kestrelsearch search "python typing" \
  --engine duckduckgo \
  --engine bing \
  --engine yahoo \
  --mode fallback
```

Different queries still run concurrently in fallback mode.

## How results are combined

Kestrel Search round-robins the result lists so one query or engine does not
occupy every early candidate slot. Canonically equivalent URLs are merged, and
their contributing query and engine occurrences are retained in `sources`.

When ranking is enabled, results are ranked within their originating-query
groups and interleaved again. See [ranking and fairness](/concepts/ranking-and-fairness).