# How OmniRoute Calculates Free Tier Budget Across 43 Provider Pools

> Discover how OmniRoute calculates free tier budgets across 43 provider pools. Get approximately 1.51 billion recurring tokens monthly by deduplicating shared quotas. Learn more.

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

---

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

Each free model is defined with specific quota metadata:

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

```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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/free-tier/summary/route.ts):

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

```

Response structure:

```json
{
  "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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/freeModelCatalog.data.ts):

```typescript
{
  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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/freeModelCatalog.ts) with data in [`open-sse/config/freeModelCatalog.data.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/config/freeModelCatalog.data.ts) and modify the catalog entries directly—the aggregation logic will respect your changes automatically.