Providers and tiers

One request goes to the router, which holds the provider keys. A tier says how wide the router fans it out, and is also a per-query cost ceiling.

The core providers

In the balanced and max tiers, the eleven core arms run on every fan-out, under a per-query cost ceiling. fast asks three fast indexes, one from each group, and answers in about a second.

kind	arms
web indexes	Exa, Brave, Serper, SerpAPI, Telem, Parallel search, TinyFish
answer engines	OpenAI web search, Perplexity, Perplexity search
research agents	Parallel (slow lane: it keeps working after the response and lands on the trace)

Thirteen more fire only when a request names them in providers: Tavily and Tavily research, Linkup and Linkup answer, Valyu, Kagi, Mojeek, Gemini, Grok, Exa answer, Brave answer, the Perplexity agent and Octen. The set is the router's and changes without a client release. decision in every response says which arms ran.

What a search returns

The router runs the request against the arms and answers once:

• result.merged: the citations of every provider that answered, deduplicated by page. Each entry carries found_by, the providers that found that page, and best_rank, the best position any of them gave it. Agreement between independent indexes is the fan-out's own evidence, and the skill tells the agent to read this list first.
• result.candidates: each provider's answer as it came back, so a disagreement can be inspected rather than averaged away. "view":"merged" drops this when tokens matter.
• decision: which providers ran, decision.trimmed for any the ceiling cut, and decision.requested when the request named its own set. An arm that was skipped carries a reason, such as breaker_open or provider_capacity, which means the router already had its share of calls in flight to that provider across every tenant; the rest of the fan-out still answers.
• usage.cost_micros: what the search cost, in millionths of a dollar. latency_ms: for the search and for each provider. request_id: so a search can be found again on the platform.

See the envelope for every field.

The three tiers

tier	what runs	for
fast	three fast indexes, one from each group, in about a second	a routine lookup, the default for a new key
balanced	the full core set, 8 results per arm, each attributed to its source	when the agent needs more than one source, or the first answer came back thin
max	the full core set, 15 results per arm, a wider page window and longer excerpts	corroboration: the same page found by independent indexes

A tier is also a per-query cost ceiling on the router. A set of arms that would exceed the ceiling is trimmed rather than refused, with decision.trimmed naming what went.

Naming your own providers

providers in a request runs exactly the arms you name, and the response records it as decision.requested. It needs balanced or max: on fast the router answers 400 invalid_request, because the fast set is the router's to choose. A named set is not a fan-out, so its trace carries no comparison between providers; that is why it earns nothing under mining. See Request options.

Who chooses

• You, out of band. /jevlin tier balanced in an agent, or jevlin agents tier balanced from a shell, sets the band every search carries unless a request names one. /jevlin tier default unsets it, and /jevlin tier says what is in force. See Choosing a band.
• The agent, one step at a time. The skill tells it to leave tier alone so your band applies, to ask for balanced when it needs several sources, and never to send max on its own. max is yours to choose.
• The router, when nobody did. A request with no tier and no band set carries none, and the router applies the default for your key.

Spend

jevlin limits          # this key's spend caps and today's spend, read from the router
jevlin limits -json    # the same as one envelope

Reading spends nothing. Setting caps from the command line is not built yet; the platform's Limits page shows the same figures.