Routing & Fallback

Model slugs

Every routable capability is addressed by a slug in the form provider/model[:variant]. The provider segment identifies the upstream vendor; the model segment names the specific model or search mode; the optional variant tweaks how routing selects among providers.

provider/model[:variant]

exa/neural
openai/text-embedding-3-small
cohere/rerank-v3.5
perplexity/sonar
exa/neural:floor

Browse the full catalog on the Models page.

Default routing behavior

With no provider object and no sort, SearchRouter picks the cheapest healthy provider for the requested capability. On an error (429, 5xx, or timeout) it falls through to the next candidate. The provider that actually served the request is reported in response.provider.

The provider object

Pass a provider object on any request to override the defaults. All fields are optional.

{
  "model": "exa/neural",
  "query": "best vector databases for RAG 2026",
  "provider": {
    "order": ["exa", "tavily", "serper"],
    "allow_fallbacks": true,
    "sort": "price"
  }
}

order vs. only vs. ignore

• order sets a preference sequence but still allows fallback to others unless allow_fallbacks: false.
• only is a hard allowlist - nothing outside the list is ever used.
• ignore is a hard blocklist - listed providers are removed from the candidate pool.

{
  "model": "searchrouter/auto-search",
  "query": "...",
  "provider": {
    "only": ["exa", "tavily"],
    "ignore": ["serper"]
  }
}

Cross-model fallback

Instead of a single model, pass a models array to fall back across different models (and providers) in order - the same pattern as OpenRouter's model fallback array:

{
  "models": ["exa/neural", "tavily/search", "serper/google"],
  "query": "best vector databases for RAG 2026"
}

Fan-out & fusion - mix and match

Unlike an LLM call, a search call has many partial answers across providers that can be combined. Set mode: "fanout" (the default is "fallback") to query several providers at once and fuse their rankings into one list. Provide a models array to choose the members, or omit it to fan out across every search provider.

{
  "model": "searchrouter/auto-search",
  "query": "best vector databases for RAG",
  "num_results": 10,
  "mode": "fanout",
  "fuse": "rrf"
}

Members run concurrently; results are deduped by URL and fused with Reciprocal Rank Fusion (fuse: "rrf", score = Σ 1/(k + rank)) so results multiple engines agree on rank highest. Each fused result carries a sources array showing which providers returned it and at what rank. only / ignore filter the set; each provider call is billed and appears in rankings independently.

{
  "provider": "fanout:brave+exa+tavily",
  "search_type": "fanout",
  "results": [
    {
      "title": "...", "url": "...", "score": 0.049,
      "sources": [
        { "provider": "tavily", "rank": 1 },
        { "provider": "brave",  "rank": 2 },
        { "provider": "exa",    "rank": 4 }
      ]
    }
  ],
  "usage": { "requests": 3, "results": 10, "cost": 0.016 }
}

The auto-search router

Use the meta-model searchrouter/auto-search to let SearchRouter pick the best search provider per query - weighing query characteristics, provider health, price, and quality. Combine it with a provider object to constrain the pool or set an objective.

{
  "model": "searchrouter/auto-search",
  "query": "papers on retrieval-augmented generation",
  "num_results": 10
}

Slug variants

Append a variant to any slug to express a routing preference inline, without a provider object:

{ "model": "cohere/rerank-v3.5:floor", "query": "...", "documents": [] }