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
round-robinRound RobinEvenly distribute requests across the pool in order. A per-org, per-endpoint counter picks the next credential in the rotation.
weighted-randomWeighted RandomRandom selection weighted by credential.weight. Higher-weight credentials get proportionally more traffic.
priority-failoverPriority FailoverUse 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.
least-latencyLeast LatencyPick the credential with the lowest recent average latency (rolling window). Falls back to first-credential if no samples yet.
lowest-costLowest CostPick the credential whose model has the lowest estimated cost for the request token count. Falls back through the next cheapest.
highest-qualityHighest QualityPick the credential with the highest quality tier. Tiers (highest to lowest) are flagship, premium, standard, economy.
randomRandomUniform random pick across the pool. Each enabled, non-rate-limited credential has equal probability of selection.
sticky-sessionSticky SessionHash 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.
adaptive-healthAdaptive HealthScore each credential by success rate, latency, and error rate, then pick the highest. Weights are configurable; defaults are 0.5 / 0.3 / 0.2.
capacity-awareCapacity AwarePick the credential with the most remaining quota, taken from the extraConfig.remainingQuota field. Falls back through the next highest.
token-aware-costToken-aware CostEstimate 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.
latency-optimizedLatency OptimizedLeast 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.
cost-optimizedCost OptimizedLowest 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.
region-optimizedRegion OptimizedPick the credential whose region matches the client IP. Falls back to priority-failover when no region-tagged credential is available.
tag-filteredTag FilteredFilter the pool by required tags (matched against credential.extraConfig.tags), then apply a secondary strategy on the filtered pool.
comboComboDelegate to a combo definition (multi-step orchestration). The routing rule references a combo id; the engine loads and executes it. See the Combos page.
fallback-chainFallback ChainTry 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.
Side-by-side comparison
| ID | Name | Picks by | Fallback chain? | Needs stats? |
|---|---|---|---|---|
round-robin | Round Robin | Counter + pool index | No | No |
weighted-random | Weighted Random | Random by weight | No | No |
priority-failover | Priority Failover | Priority asc | Yes (up to maxRetries) | No |
least-latency | Least Latency | Avg recent latency | Yes (next 3) | Yes (latency samples) |
lowest-cost | Lowest Cost | Est. cost per token | Yes (next 3) | No |
highest-quality | Highest Quality | Quality tier | Yes (next 3) | No |
random | Random | Uniform random | No | No |
sticky-session | Sticky Session | Session id hash | Repick on failure | No |
adaptive-health | Adaptive Health | Success / latency / errors | Yes (next 3) | Yes (full stats) |
capacity-aware | Capacity Aware | Remaining quota | Yes (next 3) | No (reads extraConfig) |
token-aware-cost | Token-aware Cost | Input tokens + cost | Yes (delegates to lowest-cost) | No |
latency-optimized | Latency Optimized | Least latency + tier floor | Yes | Yes |
cost-optimized | Cost Optimized | Lowest cost + tier floor | Yes | No |
region-optimized | Region Optimized | Client IP vs region | Falls back to priority-failover | No |
tag-filtered | Tag Filtered | Tag filter + secondary | Per secondary strategy | No |
combo | Combo | Combo definition | Per combo type | Per step |
fallback-chain | Fallback Chain | Explicit ordered list | Yes (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.