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

> Learn how to configure OmniRoute free tier budget tracking. This guide shows you how to monitor token usage per model, provider, and account to prevent exceeding limits.

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

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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

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

```

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

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

```

### Manually Increase Token Budgets

```bash
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```ts
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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/constants/mcpScopes.ts).

## Summary

- **Free tier limits** originate from [`open-sse/config/freeModelCatalog.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/freeModelCatalog.ts) and are enforced per-model, per-provider, per-account
- **Budget windows reset** automatically via [`src/lib/jobs/budgetResetJob.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/jobs/budgetResetJob.ts) (default: every 10 minutes)
- **Request blocking** happens in [`src/shared/utils/apiKeyPolicy.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/emergencyFallback.ts). Requests will hard-fail at budget limits instead of rerouting.