Routing

Every tool request accepts a routing block:

{
  "routing": {
    "sort": "price",
    "providers": ["brave", "serper"],
    "fallbacks": true
  }
}

Field	Default	Meaning
sort	"price"	price | latency | quality
providers	all	Optional allowlist of provider ids (see GET /v1/tools)
fallbacks	true	When false, only the top-ranked provider is tried

How selection works

1. Candidates — all providers for the category, intersected with your providers allowlist, minus any provider that can’t serve the request (e.g. an image model it doesn’t host).
2. Circuit breaker — providers with an error rate above 30% over the last 5 minutes are skipped while a healthy alternative exists.
3. Sort — by static price (price), live rolling p50 latency (latency), or curated quality score (quality). Ties break on the other two dimensions.
4. Failover — the top candidate is called with a per-category timeout. On timeout, 5xx, 429, or a malformed response, the next candidate is tried (up to 3 attempts). Only the winning provider is billed.

The full attempt chain is returned in routing.attempted on every response, so routing decisions are never a black box.

Latency data

Live latency/error stats are collected per provider over a rolling 5-minute window and refreshed every ~30 seconds. A provider with no recent traffic falls back to its catalog-default latency.