17 routing strategies

Pick the right credential, every time

Each strategy is a pure function that takes the credential pool and the request context and returns the chosen credential (plus, optionally, an ordered fallback chain). The router runs the first matching rule's strategy and uses the result. If no rule matches,priority-failover is the default. The full registry lives atsrc/lib/server/router/strategies/index.ts.

How to configure a strategy

A routing rule has the shape below. The router matches rules bymatch.endpoint (path prefix), match.models, andmatch.tags. The first enabled rule with the lowest priority number that matches the incoming request wins.

{
  "name": "Chat to OpenRouter free",
  "enabled": true,
  "priority": 10,
  "match": {
    "endpoint": "/v1/chat/completions",
    "models": ["openai/gpt-4o-mini"]
  },
  "strategy": "priority-failover",
  "strategyConfig": {"maxRetries": 2},
  "credentialPool": ["cred_openrouter", "cred_openai"]
}

The 17 strategies

1round-robinRound Robin

Evenly distribute requests across the pool in order. A per-org, per-endpoint counter picks the next credential in the rotation.

When to use
You have multiple equivalent credentials and want to spread load evenly. Best when all credentials have similar cost, latency, and quota.
Example
{
  "strategy": "round-robin",
  "strategyConfig": {}
}
2weighted-randomWeighted Random

Random selection weighted by credential.weight. Higher-weight credentials get proportionally more traffic.

When to use
You want to bias traffic toward preferred credentials while keeping others warm. Useful for canary deploys and gradual rollouts.
Example
{
  "strategy": "weighted-random",
  "strategyConfig": {
    "defaultWeight": 1
  }
}
3priority-failoverPriority Failover

Use the highest-priority (lowest priority number) credential; fall to the next priority on failure. Builds an ordered fallback chain of up to maxRetries+1 credentials.

When to use
You have a primary provider and one or more backups. The primary should be the cheapest or fastest; backups take over on 429/5xx.
Example
{
  "strategy": "priority-failover",
  "strategyConfig": {
    "maxRetries": 3,
    "backoffMs": 200
  }
}
4least-latencyLeast Latency

Pick the credential with the lowest recent average latency (rolling window). Falls back to first-credential if no samples yet.

When to use
You have multiple credentials with similar cost but different speeds. Use when latency is the dominant concern and you can tolerate a few warm-up requests.
Example
{
  "strategy": "least-latency",
  "strategyConfig": {
    "windowMs": 300000,
    "minSamples": 5
  }
}
5lowest-costLowest Cost

Pick the credential whose model has the lowest estimated cost for the request token count. Falls back through the next cheapest.

When to use
Cost is the dominant concern. Requires costPerMTokensIn / costPerMTokensOut to be set on the credential extraConfig.
Example
{
  "strategy": "lowest-cost",
  "strategyConfig": {
    "includeImageCost": true
  }
}
6highest-qualityHighest Quality

Pick the credential with the highest quality tier. Tiers (highest to lowest) are flagship, premium, standard, economy.

When to use
You want the best output regardless of cost. Set tier on credential extraConfig so the strategy can rank.
Example
{
  "strategy": "highest-quality",
  "strategyConfig": {
    "tierOrder": ["flagship", "premium", "standard", "economy"]
  }
}
7randomRandom

Uniform random pick across the pool. Each enabled, non-rate-limited credential has equal probability of selection.

When to use
You want maximum distribution entropy. Useful for testing, canaries, and avoiding hot-spotting on a single credential.
Example
{
  "strategy": "random",
  "strategyConfig": {}
}
8sticky-sessionSticky Session

Hash the conversation id (or session id) to a stable credential. Repicks on failure. Subsequent requests with the same conversation id land on the same credential.

When to use
You need per-conversation consistency (e.g., provider-side context caching, provider-side rate limits per conversation). Requires a sessionId in the request body or header.
Example
{
  "strategy": "sticky-session",
  "strategyConfig": {}
}
9adaptive-healthAdaptive Health

Score each credential by success rate, latency, and error rate, then pick the highest. Weights are configurable; defaults are 0.5 / 0.3 / 0.2.

When to use
You want the engine to self-tune based on observed behavior. Best for production where credentials have variable reliability.
Example
{
  "strategy": "adaptive-health",
  "strategyConfig": {
    "weights": {"success": 0.5, "latency": 0.3, "errors": 0.2}
  }
}
10capacity-awareCapacity Aware

Pick the credential with the most remaining quota, taken from the extraConfig.remainingQuota field. Falls back through the next highest.

When to use
You have credentials with known quota limits and want to drain the highest-remaining first. Requires a webhook or scrape step to update remainingQuota.
Example
{
  "strategy": "capacity-aware",
  "strategyConfig": {}
}
11token-aware-costToken-aware Cost

Estimate input tokens from the request body, pick the cheapest credential that supports the request. Currently delegates to lowest-cost; full token-aware selection arrives in v2.

When to use
You have a mix of small-context and large-context credentials and want to push large requests to providers with cheaper large-context pricing.
Example
{
  "strategy": "token-aware-cost",
  "strategyConfig": {}
}
12latency-optimizedLatency Optimized

Least latency with a hard quality floor. Only considers credentials at or above a minimum tier; falls back to least-latency on the full pool if none match.

When to use
You want low latency but a guaranteed quality floor (e.g., never use economy models even if they happen to be fastest).
Example
{
  "strategy": "latency-optimized",
  "strategyConfig": {
    "minTier": "premium"
  }
}
13cost-optimizedCost Optimized

Lowest cost with a hard quality floor. Only considers credentials at or above a minimum tier; falls back to lowest-cost on the full pool if none match.

When to use
You want low cost but a guaranteed quality floor (e.g., never use economy models for production traffic).
Example
{
  "strategy": "cost-optimized",
  "strategyConfig": {
    "minTier": "standard"
  }
}
14region-optimizedRegion Optimized

Pick the credential whose region matches the client IP. Falls back to priority-failover when no region-tagged credential is available.

When to use
You have geo-distributed credentials and want to route to the closest one to minimize TLS handshake and TTFB.
Example
{
  "strategy": "region-optimized",
  "strategyConfig": {}
}
15tag-filteredTag Filtered

Filter the pool by required tags (matched against credential.extraConfig.tags), then apply a secondary strategy on the filtered pool.

When to use
You want to isolate traffic by capability or category (e.g., "only free providers" or "only enterprise") and then apply a normal strategy on the filtered set.
Example
{
  "strategy": "tag-filtered",
  "strategyConfig": {
    "require": ["free"],
    "then": "round-robin"
  }
}
16comboCombo

Delegate to a combo definition (multi-step orchestration). The routing rule references a combo id; the engine loads and executes it. See the Combos page.

When to use
You need multi-step orchestration across providers: fallback with conditions, parallel racing, speculative first-chunk wins, chained refinement, or per-step routing.
Example
{
  "strategy": "combo",
  "strategyConfig": {
    "comboId": "combo_abc"
  }
}
17fallback-chainFallback Chain

Try an explicit ordered list of credential ids in turn. Each credential in the chain is tried; if all fail, the last error is returned. Credentials not in the chain are appended as a safety net.

When to use
You know the exact order you want to try credentials in (e.g., "try my cheap one first, then the expensive backup, then the community free tier").
Example
{
  "strategy": "fallback-chain",
  "strategyConfig": {
    "chain": ["cred_a", "cred_b", "cred_c"],
    "retryOn": [429, 500, 503]
  }
}

Side-by-side comparison

IDNamePicks byFallback chain?Needs stats?
round-robinRound RobinCounter + pool indexNoNo
weighted-randomWeighted RandomRandom by weightNoNo
priority-failoverPriority FailoverPriority ascYes (up to maxRetries)No
least-latencyLeast LatencyAvg recent latencyYes (next 3)Yes (latency samples)
lowest-costLowest CostEst. cost per tokenYes (next 3)No
highest-qualityHighest QualityQuality tierYes (next 3)No
randomRandomUniform randomNoNo
sticky-sessionSticky SessionSession id hashRepick on failureNo
adaptive-healthAdaptive HealthSuccess / latency / errorsYes (next 3)Yes (full stats)
capacity-awareCapacity AwareRemaining quotaYes (next 3)No (reads extraConfig)
token-aware-costToken-aware CostInput tokens + costYes (delegates to lowest-cost)No
latency-optimizedLatency OptimizedLeast latency + tier floorYesYes
cost-optimizedCost OptimizedLowest cost + tier floorYesNo
region-optimizedRegion OptimizedClient IP vs regionFalls back to priority-failoverNo
tag-filteredTag FilteredTag filter + secondaryPer secondary strategyNo
comboComboCombo definitionPer combo typePer step
fallback-chainFallback ChainExplicit ordered listYes (entire chain)No

Strategy selection guidance

Default

If no routing rule matches the incoming request, AIRouter falls back topriority-failover over the org's full credential pool, ordered by ascendingpriority. This means even with zero rules configured, requests still work.

Production recommendation

Start with priority-failover (deterministic, easy to reason about). Add aleast-latency or adaptive-health rule for traffic where latency matters. Use lowest-cost for batch / async workloads. Reservecombo for orchestrated multi-step flows where a single strategy is not enough.

Per-credential metadata

Several strategies read fields from the credential's extraConfig:tier (string, e.g. "premium"),region (string, e.g. "us-east"),costPerMTokensIn / costPerMTokensOut (numbers, USD per million tokens),remainingQuota (number),tags (string array, e.g. ["free", "openai-compat"]),estimatedOutputTokens (number, default 500). Set these when adding a credential via the dashboard or admin API.