OmniRoute Tiers — User Guide

OmniRoute organizes the 207+ supported providers into 3 economic tiers. Each request travels through them in order until one returns successfully — you get the cheapest viable response without ever writing fallback code.

Tier 1 — Subscription

Providers you already pay for. OmniRoute uses every drop of quota before it expires.

Strategy: route here first for every request that fits the model's strengths. Quota tracker monitors approaching reset; combo strategies reset-aware and subscription prioritize accordingly.

Tier 2 — Cheap

Pay-per-token providers under $1/1M tokens. Reserved for high-volume work or after Tier 1 quotas hit limits.

Strategy: combo cost-optimized picks lowest $/token model that meets the task's capability filter (vision, JSON mode, tools, max-context).

Tier 3 — Free

Zero-cost providers — free tiers, credit programs, OAuth daily quotas.

Strategy: combo auto with budget cap routes here when Tier 1+2 fail or when useFreeOnly=true is set. Free providers often have weaker rate limits — circuit breaker recovers them on backoff.

Configuring tiers

Dashboard → Tiers → assign your providers. Defaults (from tierDefaults.json) are sensible; edit when you have specific subscriptions to prioritize or providers to exclude.

Auto-Combo's 13-factor scoring also considers tier. See docs/routing/AUTO-COMBO.md.

Telemetry

Dashboard → Usage shows tokens spent per tier per day. Use this to:

• Confirm Tier 1 is utilized fully (otherwise you're wasting subscription value)
• Identify which Tier 2 models are picked most (consolidate to 1-2)
• Verify Tier 3 saves money on test/exploration workloads

Common patterns

Pure-free workload

{
  "strategy": "auto",
  "config": { "auto": { "weights": { "costInv": 0.5, "tierPriority": 0.3 } } }
}

Forces strongly towards Tier 3; only uses Tier 2 if Tier 3 is unavailable.

Subscription-first with cheap fallback

{
  "strategy": "priority",
  "targets": [
    { "provider": "claude-code-oauth", "weight": 1 },
    { "provider": "deepseek", "weight": 1 },
    { "provider": "kiro", "weight": 1 }
  ]
}

Explicit ordered list matching Tier 1 → Tier 2 → Tier 3.