How OmniRoute Calculates Free Tier Budget Across 43 Provider Pools

OmniRoute aggregates the free-tier token quotas of every LLM provider by deduplicating shared provider pools and exposing totals through /api/free-tier/summary, yielding approximately 1.51 billion recurring tokens per month.

The free tier budget calculation in OmniRoute is a core feature that lets users understand exactly how many LLM tokens they can access without spending money. According to the diegosouzapw/OmniRoute source code, this system tracks 226 free models across 42–43 distinct provider pools, applying intelligent deduplication to avoid inflating totals when multiple models share the same underlying quota.

This article explains the three-step aggregation process, the key data structures, and how to access these calculations programmatically.

The Free Tier Catalog Architecture

OmniRoute maintains its free tier data in two coordinated files within the open-sse/config/ directory.

Per-Model Definitions in freeModelCatalog.data.ts

Each free model is defined with specific quota metadata:

// Typical entry in open-sse/config/freeModelCatalog.data.ts
{
  modelId: "gemini-1.5-flash-001",
  provider: "google-ai-studio",
  monthlyTokens: 1_000_000_000,     // 1 billion tokens recurring
  creditTokens: 0,                   // no signup bonus
  freeType: "recurring-daily",       // quota resets daily within the month
  poolKey: "google-ai-studio",       // shared pool key for deduplication
  // ... other fields
}

The critical fields are:

• monthlyTokens – the steady recurring grant available each month
• creditTokens – one-time signup credits (first-month boost only)
• freeType – classification as recurring-daily, recurring-uncapped, one-time-initial, or deposit-unlock
• poolKey – optional identifier grouping models that share the same free quota

The Catalog Entry Point

The open-sse/config/freeTierCatalog.ts file serves as the public interface, re-exporting the aggregation logic for both internal use and external consumption.

Three-Step Pool Deduplication Logic

The deduplication algorithm in computeFreeModelTotals() ensures accurate counting across shared provider pools.

Step 1: Pool Grouping

Models with the same poolKey are grouped together. For example, Google AI Studio offers multiple Flash and Pro models, but they all draw from the same 1 billion token/month pool. Without deduplication, summing each model individually would falsely suggest 3–4 billion tokens available.

Independent models without a poolKey are treated as their own pool of one.

Step 2: Per-Pool Maximum Selection

The helper function dedupedSum() selects the highest token grant within each pool, discarding lower values. This represents the realistic maximum a user can extract from that provider relationship.

Step 3: Aggregate Totals Computation

The computeFreeModelTotals() function in open-sse/config/freeModelCatalog.ts produces five distinct figures:

Metric	Description	Included in Headline?
steadyRecurringTokens	Pool-deduped recurring tokens per month	Yes – the "~1.51B" figure
steadyWithRecurringCreditsTokens	Adds recurring credit-based grants	No
firstMonthRealisticTokens	Includes one-time signup credits	No (shown as "up to ~2.13B")
boostMonthlyTokens	Deposit-unlock boosts (e.g., OpenRouter $10 top-up)	No (kept strictly separate)
uncappedProviders	Rate-limited providers with no published token cap	Excluded entirely from sums

Providers like Baidu, GLM-CN, Kilo-Gateway, OpenCode-Zen, SiliconFlow, Tencent, and Vertex are permanently free but publish no token limits. These are listed in uncappedProviders for completeness but deliberately omitted from numeric totals to maintain conservative, defensible figures.

Accessing Free Tier Calculations

Direct Library Usage

Import and call the core function in Node.js or TypeScript:

import { computeFreeModelTotals } from '@omniroute/open-sse/config/freeModelCatalog.ts';

const totals = computeFreeModelTotals({ excludeTosAvoid: true });

console.log('Steady recurring tokens/month:', totals.steadyRecurringTokens);
// Output: 1510000000

console.log('First-month realistic tokens:', totals.firstMonthRealisticTokens);
// Output: 2130000000

console.log('Boost from deposit-unlock:', totals.boostMonthlyTokens);
// Output: 24000000

console.log('Uncapped providers (rate-limited):', totals.uncappedProviders);
// Output: ['baidu', 'glm-cn', 'kilo-gateway', 'opencode-zen', ...]

console.log('Display headline:', totals.headline);
// Output: "~1.51B documented free tokens/month (steady), up to ~2.13B in your first month with signup credits"

The excludeTosAvoid option filters providers whose terms of service discourage automated API access, keeping the budget conservative and legally prudent.

Public API Endpoint

OmniRoute exposes identical data through GET /api/free-tier/summary, implemented in src/app/api/free-tier/summary/route.ts:

curl https://your-omniroute-instance/api/free-tier/summary

Response structure:

{
  "steadyRecurringTokens": 1510000000,
  "steadyWithRecurringCreditsTokens": 1530000000,
  "firstMonthRealisticTokens": 2130000000,
  "boostMonthlyTokens": 24000000,
  "uncappedProviders": [
    "baidu",
    "glm-cn",
    "kilo-gateway",
    "opencode-zen",
    "siliconflow",
    "tencent",
    "vertex"
  ],
  "modelCount": 226,
  "poolCount": 42,
  "headline": "~1.51B documented free tokens/month (steady), up to ~2.13B in your first month with signup credits"
}

As implemented in diegosouzapw/OmniRoute, both the dashboard and API draw from the same computeFreeModelTotals() function, guaranteeing synchronization between user-facing displays and internal routing decisions.

Extending the Free Tier Catalog

To add a new provider pool, append to open-sse/config/freeModelCatalog.data.ts:

{
  modelId: "new-provider-model",
  provider: "new-provider",
  monthlyTokens: 500_000_000,
  creditTokens: 1_000_000_000,
  freeType: "recurring-daily",
  poolKey: "new-provider-pool-2024",  // unique pool key
  // ...
}

The next call to computeFreeModelTotals() automatically includes this pool in poolCount and applies the deduplication logic. No additional registration steps are required.

Understanding the "43 Provider Pools" Figure

The current release v3.8.50 resolves to 42 distinct pools in the canonical catalog. The documentation references "43 provider pools" when including the newly discovered kilo-gateway pool, which was identified after the initial v3.8.50 tag. This transparent versioning explains minor discrepancies between marketing materials and API responses.

Summary

• OmniRoute's free tier budget calculation lives in open-sse/config/freeModelCatalog.ts with data in open-sse/config/freeModelCatalog.data.ts
• The dedupedSum() helper prevents double-counting models that share provider pools
• computeFreeModelTotals() produces five metrics, with steadyRecurringTokens (~1.51B) as the conservative headline figure
• Uncapped providers are tracked but excluded from numeric totals to maintain accuracy
• The public /api/free-tier/summary endpoint returns identical data to the internal library function

Frequently Asked Questions

How does OmniRoute avoid counting the same free quota multiple times?

OmniRoute uses the poolKey field in open-sse/config/freeModelCatalog.data.ts to group models that share an underlying provider quota. The dedupedSum() helper then selects only the highest token grant per pool, ensuring the Gemini Flash family (for example) contributes once to the total rather than once per model variant.

What is the difference between steadyRecurringTokens and firstMonthRealisticTokens?

steadyRecurringTokens represents the sustainable monthly baseline (~1.51B in v3.8.50) that renews indefinitely. firstMonthRealisticTokens adds one-time signup credits (~2.13B total), capturing the "new user boost" that cannot be repeated in subsequent months. OmniRoute surfaces both figures so users understand the long-term sustainable rate versus initial promotional access.

Why are some free providers excluded from the headline total?

Providers listed in uncappedProviders—including Baidu, SiliconFlow, and Vertex—offer permanently free tiers with rate limits but no published token caps. OmniRoute deliberately excludes these from numeric totals to maintain conservative, defensible figures that resist overcommitment. They remain accessible for actual usage; the exclusion is purely for budgeting mathematics.

Can I customize which providers count toward my instance's free tier budget?

Yes. Pass { excludeTosAvoid: true } to computeFreeModelTotals() to filter providers with restrictive terms of service. For deeper customization, fork open-sse/config/freeModelCatalog.data.ts and modify the catalog entries directly—the aggregation logic will respect your changes automatically.

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