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

# Vendor modes

> Pin a backend to one of its own tiers, contents or flags, priced as that mode, in one id grammar.

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.

```python theme={null}
from web_router import WebRouter

router = WebRouter()
router.search("...", provider="exa:exa-instant")        # Exa's instant search type
router.search("...", provider="exa:exa-instant+lite")   # the same, at the lite depth
router.search("...", provider="tavily:tavily-ultra-fast")
router.search("...", provider="brave:brave-extra-snippets")
```

The same id works as an `auto` chain entry, and a pinned backend is built with
its backend's `provider_config` entry:

```python theme={null}
router = WebRouter(
    provider="auto",
    provider_config={
        "auto": {"chain": {"search": ["exa:exa-instant", "tavily"]}},  # a pin is a search id
        "exa": {"api_key": "..."},  # also used for exa:exa-instant
    },
)
```

## 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

| Backend | Tiers | Contents | Flags |
| - | - | - | - |
| Exa | `exa-instant`, `exa-fast`, `exa-deep-lite`, `exa-deep`, `exa-deep-reasoning` | `exa-highlights` (as `lite`) | |
| Tavily | `tavily-fast`, `tavily-ultra-fast` | | |
| Parallel | `parallel-turbo`, `parallel-basic`, `parallel-advanced` | | |
| Linkup | `linkup-flash`, `linkup-standard`, `linkup-deep` | | |
| Perplexity | `perplexity-fast` | | |
| Keenable | `keenable-realtime` | | |
| You.com | | `you-full-page-cache` (as `deep`) | |
| Brave | | | `brave-extra-snippets` |
| DeepSeek | | | `deepseek-content` |

An extract backend declares tiers and flags only, since an extract has no
depth; a mode never writes the URLs:

| Backend | Tiers | Flags |
| - | - | - |
| Tavily | `tavily-advanced` | |
| Linkup | `linkup-pro` | `linkup-render-js` |
| Oxylabs | `oxylabs-render` | |
| Nimble | `nimble-vx8`, `nimble-vx8-pro`, `nimble-vx10`, `nimble-vx10-pro`, `nimble-max` | |
| Exa | | `exa-highlights`, `exa-summary` |
| Browserbase | | `browserbase-proxies` |

`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:

| Backend | Tiers |
| - | - |
| Exa | `exa-fast`, `exa-pro`, `exa-research` (`model`) |
| Linkup | `linkup-flash`, `linkup-standard`, `linkup-deep` (`depth`; unset is `fast`) |
| Perplexity | `perplexity-low`, `perplexity-medium`, `perplexity-high` (`effort`; unset is `fast`) |

`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`:

| Backend | Tiers |
| - | - |
| Browser Use | `browser-use-<model>` for `gpt-5.6-luna`, `gemini-flash-lite-latest`, `gemini-flash-latest`, `gemini-3-flash-preview`, `o3`, `claude-sonnet-5`, `claude-sonnet-4-5-20250929`, `claude-opus-4-8` (`llm`) |
| Skyvern | `skyvern-2.0`, `skyvern-3.0`, `skyvern-openai-cua`, `skyvern-anthropic-cua`, `skyvern-ui-tars` (`engine`) |

`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`:

```python theme={null}
router = WebRouter(router=my_router, 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:

```python theme={null}
RouteDecision(attempts=["search:exa:exa-instant", "search:exa:exa-deep", "search:tavily"])
```

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](https://docs.webrouter.net/smart-routing.md) for what a router picks today.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.