Routing

Routing per query

Routing per query is the default: Grounder sends each query to the provider, or pair of providers, most likely to answer it well, and keeps learning which that is.

{
  "query": "what is the half-life of caffeine",
  "requested_provider": "tavily"
}

{
  "routing": {
    "policy": "ranked",
    "calls": [
      { "provider": "perplexity", "status": "ok", "latency_ms": 194, "result_count": 3 },
      { "provider": "exa", "status": "ok", "latency_ms": 2158, "result_count": 3 }
    ]
  }
}

The response’s routing.calls shows where the query went: here the router sent the query to Perplexity and Exa together. To decide yourself, pin one provider with requested_provider or fan out with providers. A search that names no provider reports ranked in routing.policy; one that names providers reports fanout. A key carries no routing policy of its own.

Account settings

Your account’s own choices apply to every search it makes, over the API and MCP alike. Under Routing on your account page, set the mode of every search, turn each provider On, Always or Off and choose its modes, add your own key for a provider so its searches run on your key, turn each specialized API On, Always or Off or add your key for it, choose how many of the best providers each search goes to at once (their top sources are returned together), and say how much accuracy, speed, results returned, recent sources and low cost matter. A provider set to Off is never called, even when a search names it; one set to Always gets every search that names no provider.

Sources

Allowed sources only, in the same place, is off until you turn it on. On, Grounder searches as before, but returns a result only from a site whose robots.txt allows the provider that found it and does not opt out of search or AI answers. A result a site disallows, for that provider or by opting out, is replaced, by the same page from another provider that is allowed, else by Ozone’s publisher content from the same site when Ozone licenses it, else by a result from another provider’s search; a result that could not be checked in time is left out, so a search can return fewer results than it would otherwise. Ozone’s publisher content and the specialized APIs are not crawls of the open web, so they are always allowed. The response then reports allowed, described under Search.

Licensed sources only, beside it, is on until you turn it off, and applies to every search your account makes. On, Grounder searches as before, also asks Ozone beside the first provider when the search names none, and returns only licensed results: Ozone’s publisher content and pages on sites Ozone licenses, each with provenance.licensed set to true. A search returns what is licensed, so it can return fewer results than it asked for, and is never filled with unlicensed ones. The specialized APIs’ values are data feeds and are always returned. A search that names its providers is filtered the same way and makes no added call. When both settings are on, a result must pass both. Turn it off on your account page, or send {"licensed_only": false} to PUT /v1/me/routing, to get every source again.

Caps

Caps, in the same place, are off until you set them. Each search can be held to a time, which stops the providers it calls; to a number of tokens, counted at about 4 characters a token, the lowest results cut and then dropped to fit; to a number of provider calls; and to a number of sources. A monthly cap on searches, tokens or search time refuses your searches with cap_reached (HTTP 429) once the month’s count reaches it, until the 1st, UTC. How you used Grounder, at the top of the same page, shows the figures of the benchmark pages’ results tables from your own searches: the share graded correct, tokens, search latency, provider calls and sources per search, and the share of results from licensed publishers, beside the average provider on its SimpleQA and SealQA tables.

Settings for one search

Your agent can change any of these for one search. Send routing_settings with the search, in the shape the account page saves: each part replaces your saved choice for that search alone, and nothing is saved. Weights take 0 (ignore), 0.5, 1 (the default), 2 or 3 (most). A search’s caps only lower yours, never raise them, and the monthly caps are set on the account page only. The MCP search tool takes the same field; user_info, or GET /v1/account/routing with your key, reads your saved settings and what each can be set to.

{
  "query": "is the 6:40 train to Milwaukee on time",
  "routing_settings": {
    "weights": { "speed": 3, "accuracy": 2 },
    "allowed_only": true,
    "caps": { "search": { "time_ms": 3000 } }
  }
}