# How to Configure Quota-Aware Scheduling in OmniRoute: A Complete Guide

> Configure quota-aware scheduling in OmniRoute with our complete guide. Enable it, register plans, and tune intervals for optimal traffic management. Read now for setup details.

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

---

**Enable quota-aware scheduling in OmniRoute by setting `QUOTA_AUTO_PING_ENABLED=true` in your environment, registering provider quota plans in [`planRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/planRegistry.ts), and optionally tuning the `QUOTA_AUTO_PING_INTERVAL` for your traffic volume.**

OmniRoute is an open-source LLM routing platform that ships with a built-in **quota-aware scheduler** to prevent provider quota exhaustion and enable graceful fallbacks. This guide walks you through the exact configuration steps, environment variables, and source file modifications needed to activate and tune quota-aware scheduling in your deployment.

## Understanding the Quota-Aware Architecture

OmniRoute's quota system consists of five coordinated components. Understanding their roles helps you configure scheduling effectively:

| Component | Role | Source Location |
|:---|:---|:---|
| **Quota Preflight** | Validates quota status before dispatching requests | [`src/lib/quota/quotaPreflight.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaPreflight.ts) |
| **Quota Monitor** | Background loop that fetches quota usage and updates cache | [`src/lib/quota/quotaMonitor.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaMonitor.ts) |
| **Plan Registry** | Defines per-provider quota plans (limits, windows, fallbacks) | [`src/lib/quota/planRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/planRegistry.ts) |
| **Quota Scheduler** | Starts/stops the monitor based on feature flags | [`src/lib/quota/quotaScheduler.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaScheduler.ts) |
| **Resilience Settings** | Default values for polling intervals and flag keys | [`src/lib/resilience/settings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/resilience/settings.ts) |

The scheduler activates at runtime when the **Quota Monitor** detects the feature flag is enabled, then periodically polls provider endpoints to keep routing decisions quota-aware.

## Step 1: Enable the Quota Monitor via Feature Flag

OmniRoute uses the `QUOTA_AUTO_PING_ENABLED` feature flag to guard the scheduler. Add this to your `.env` file or container environment:

```bash

# .env

QUOTA_AUTO_PING_ENABLED=true
QUOTA_AUTO_PING_INTERVAL=300000   # Optional: 5 minutes in milliseconds

```

The **Quota Scheduler** reads this flag at startup in [`src/lib/quota/quotaScheduler.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaScheduler.ts):

```typescript
// src/lib/quota/quotaScheduler.ts
import { getFeatureFlag } from '@/lib/featureFlags';
import { startQuotaAutoPing } from './quotaMonitor';

if (getFeatureFlag('QUOTA_AUTO_PING_ENABLED')) {
  startQuotaAutoPing();   // launches the periodic job
}

```

Without this flag set to `true`, the background polling loop never starts and quota-aware scheduling remains inactive.

## Step 2: Register Provider Quota Plans

Each provider needs a **plan entry** in [`src/lib/quota/planRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/planRegistry.ts) declaring its quota window structure and limits. The scheduler uses this metadata to determine polling frequency and back-off thresholds.

```typescript
// src/lib/quota/planRegistry.ts
export const PLAN_REGISTRY = {
  openai: {
    daily: { limit: 1_000_000, window: 'daily' },
    monthly: { limit: 30_000_000, window: 'monthly' },
  },
  anthropic: {
    weekly: { limit: 500_000, window: 'weekly' },
  },
  // Add custom providers here
};

```

Each plan specifies:

- **Quota window**: `daily`, `weekly`, or `monthly` measurement periods
- **Hard limit**: Maximum tokens or requests allowed per window
- **Implicit fallback behavior** when limits are approached

The registry is read-only at runtime. Changes require deployment restart.

## Step 3: Adjust the Polling Interval

The default 5-minute polling interval is defined in [`src/lib/resilience/settings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/resilience/settings.ts):

```typescript
// src/lib/resilience/settings.ts
export const QUOTA_AUTO_PING_DEFAULT_MS = 5 * 60_000; // 5 minutes

```

Override this via the environment variable `QUOTA_AUTO_PING_INTERVAL` for higher-frequency polling in high-traffic deployments. The scheduler prioritizes the environment variable over the code default.

**Recommended intervals by traffic volume:**

- **Low traffic** (< 1K requests/day): 10-15 minutes (600000-900000 ms)
- **Standard traffic** (1K-100K requests/day): 5 minutes (300000 ms) — default
- **High traffic** (> 100K requests/day): 1-2 minutes (60000-120000 ms)

## Step 4: Verify Scheduler Operation

When active, the **Quota Monitor** logs polling activity through [`src/shared/utils/logger.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/logger.ts):

```

[info] quota-monitor: fetched quota for connection "xai-01" – used=12% of monthly limit

```

Programmatically inspect cached quota data:

```typescript
import { getCachedQuota } from '@/lib/quota/quotaMonitor';

const quota = getCachedQuota('xai-01');
console.log(quota?.monthly?.percentUsed);  // Current utilization percentage

```

Missing log lines or `undefined` cache returns indicate the scheduler is not running—check your feature flag configuration.

## Step 5: Confirm Routing Integration

The **Combo Router** in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) consumes cached quota data to make routing decisions. It automatically deprioritizes providers approaching their limits:

```typescript
// open-sse/services/combo.ts (excerpt)
if (quota?.monthly?.percentUsed > 0.9) {
  // Provider >90% of monthly quota → skip to fallback
  continue;
}

```

This integration requires no additional configuration. Once the scheduler populates the cache, routing becomes quota-aware automatically.

## Complete Configuration Example

```bash

# .env — minimal working configuration

QUOTA_AUTO_PING_ENABLED=true
QUOTA_AUTO_PING_INTERVAL=120000   # 2 minutes for high-traffic deployment

```

```typescript
// src/lib/quota/planRegistry.ts — example custom provider
export const PLAN_REGISTRY = {
  openai: {
    daily: { limit: 2_000_000, window: 'daily' },
    monthly: { limit: 50_000_000, window: 'monthly' },
  },
  anthropic: {
    monthly: { limit: 10_000_000, window: 'monthly' },
  },
  custom_provider: {
    daily: { limit: 100_000, window: 'daily' },
    weekly: { limit: 500_000, window: 'weekly' },
  },
};

```

## Summary

- **Enable quota-aware scheduling** by setting `QUOTA_AUTO_PING_ENABLED=true` in your environment
- **Define provider limits** in [`src/lib/quota/planRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/planRegistry.ts) with appropriate windows and thresholds
- **Tune polling frequency** via `QUOTA_AUTO_PING_INTERVAL` based on traffic patterns
- **Verify operation** through monitor logs and cached quota inspection
- **Leverage automatic routing integration** in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) without additional code changes

## Frequently Asked Questions

### What happens if `QUOTA_AUTO_PING_ENABLED` is false or unset?

The **Quota Scheduler** skips initialization of the background monitor in [`src/lib/quota/quotaScheduler.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaScheduler.ts). Routing continues without quota awareness, risking provider quota exhaustion and request failures.

### How do I add a new provider with custom quota windows?

Add an entry to `PLAN_REGISTRY` in [`src/lib/quota/planRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/planRegistry.ts) with your desired window types (`daily`, `weekly`, `monthly`) and corresponding limits. The scheduler automatically picks up the new provider on next deployment.

### Can I disable quota-aware scheduling for specific providers only?

No—OmniRoute's quota scheduler is globally enabled or disabled via feature flag. However, you can omit providers from [`planRegistry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/planRegistry.ts) to exclude them from quota monitoring while keeping the scheduler active for others.

### What causes quota cache staleness and how is it prevented?

Cache staleness occurs when polling fails or the interval is too long for traffic spikes. Prevent this by setting aggressive `QUOTA_AUTO_PING_INTERVAL` values for high-traffic deployments and monitoring the scheduler logs in [`src/shared/utils/logger.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/utils/logger.ts) for fetch failures.