# How to Configure OmniRoute with 19 Different Routing Strategies

> Master OmniRoute configuration with 19 routing strategies including priority round-robin least-used and cost-optimized. Optimize your routes today.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-28

---

**OmniRoute supports 19+ distinct routing algorithms through its combo engine, with 9 core strategies—including priority, round-robin, least-used, cost-optimized, and intelligent auto-routing—configurable via the `/api/combos` endpoint or per-provider fallback settings.**

OmniRoute's routing layer, implemented in the `diegosouzapw/OmniRoute` repository, provides granular control over how LLM requests are dispatched across provider connections. While the platform supports extensive customization with over 19 different routing configurations, this guide focuses on the 9 primary strategies documented in the source code. These algorithms determine how the **combo engine** (located in `open-sse/services/combo/`) selects targets from eligible provider pools during the request pipeline: `src/app/api/v1/chat/completions` → [`open-sse/handlers/chatCore.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore.ts) → [`open-sse/services/combo/comboSetup.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/comboSetup.ts).

## The 9 Core Routing Strategies

Each strategy is implemented as a distinct algorithm within the combo engine. When you configure a combo or set a fallback strategy, you select one of these identifiers which the system resolves through [`open-sse/services/combo/strategyDispatch.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/strategyDispatch.ts).

### Priority (Sequential Failover)

The **priority** strategy sequentially tries targets in the order they appear and stops at the first successful response. This is the default behavior for named combos. The core logic resides in [`open-sse/services/combo/targetResolution.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/targetResolution.ts) at line 71, where the engine checks `strategy === "priority"` before executing sequential resolution.

### Fill-First (Guaranteed Primary)

The **fill-first** strategy behaves identically to priority but guarantees that the first target is always tried, even if later targets report healthier status. This serves as the default fallback strategy for certain provider configurations. The resolver logic appears in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) at line 1908, where it handles the `<fill-first>` default fallback directive.

### Round-Robin (Load Distribution)

The **round-robin** strategy cycles through eligible connections in a rotating fashion to distribute load evenly. The implementation in [`open-sse/services/combo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoStrategy.ts) (line 400) maintains rotation state and advances the pointer with each request.

### Random (Stochastic Selection)

The **random** strategy selects targets uniformly at random from the eligible pool on each request. The ordering logic lives in [`open-sse/services/combo/runtimeUnits.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/runtimeUnits.ts) between lines 166-168 within the `orderUnitsForStrategy` function.

### Least-Used (Quota Balancing)

The **least-used** strategy picks the connection with the fewest invocations in the recent time window, helping to balance provider quotas. The sorting algorithm is implemented in [`open-sse/services/combo/targetSorters.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/targetSorters.ts) at line 120.

### Cost-Optimized (Price-Based)

The **cost-optimized** strategy orders targets by effective price (cheapest first) before applying secondary filters. This sorter resides in [`open-sse/services/combo/targetSorters.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/targetSorters.ts) at line 62, calculating per-token costs across candidate providers.

### Reset-Aware (Recovery Preference)

The **reset-aware** strategy prefers connections that have recently recovered from a circuit-breaker open state (reset events). The detection logic appears in [`open-sse/services/combo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoStrategy.ts) at line 318, monitoring circuit-breaker health transitions.

### LKGP (Least Known Good Provider)

The **lkgp** (Least Known Good Provider) strategy selects the provider with the highest historical health score, combining quota availability, latency percentiles, and error rates. The scoring implementation is found in [`open-sse/services/combo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoStrategy.ts) at line 280.

### Auto (Intelligent 15-Factor Routing)

The **auto** strategy implements the full intelligent router, building a candidate pool and applying quota cutoffs, context-window filters, mode-packs, and 15 distinct scoring factors before final selection. The complete pipeline is defined in [`open-sse/services/combo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoStrategy.ts) between lines 19-31, with per-request control parsing at line 240.

## Configuring Strategies Via REST API

To configure a combo with a specific strategy, POST to the combos endpoint:

```json
POST /api/combos
Content-Type: application/json

{
  "name": "my-priority-combo",
  "strategy": "priority",
  "models": [
    "openai/gpt-4o",
    "anthropic/claude-3.5-sonnet"
  ],
  "description": "Sequential fallback for high-reliability workloads"
}

```

The `strategy` field accepts any of the nine string identifiers listed above. This value is persisted in [`src/lib/db/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts) and subsequently read by [`comboSetup.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/comboSetup.ts) during request processing. The `ACCOUNT_FALLBACK_STRATEGY_VALUES` enum in [`src/shared/validation/settingsSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/settingsSchemas.ts) defines the allowed values for validation.

## Overriding Per-Provider Fallback Strategies

When no combo matches a request, OmniRoute uses per-provider fallback strategies configured via the settings endpoint:

```json
PATCH /api/v1/settings
Content-Type: application/json

{
  "providerStrategies": {
    "codex": { "fallbackStrategy": "least-used" },
    "openai": { "fallbackStrategy": "round-robin" }
  }
}

```

The resolver in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) (line 1908) selects the strategy using the logic: `providerOverride.fallbackStrategy || settings.fallbackStrategy`. This allows fine-grained control over individual provider behavior without modifying combo definitions.

## Per-Request Steering for Auto Strategies

Even when a combo uses the **auto** strategy, you can steer individual requests using HTTP headers parsed by [`open-sse/services/autoCombo/requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/requestControls.ts):

- **`X-OmniRoute-Mode`**: Accepts values like `fast`, `balanced`, `quality`, `cheap`, `reliable`, `offline`, or a custom mode-pack name. This selects preset weight configurations for the 15-factor scoring engine.
- **`X-OmniRoute-Budget`**: Specifies a numeric USD cost ceiling. The engine prunes candidates with estimated costs exceeding this value.

These headers are processed in [`open-sse/services/combo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoStrategy.ts) at line 240 and affect only the current request without mutating the stored combo configuration.

## Summary

- **OmniRoute provides 9 core routing strategies**—priority, fill-first, round-robin, random, least-used, cost-optimized, reset-aware, lkgp, and auto—implemented across `open-sse/services/combo/` source files.
- **Configuration persistence** occurs via `/api/combos` (stored in [`src/lib/db/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts)) and per-provider overrides via `/api/v1/settings` (resolved in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts)).
- **Default behaviors** can be overridden at the provider level using the `providerStrategies` configuration object.
- **Runtime control** of auto-strategy execution is available through `X-OmniRoute-Mode` and `X-OmniRoute-Budget` headers without API configuration changes.

## Frequently Asked Questions

### What is the difference between priority and fill-first strategies?

Both strategies attempt targets sequentially, but **fill-first** guarantees the primary target receives traffic even when secondary targets demonstrate superior health metrics. The **priority** strategy (default for named combos) will skip an unhealthy first target, while fill-first persists with the initial selection as defined in [`src/sse/services/auth.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/sse/services/auth.ts) line 1908.

### How do I change routing strategies for a single request without modifying the combo?

Send `X-OmniRoute-Mode` or `X-OmniRoute-Budget` headers with your request. These are parsed in [`open-sse/services/combo/autoStrategy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/autoStrategy.ts) (line 240) and [`open-sse/services/autoCombo/requestControls.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/autoCombo/requestControls.ts), allowing temporary overrides of the auto-strategy scoring weights without altering the persisted combo configuration in [`src/lib/db/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/combo.ts).

### Where does OmniRoute validate allowed strategy names?

The allowed strategy strings are enumerated in [`src/shared/validation/settingsSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/settingsSchemas.ts) within the `ACCOUNT_FALLBACK_STRATEGY_VALUES` constant. This schema validates inputs for both the `/api/combos` endpoint and the `/api/v1/settings` provider override configuration.

### Which file contains the logic for cost-based routing selection?

The **cost-optimized** strategy implementation resides in [`open-sse/services/combo/targetSorters.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo/targetSorters.ts) at line 62. This sorter calculates effective pricing across candidate connections and orders them from cheapest to most expensive before the combo engine applies additional filters like context-window limits or quota checks.