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.
auto chain entry, and a pinned backend is built with
its backend’s provider_config entry:
The id
An id isprovider[: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:
- 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 setsearch_depth; - a depth: a normalized level (
lite,fast,deep;lowtomaxfor 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; - 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-contenttakesdeep, which sends the page body too, but notlite. Two flags on one field never combine.
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 yourprovider_options:
- a content replaces the fields it writes;
- a tier or a flag is merged into nested objects;
provider_optionsstill go last, as they always have.
What is refused
A mode is refused withInvalidParameterError, before anything is sent, when
you set something it would overwrite:
- a
provider_optionskey the mode writes ({"type": ...}besideexa-instant); - a
search_depthother than the one the mode names (exa:exa-instant+litewithsearch_depth="deep"), or other than the level a content stands for; - an option that writes the same field to another value: Exa’s
effortwith an Exa tier, Tavily’ssearch_depthwith a Tavily tier, Parallel’s or Keenable’seffortwith one of their tiers, DeepSeek’slitewithdeepseek-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:- the row for the canonical mode;
- else its tier’s row, when that row assumes the mode’s depth, plus each flag’s added price;
- else unknown.
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, withroute_modes=True:
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 withRouteDecision.attempts: candidate ids, best first,
which replace tools and providers when set. One backend may appear in
several modes:
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
localortargeterror) 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=orBudget(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.
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 declareroute_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.