Routing and policies

GroundRoute routes each query to a single engine — the cheapest one that clears the query class's bar — and fails over if it errors. Routing decisions are recorded in routing_meta on every response.

Query classification

Each query is classified into one of five classes. mode and freshness take precedence; in auto/web mode, keyword signals can promote a query.

Class	Triggered by
`news`	`mode: news`, `freshness: fresh`, or news keywords ("latest", "today", "breaking", "announced", …)
`academic`	`mode: academic`, or academic keywords ("paper", "arxiv", "doi", "pubmed", "preprint", …)
`answer`	`mode: answer`
`page`	`mode: page`
`web`	`mode: web`, or `auto` with no promoting signal

The six engines

Engine	Cost per 1k (USD, list)	Strong for
`firecrawl`	$0.85	page / content extraction
`serper`	$1.00	web / SERP, news
`brave`	$5.00	web, news, academic
`perplexity`	$5.00	answer synthesis
`exa`	$7.00	academic / semantic
`tavily`	$8.00	answer / RAG

Costs are list prices used for the routing decision and the routing_meta.reason string; actual metered cost comes from the engine adapter. Firecrawl Standard is ~$0.85/1k; bot-protected "Enhanced Mode" is ~5× higher.

Default engine order per class

The static (failsafe) price-led order — index 0 is the first choice, the rest are failover targets:

Class	Order
`web`	serper → brave → exa
`news`	serper → brave
`academic`	exa → brave → serper
`answer`	perplexity → tavily → exa
`page`	firecrawl

The router picks the first engine in the order that is available with a usable key.

Routing strategies (default policy)

A workspace default policy re-ranks the class's candidate engines, so a saved policy changes which engine is actually chosen — not just the displayed order:

Policy	Effect
`price`	Curated price-led order (the day-one default).
`quality`	Re-rank by per-engine quality prior, highest first.
`latency`	Re-rank by per-engine latency prior, lowest first.
`balanced`	Blend of normalized cost, latency, and quality.

Ties keep the price-led order. The learned and fanout strategies are scaffolded but off by default — price_led is the live strategy.

Setting the default policy

Set the workspace default from the console, or via the console API:

curl -s -X PUT https://api.groundroute.ai/v1/console/settings \
  -H "Content-Type: application/json" \
  --cookie "gr_session=…" \
  -d '{"default_policy": "balanced"}'

default_policy must be one of price, quality, latency, balanced. The change takes effect on new searches within ~60s (a short routing cache is busted on save). GET /v1/console/settings returns the current value.

Automatic failover

If the chosen engine errors, GroundRoute attempts one synchronous failover to the next eligible engine in the order. The outcome is recorded in routing_meta:

failover_from — the engine that failed before the one that served the request.
degraded: true — at least one engine failed but at least one returned results. The response is still 200; this is partial success, not an error.
missing_engines — engines that were in the order but not available (e.g. no key).

If all eligible engines fail, the request returns an error envelope instead of partial results.

PreviousIntegrations NextCaching