> ## Documentation Index
> Fetch the complete documentation index at: https://docs.andiai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Search modes
> Andi sets the right search effort for every query automatically — or you can pin the effort level yourself with searchMode.
Every query needs a different amount of work. A currency conversion resolves in a single fast pass. A literature review needs multiple rounds of retrieval. The `searchMode` parameter controls who decides how much work each search gets: Andi, or you.
* **`auto` (default)** — Andi reads each query and sets the compute, models, and search depth it needs. No tuning required.
* **Fixed modes** — pin an effort level (`low-cost`, `fast`, `balanced`, `deep`, `exhaustive`) when you want the same behavior on every call.
## Automatic mode
When you omit `searchMode` (or set `searchMode=auto`), Andi decides per query how much effort the search needs. Simple lookups and navigational queries resolve fast. Complex, multi-faceted, or research questions get deeper treatment — query expansion, more search angles, follow-up searches, stronger reranking, spell correction. Multi-query requests get deep coverage automatically.
```bash theme={null}
curl "https://api.andiai.com/api/v1/search?q=climate+change+effects" \
-H "x-api-key: YOUR_API_KEY"
```
You are charged for the work each search actually performs, not a flat per-call rate — so simple queries stay cheap even when your traffic mix includes hard ones. The billed amount is returned in every response as `metrics.cost_dollars`.
Use `auto` unless you have a specific reason not to. It adapts as your query mix changes, so you never have to retune mode choices as your application grows.
To see which mode a request resolved to, use `format=context` — the response frontmatter includes a `search_mode` field.
## Setting the effort yourself
When you want the same effort on every call — a hard latency budget, a cost ceiling, or research-grade coverage regardless of query — pin a mode:
| Mode | Typical response | What it does |
| ------------ | ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `low-cost` | \~1–2s | Budget-constrained search. More coverage than `fast`, with a cost ceiling. |
| `fast` | \~1s | Single-pass search. Lowest latency. |
| `balanced` | \~1–2s | Everyday web search. Solid coverage and ranking without deep-mode latency. |
| `deep` | \~2–3s | Searches from multiple angles. Spell correction. Higher-quality results for complex queries. |
| `exhaustive` | Up to \~15s | Multi-round agentic retrieval. Keeps searching until it finds strong matches. Research-grade thoroughness. |
```bash theme={null}
curl "https://api.andiai.com/api/v1/search?q=climate+change+effects&searchMode=deep" \
-H "x-api-key: YOUR_API_KEY"
```
### Choosing a mode
* Use `fast` when latency matters most: autocomplete, real-time UIs, high-volume batch jobs.
* Use `low-cost` when per-call spend matters most and you can trade some speed for coverage.
* Use `balanced` for general-purpose search when you want predictable mid-range latency.
* Use `deep` when result quality matters more than speed: research questions, multi-faceted topics, queries that might contain typos.
* Use `exhaustive` for tasks where missing a result is worse than waiting: due diligence, competitive analysis, literature review.
### What higher effort buys
Moving up the ladder does more than allow extra time. Deeper modes expand your query into related variations, fan out follow-up searches based on what the first pass finds, and apply stronger semantic reranking. `auto` uses the same machinery, scaled to what each query needs.
## The `effort` parameter
`effort` pins the same ladder as `searchMode`, using generic tier names instead of Andi's mode names — a second way in for agents that already speak a generic effort convention.
| Tier | Equivalent mode |
| -------- | --------------- |
| `low` | `fast` |
| `medium` | `balanced` |
| `high` | `deep` |
| `max` | `exhaustive` |
```bash theme={null}
curl "https://api.andiai.com/api/v1/search?q=climate+change+effects&effort=high" \
-H "x-api-key: YOUR_API_KEY"
```
An explicit `searchMode` always wins over `effort` — if you send both, the named mode applies. Left at the default `auto`, an explicit `effort` pins its equivalent mode, same as naming that mode directly. Inside `low-cost`, `effort` shapes thoroughness within that lane's own pricing and limits rather than leaving the lane.
Invalid values return a `400` listing the valid tiers: `low`, `medium`, `high`, `max`.
The resolved tier is echoed back in `metrics.effort` (JSON) and `effort` in the frontmatter (`format=context`):
```yaml theme={null}
---
search_mode: "deep"
effort: "high"
---
```
`effort` also works on [`/api/v1/fetch`](/search/content-retrieval#using-the-effort-parameter), shaping how thoroughly a page is retrieved.
## The `reranker` parameter
The `reranker` parameter controls the strength of semantic reranking applied to your results:
| Value | Reranking strength |
| ---------------- | ------------------------------------------------------------------- |
| `auto` (default) | Chosen based on query and mode |
| `small` | Light reranking, fastest |
| `medium` | Moderate reranking |
| `large` | Strong reranking |
| `xl` | Strongest reranking — requires a `deep` or `exhaustive` mode budget |
Stronger reranking improves result ordering for complex or ambiguous queries, at the cost of additional latency. The `auto` default picks an appropriate level based on your `searchMode` and query.
```bash theme={null}
curl "https://api.andiai.com/api/v1/search?q=effects+of+sleep+deprivation+on+cognition&searchMode=deep&reranker=large" \
-H "x-api-key: YOUR_API_KEY"
```
## Pricing
Search requests are priced on outcome: the charge reflects the actual work the search performed. With `auto`, that means the price follows the effort Andi chose for each query. With a pinned mode, cost is more uniform call to call. The billed amount is returned in every response as `metrics.cost_dollars` (JSON) or `cost_dollars` in the frontmatter (`format=context`).
```json theme={null}
{
"metrics": {
"cost_dollars": 0.0043,
"duration": 1240,
"results_returned": 10
}
}
```
## MCP tool
Agents using the [Andi Search MCP server](/resources/ai-agents#andi-search-mcp-server) control the same behavior through the `andi_web_search` tool — its `searchMode` and `effort` parameters accept the values on this page.
## Examples
### Auto mode (recommended)
```bash theme={null}
curl "https://api.andiai.com/api/v1/search?q=CRISPR+gene+therapy+clinical+trials" \
-H "x-api-key: YOUR_API_KEY"
```
### Pinned fast mode for a real-time UI
```bash theme={null}
curl "https://api.andiai.com/api/v1/search?q=USD+to+EUR&searchMode=fast" \
-H "x-api-key: YOUR_API_KEY"
```
### Pinned exhaustive mode for research
```bash theme={null}
curl "https://api.andiai.com/api/v1/search?q=CRISPR+gene+therapy+clinical+trials+2026&searchMode=exhaustive&limit=40" \
-H "x-api-key: YOUR_API_KEY"
```
## Next steps
When to pin fast mode and what to expect.
Multi-angle search with spell correction.
Full parameter reference.
Response structure and metrics fields.