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

Enable quota-aware scheduling in OmniRoute by setting QUOTA_AUTO_PING_ENABLED=true in your environment, registering provider quota plans in 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
Quota Monitor	Background loop that fetches quota usage and updates cache	src/lib/quota/quotaMonitor.ts
Plan Registry	Defines per-provider quota plans (limits, windows, fallbacks)	src/lib/quota/planRegistry.ts
Quota Scheduler	Starts/stops the monitor based on feature flags	src/lib/quota/quotaScheduler.ts
Resilience Settings	Default values for polling intervals and flag keys	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:

# .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:

// 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 declaring its quota window structure and limits. The scheduler uses this metadata to determine polling frequency and back-off thresholds.

// 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:

// 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:

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

Programmatically inspect cached quota data:

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 consumes cached quota data to make routing decisions. It automatically deprioritizes providers approaching their limits:

// 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

# .env — minimal working configuration

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

// 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 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 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. 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 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 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 for fetch failures.

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