How to Configure OmniRoute Free Tier Budget Tracking: A Step-by-Step Guide

OmniRoute tracks free tier budgets per-model, per-provider, and per-account through a token-based system that rejects exceeded requests with 429 or 402 status codes and optionally routes them to an emergency fallback provider.

OmniRoute's free tier budget tracking prevents unexpected API costs by enforcing hard limits on provider usage. The system stores usage data in the domain_budgets table and provides REST endpoints for monitoring and manual adjustments. This guide explains how to configure and tune these controls using the actual source code implementation in the diegosouzapw/OmniRoute repository.

Understanding the Free Tier Budget Architecture

OmniRoute's budget system consists of six interconnected components that handle everything from catalog definitions to emergency routing.

The Free-Model Catalog

The open-sse/config/freeModelCatalog.ts file defines the per-model token caps that establish free tier limits. This catalog serves as the authoritative source for both budget reset jobs and request-time enforcement.

Budget Reset Job

The src/lib/jobs/budgetResetJob.ts component runs periodically to roll over time windows. By default, it executes every OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS (600,000 ms / 10 minutes) to clear spent tokens for each API key.

API-Key Policy Enforcement

Each incoming request passes through src/shared/utils/apiKeyPolicy.ts, which calls checkBudget() to validate current usage against free tier limits. Exceeded budgets trigger immediate rejection.

Enabling and Configuring Budget Tracking

Step 1: Verify the Free-Model Catalog

Ensure open-sse/config/freeModelCatalog.ts reflects current provider limits. Update this file when providers change their free tier offerings.

Step 2: Adjust the Reset Interval (Optional)

Modify OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS in your environment to change how frequently budget windows reset. The default 10-minute interval balances freshness with performance.

Step 3: Enable Emergency Fallback

Set OMNIROUTE_EMERGENCY_FALLBACK=true (default) to route blocked requests to alternative free providers. Disable this feature flag if you prefer hard stops at budget limits.

Monitoring and Adjusting Budgets via REST API

OmniRoute exposes two endpoints in src/app/api/usage/budget/ for operational control.

View Current Free Tier Usage

curl http://localhost:20128/api/usage/budget

This returns JSON with per-key, per-model consumption:

[
  {
    "apiKeyId": "123",
    "provider": "gemini",
    "model": "gemini-1.5-flash",
    "usedTokens": 4200,
    "budgetTokens": 5000
  }
]

Manually Increase Token Budgets

curl -X POST http://localhost:20128/api/usage/budget \
     -H "Content-Type: application/json" \
     -d '{
           "apiKeyId": "42",
           "provider": "gemini",
           "model": "gemini-2.5-flash",
           "budgetTokens": 12000
         }'

The endpoint validates against src/shared/validation/schemas/settings.ts before updating the domain_budgets table.

Handling Budget Exhaustion

When free tier limits are exceeded, OmniRoute responds with:

• 429 Too Many Requests — standard free tier quota exhaustion
• 402 Payment Required — monetary budget limit reached

If OMNIROUTE_EMERGENCY_FALLBACK is enabled, the open-sse/services/emergencyFallback.ts service automatically selects an alternative provider with remaining free quota (such as nvidia or openai/gpt-oss-120b).

Programmatic Budget Checks

Use the internal API for custom budget validation:

import { checkBudget } from "@/shared/utils/apiKeyPolicy";

async function canProceed(apiKeyId: string) {
  const result = await checkBudget(apiKeyId);
  if (!result.allowed) {
    throw new Error(`Budget exceeded: ${result.reason}`);
  }
}

Visualizing Budgets in the Dashboard

The dashboard component at src/app/(dashboard)/dashboard/providers/page.tsx renders aggregated free tier budgets, displaying per-model usage bars and remaining quota indicators. This UI consumes the same REST endpoints documented above.

Subscribing to Budget Events

Monitor budget exhaustion programmatically by subscribing to the budget.exceeded MCP event. This requires the write:budget scope defined in src/shared/constants/mcpScopes.ts.

Summary

• Free tier limits originate from open-sse/config/freeModelCatalog.ts and are enforced per-model, per-provider, per-account
• Budget windows reset automatically via src/lib/jobs/budgetResetJob.ts (default: every 10 minutes)
• Request blocking happens in src/shared/utils/apiKeyPolicy.ts with 429/402 responses
• Manual adjustments are available through POST /api/usage/budget with validation in src/shared/validation/schemas/settings.ts
• Emergency fallback to alternative free providers is controlled by OMNIROUTE_EMERGENCY_FALLBACK

Frequently Asked Questions

How do I add temporary free tokens to a specific API key?

Use the POST /api/usage/budget endpoint with the apiKeyId, provider, model, and target budgetTokens. The payload validates against the schema in src/shared/validation/schemas/settings.ts before updating the domain_budgets table.

What happens when a free tier budget is exceeded?

Requests receive 429 Too Many Requests (free token limits) or 402 Payment Required (monetary limits). If OMNIROUTE_EMERGENCY_FALLBACK is enabled, the open-sse/services/emergencyFallback.ts service reroutes to an alternative provider with available free quota.

How often do free tier budgets reset?

The src/lib/jobs/budgetResetJob.ts runs every OMNIROUTE_BUDGET_RESET_JOB_INTERVAL_MS milliseconds—defaulting to 600,000 ms (10 minutes). Adjust this environment variable to change rollover frequency for daily or hourly windows.

Can I disable automatic fallback when budgets exhaust?

Yes. Set OMNIROUTE_EMERGENCY_FALLBACK=false or toggle the budget feature flag in the database to disable open-sse/services/emergencyFallback.ts. Requests will hard-fail at budget limits instead of rerouting.

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