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

Anything you leave unset falls back to your saved routing preferences (below), then to the platform defaults in the table.

Saved preferences: change your tools without changing code

Every account has per-category routing preferences, editable in the dashboard’s Routing panel or via the API:

PUT /v1/routing
{
  "search": {
    "sort": "quality",
    "disabled": ["serper"]
  },
  "image": {
    "sort": "priority",
    "order": ["fal", "replicate", "openai-images"]
  }
}

Field	Meaning
sort	Default dimension: price | latency | quality | priority
order	Your manual provider order — used when sort is "priority"
disabled	Providers this account never routes to
fallbacks	Default failover behaviour

Preferences apply to every key on the account instantly — REST, SDK, and MCP calls alike. Precedence is always request routing → saved preferences → platform default, with one nuance: an explicit per-request providers allowlist also overrides your disabled list, so a one-off call can still reach a provider you’ve switched off.

GET /v1/routing returns your saved preferences alongside the full per-category provider catalog (prices, quality scores, availability), which is everything needed to build your own routing UI.

Raw provider payloads

The normalized schema is deliberately a common denominator, so premium providers’ extra fields (highlights, structured chunks, word timestamps…) are not lost — set include_raw: true on any search, scrape, parse, transcribe, or embed request and the response includes provider_raw: the winning provider’s unmodified payload alongside the normalized result.

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.