Skip to main content
A backend often sells several ways to run the same search: Exa’s instant and deep search types, Tavily’s ultra-fast tier, Linkup’s deep depth, Brave’s extra snippets. web-router’s normalized options (search_depth, effort) reach some of them; a vendor mode names the rest, so you can pin one, see what it costs, and keep a budget honest.
The same id works as an auto chain entry, and a pinned backend is built with its backend’s provider_config entry:

The id

An id is provider[:mode], or search:provider[:mode] (extract:, answer:, browse:) with the method named. A mode has up to three slots, joined with +, always in this order:
  1. a tier: a vendor setting (Exa’s type). It combines with a depth unless both write one field, as Tavily’s tiers and depths both set search_depth;
  2. a depth: a normalized level (lite, fast, deep; low to max for an effort), or a content: a vendor setting that replaces what a depth sends (Exa’s highlights instead of page text), standing for one level;
  3. flags, sorted: add-ons that write a field no tier writes (Brave’s extra snippets), so they combine with any tier. A flag combines with a depth unless the depth sends its field another way: deepseek-content takes deep, which sends the page body too, but not lite. Two flags on one field never combine.
Each vendor part is spelled with its backend’s name first (exa-instant), so it can never be read as a normalized level. Input in any order comes out canonical: exa-highlights+exa-instant is exa-instant+exa-highlights. web_router.modes.parse_id reads an id; an unknown part, or a slot filled twice, raises InvalidParameterError.

What each backend declares

An extract backend declares tiers and flags only, since an extract has no depth; a mode never writes the URLs: extract(urls, provider="tavily:tavily-advanced") pins one, as does the same id in an extract chain. When a chain retries the URLs one member failed on the members after it, each runs the retried URLs in its own pinned mode. Nimble publishes no price per driver, so its drivers other than nimble-max are unpriced, and never run under a cost cap. An answer backend declares tiers only; a mode never writes the question: answer(question, provider="linkup:linkup-deep") pins one, as does the same id in an answer chain. Linkup prices each depth; Exa publishes one /answer price that names no model, so its tiers are unpriced (the response still states its own cost), and Perplexity bills tokens, so its tiers are unknown before the call. A browse backend declares tiers only; a mode never writes the task or start_url: browse(task, provider="browser-use:browser-use-o3") and submit_browse pin one. Browser Use prices each model per agent step and Skyvern sells credits by plan, so no browse tier has a price before the task runs, and none runs under a cost cap. Each provider class carries its parts (ExaProvider.tiers, .contents, .flags), with the request-body change each one makes. Tavily’s tavily-fast is Tavily’s own tier, not web-router’s fast depth, which sends advanced. A backend’s contract (contracts/<method>/<provider>.json) lists the body change of every part under options.mode, and the modes a router may pick under offers: each tier at the default depth, each depth level and content at the default tier, and each flag. verified["mode.<part>"] says whether a live call has shown the part changing what comes back, or which documentation page it was written from.

What is sent

The mode is merged into the request body web-router builds, before your provider_options:
  • a content replaces the fields it writes;
  • a tier or a flag is merged into nested objects;
  • provider_options still go last, as they always have.

What is refused

A mode is refused with InvalidParameterError, before anything is sent, when you set something it would overwrite:
  • a provider_options key the mode writes ({"type": ...} beside exa-instant);
  • a search_depth other than the one the mode names (exa:exa-instant+lite with search_depth="deep"), or other than the level a content stands for;
  • an option that writes the same field to another value: Exa’s effort with an Exa tier, Tavily’s search_depth with a Tavily tier, Parallel’s or Keenable’s effort with one of their tiers, DeepSeek’s lite with deepseek-content;
  • a level the request has no option for: an extract, answer or browse mode names no depth (tavily:tavily-advanced+lite).

What it costs

A pinned search, extract, answer or browse task is priced as its mode, by the price list’s order:
  1. the row for the canonical mode;
  2. else its tier’s row, when that row assumes the mode’s depth, plus each flag’s added price;
  3. else unknown.
An extract’s price is per URL. That price is the response’s cost_usd (cost_source="estimated" unless the backend states one), and what a budget charges. An unknown price never fits under a cost cap. Cooldowns stay keyed by backend: a rate limit on one mode cools every mode of that backend.

Benchmarks

A provider scan’s setup is the same id (--providers tavily,tavily:fast,tavily:tavily-ultra-fast). The old spelling tavily@deep still runs. tavily:ultra-fast@deep parses, so an older scan’s rows still read, but a search with it is refused: Tavily’s tier and deep both set search_depth. tavily:ultra-fast without @ is no vendor mode, and tavily:fast is the fast depth, where an older scan meant Tavily’s tier.

Showing modes to a router

A router can be shown each search backend’s modes as candidates of their own, opt in, with route_modes=True:
Each backend’s candidate (search:exa) is then followed by one per mode it offers (search:exa:exa-instant), with mode set and its own estimated cost and p90. A mode the request rules out — a search_depth you set that it would overwrite, a provider_options key it writes — is left out, recorded with why, and a budget prefilters modes as it does backends. A router that declares a route_modes attribute opts itself in; yours, when you pass one, wins. The built-in routers declare False. The remote router is shown modes only when its router_config sets "route_modes": True: your True does not opt it in, and your False turns modes off for it too. A fallback member that does not opt in is shown backends only. A remote request carries at most 64 candidates in all: past that, the modes lowest in their method’s order are left out.

A router picks modes

A router picks modes with RouteDecision.attempts: candidate ids, best first, which replace tools and providers when set. One backend may appear in several modes:
Each attempt runs in its own mode. The mode replaces any search_depth or effort the router set in params; every other option still applies, and a search_depth you set binds every attempt. The call’s backends that attempts does not name in any mode run after them, at their default mode: a backend named only in its modes runs in those modes alone. Excluding search:exa excludes every Exa mode; excluding search:exa:exa-deep excludes that one only. As with any exclusion, one that would leave the method nothing to run is ignored: if the excluded mode is the only one attempts names and the call has no other backend, that mode still runs. Under a cost cap the router’s order is kept. When an attempt fails:
  • A backend that refuses the mode’s request (a 400 or 422, and not out of credit) is not charged for it, and its next attempt runs.
  • A failure that no other backend could do better on (a local or target error) raises, as it does without modes.
  • A timeout (a 408 included) in search, extract or answer moves to the backend’s next attempt when that mode’s measured p90 fits the time the call has left (timeout= or Budget(time_limit_s=...)). With no time limit, no measured p90, or too little time left, it stops the backend as below. The timed-out attempt stays charged. Research and browse always stop, since a job that timed out may already be running.
  • Any other failure, an auth error, a 429 or a 5xx among them, stops that backend for the call: its later attempts are passed over, each recorded as backend_failed. A 429 or 402 cools down the backend, every mode with it, as it always has.
The decision record lists each attempt by its full id, with mode set, and the answer’s cost_usd is the price of the mode that answered.

Deciders and the built-in routers

The built-in routers declare route_modes=False; pass route_modes=True to show them modes. A decider’s option for a mode names it and says what each of its parts does, such as search on exa in mode exa-instant (Exa's instant search, its fastest), $0.005, p90 0.9s, so no two modes of one backend read the same. When it ranks a mode, its decision fills attempts. A decider that scores its options has the backend and its modes scored apart: the backend’s own id (search:exa) scores the backend, and each of its modes takes its share of that backend’s mode scores. Attempts rank by the product, so with search:exa at 0.6, search:tavily at 0.4, and Exa’s instant and deep modes at 0.7 and 0.3, the order is exa-instant (0.42), tavily (0.40), exa-deep (0.18). Across methods, the order the decider first names them in is kept, so splitting a backend’s score over its modes never moves the call to another method. A backend whose modes are scored runs in those modes. Without a score for every ranked id, or for a ranked mode’s backend, the attempts keep the decider’s order. cheapest_first shown modes answers attempts for the method the call runs: each backend and mode by its own estimated cost. rules picks the method only, so it never names one.

Not yet

Routing on modes is opt-in and covers search only: an extract, answer or browse mode runs only when you pin it. Research has no vendor modes yet. See Smart routing for what a router picks today.