What Are the 17 Routing Strategies Supported by OmniRoute and How to Configure Them?

OmniRoute provides 17 public routing strategies—including priority, weighted, round-robin, cost-optimized, and fusion—that determine how requests are distributed across AI model providers, all configurable via REST API, JSON files, or MCP tools.

OmniRoute's I‑7 auto‑combo routing engine intelligently selects target providers using predefined routing strategies supported by OmniRoute. These strategies define traffic distribution logic, failover behavior, and cost optimization. This guide covers all 17 public strategies, their implementation in the source code, and configuration methods.

The 17 Routing Strategies Supported by OmniRoute

The canonical list of routing strategies supported by OmniRoute resides in src/shared/constants/routingStrategies.ts. This file exports ROUTING_STRATEGY_VALUES as a constant array containing exactly 17 user-configurable strategies:

• priority – Uses the first healthy target; falls back to next only on failure
• weighted – Selects targets proportionally based on assigned weights
• fill-first – Exhausts the first target's quota before moving to the next
• round-robin – Cycles through targets in order to spread load evenly
• p2c (Power-of-Two-Choices) – Randomly picks two targets, selects the one with lower load
• random – Pure random selection among healthy targets
• least-used – Picks the target with the smallest recent usage counter
• reset-aware – Avoids targets that have just been reset
• reset-window – Similar to reset-aware but respects a configurable time window
• cost-optimized – Chooses the cheapest target satisfying the token budget
• strict-random – Random selection that never falls back once chosen
• auto – Automatically selects the most appropriate strategy based on combo composition
• lkgp (Last-Known-Good-Provider) – Uses the most recent successful provider
• context-optimized – Prefers providers with the highest context windows
• context-relay – Routes to providers that can continue previous conversations
• headroom – Selects providers with sufficient remaining token headroom
• fusion – Combines multiple providers in parallel and merges responses (experimental)

The same file also exports INTERNAL_ROUTING_STRATEGY_VALUES containing quota-share, a strategy reserved for internal dispatcher logic and not exposed to end-users.

How to Configure Routing Strategies

Via the Settings REST API

Configure strategies programmatically by posting to the combo endpoint at src/app/api/settings/combo/route.ts. The request body must include a strategy field validated against ROUTING_STRATEGY_VALUES by the Zod schema in src/shared/validation/schemas/combo.ts.

POST /api/v1/settings/combo
{
  "name": "production-combo",
  "targets": [
    { "providerId": "openai", "modelId": "gpt-4o-mini" },
    { "providerId": "anthropic", "modelId": "claude-3-sonnet" }
  ],
  "strategy": "cost-optimized"
}

Via Combo JSON Files

For CLI-based workflows, define strategies in JSON files stored at ~/.omniroute/combo/:

{
  "name": "fast-fallback",
  "targets": [
    { "providerId": "anthropic", "modelId": "claude-3-sonnet-20240229" },
    { "providerId": "openai", "modelId": "gpt-4o-mini" }
  ],
  "strategy": "reset-aware"
}

Import these configurations using omniroute combo import to persist them to the database.

Via MCP Tools

The MCP server exposes routing strategy configuration through the set_routing_strategy tool implemented in open-sse/mcp-server/tools/advancedTools.ts:

omniroute mcp --tool set_routing_strategy --args '{
  "combo": "fast-fallback",
  "strategy": "headroom"
}'

Via the TypeScript SDK

Programmatically create combos using the OmniRouteClient class, which validates the strategy parameter at compile-time using the same constants:

import { OmniRouteClient } from '@omniroute/sdk'

const client = new OmniRouteClient({ apiKey: process.env.OMNIRoute_API_KEY })

await client.createCombo({
  name: 'latency-aware',
  targets: [
    { providerId: 'openai', modelId: 'gpt-4o-mini' },
    { providerId: 'anthropic', modelId: 'claude-3-opus-20240229' }
  ],
  strategy: 'least-used'
})

Implementation Details

The normalizeRoutingStrategy() function in src/shared/constants/routingStrategies.ts validates supplied strings against ROUTING_STRATEGY_VALUES and defaults to "priority" if the value is unrecognized.

At runtime, resolveComboTargets() in src/lib/db/combo.ts reads the combo's strategy field and delegates selection logic to the dispatcher in open-sse/services/combo/comboSetup.ts. This dispatcher coordinates with helper modules like rateLimitManager.ts and usage.ts to execute strategies such as least-used or cost-optimized based on real-time provider metrics.

When making requests, specify the combo via the x-omniroute-combo header:

await fetch('https://my-omniroute-instance.com/api/v1/chat/completions', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json', 
    'x-omniroute-combo': 'latency-aware' 
  },
  body: JSON.stringify({
    model: 'combo',
    messages: [{ role: 'user', content: 'Explain routing strategies' }]
  })
})

Summary

• 17 public strategies are defined in ROUTING_STRATEGY_VALUES at src/shared/constants/routingStrategies.ts, ranging from simple priority to advanced fusion modes.
• Configuration methods include the REST API (/api/settings/combo), JSON files in ~/.omniroute/combo/, MCP tools, and the TypeScript SDK.
• Validation occurs through Zod schemas in src/shared/validation/schemas/combo.ts and the normalizeRoutingStrategy() utility.
• Execution happens in open-sse/services/combo/comboSetup.ts, which interprets the strategy and selects the appropriate provider.
• Unknown strategies automatically fall back to priority mode to ensure system reliability.

Frequently Asked Questions

What is the difference between auto and priority routing strategies?

The auto strategy allows the combo dispatcher to dynamically select the most appropriate algorithm based on the combo's composition and current system load, while priority strictly uses targets in the order they are defined, only falling back to the next target when the current one fails.

How does OmniRoute validate routing strategy configurations?

All routing strategies supported by OmniRoute are validated against the ROUTING_STRATEGY_VALUES array using Zod schemas in src/shared/validation/schemas/combo.ts. The normalizeRoutingStrategy() function provides additional runtime validation, defaulting unknown values to "priority" to prevent configuration errors from crashing the system.

Can I use internal strategies like quota-share in my combos?

No, quota-share is restricted to INTERNAL_ROUTING_STRATEGY_VALUES and is used exclusively by the internal combo-dispatcher for worker coordination. End-users can only configure the 17 public strategies listed in ROUTING_STRATEGY_VALUES.

Which strategy is best for cost-sensitive applications?

The cost-optimized strategy is specifically designed for cost-sensitive workloads, as it selects the cheapest provider that satisfies the request's token budget. For additional savings, combine it with headroom to ensure providers have sufficient capacity before selection, preventing expensive fallback scenarios.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}