# How the Quota-Share Routing Strategy in OmniRoute Manages Shared Account Quota for Pooled Keys

> Learn how OmniRoute's quota-share routing strategy manages shared account quota for pooled keys. Discover how virtual combos and group-scoped naming enforce collective limits, ensuring efficient resource utilization.

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

---

**OmniRoute's quota-share routing strategy enables multiple API keys to draw from a single quota pool, enforcing shared account limits collectively rather than per-key through virtual combos, group-scoped naming, and pool-wide concurrency controls.**

The **quota-share routing strategy** in OmniRoute solves a critical problem for organizations managing multiple API connections: how to enforce a single usage limit across many pooled keys while maintaining provider isolation and concurrency safety. This article examines the implementation details based on the OmniRoute source code.

## Core Architecture of Quota-Share Routing

The quota-share strategy operates through a **virtual combo system** that automatically generates routing configurations for each model in a provider's catalog. Unlike standard routing strategies that target individual connections, quota-share combos distribute requests across a pool of connections while tracking aggregate usage against a shared quota.

### The Routing Strategy Constant

Every quota-share combo is tagged with a specific strategy identifier defined in [`src/lib/quota/quotaCombos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaCombos.ts):

```ts
export const QUOTA_SHARE_STRATEGY: AnyRoutingStrategyValue = "quota-share";

```

This constant forces the combo executor to process requests through the dedicated quota-share pathway in [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) (Phase 3, step 9). The strategy value acts as a discriminator that triggers pool-aware quota checking before any request reaches the underlying provider connections.

## Virtual Combo Generation and Naming

When a quota pool is created or modified, `syncQuotaCombos(poolId)` generates virtual combos for every model offered by the pool's provider. This function lives in [`src/lib/quota/quotaCombos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaCombos.ts) and performs several critical tasks:

- **Combo naming pattern**: Each combo follows the structure `qtSd/<groupSlug>/<provider>/<model>` via the `quotaModelName` helper
- **Connection pinning**: All steps in the combo reference specific connection IDs from the pool
- **Strategy enforcement**: The routing strategy is hardcoded to `"quota-share"` regardless of any template configuration

The naming convention serves a dual purpose. It organizes models by **quota group** (the `groupSlug` segment) while keeping providers isolated within that namespace. This design allows multiple pools in the same group to share the same virtual model identifiers.

### Group-Scoped Pool Resolution

Pools belong to quota groups, and this relationship drives combo scoping. The `resolvePoolForSync` function (lines 56-64) retrieves the group's slug, which `syncQuotaCombos` then incorporates into every generated combo name (lines 139-143). This ensures that when multiple pools exist within the same group, their virtual combos occupy the same namespace and can be treated as interchangeable routing targets.

## Enforcing Pool-Wide Concurrency Limits

Quota-share pools support **per-connection Max Concurrent limits** that the executor enforces collectively across the entire pool. This prevents the combined request volume of all pooled keys from overwhelming the underlying connections.

The concurrency controls are documented in the internationalization strings ([`settings-i18n-keys.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/settings-i18n-keys.test.ts)) and implemented in the resilience layer ([`resilience-settings-quota-share-concurrency.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/resilience-settings-quota-share-concurrency.test.ts)). When a connection declares a maximum concurrent request limit, the quota-share executor tracks in-flight requests across all keys using that pool and rejects or queues additional requests that would exceed the threshold.

## Lifecycle Management: Pruning and Cleanup

### Pruning Stale Combos

When connections are removed or a provider drops a model, `syncQuotaCombos` prunes obsolete virtual combos. The pruning logic (lines 22-48 of the prune loop) scopes deletions to **group + provider** pairs. This precision prevents collateral damage—removing an OpenAI connection from one pool won't delete combos for Anthropic connections in the same quota group.

```ts
// Prune loop structure from quotaCombos.ts
for (const [groupSlug, providers] of Object.entries(groupedProviders)) {
  for (const provider of providers) {
    // Delete only combos matching this specific group/provider combination
    await deleteCombosWhere({ groupSlug, provider, model: { notIn: activeModels } });
  }
}

```

### Pool Deletion Handling

The `removeQuotaCombosForPool` function (lines 45-81) performs complete cleanup when a pool is deleted. Like the pruning logic, it respects group-and-provider scoping to avoid affecting unrelated providers in shared groups.

## Access Control for Quota-Exclusive Keys

Quota-share models are **hidden by default** (`isHidden: true`) in the standard model catalog. For keys restricted to quota pools only, OmniRoute provides specialized filtering functions in [`src/lib/quota/quotaCombos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaCombos.ts):

- **`filterModelsToQuotaPools`** (lines 77-88): Removes non-quota models from the catalog response
- **`buildQuotaExclusiveModels`** (lines 105-125): Constructs a complete model listing containing only the combo models the key's pools provide

This ensures that quota-exclusive API keys see a curated interface where every available model routes through appropriate pooled quota.

## Practical Implementation Example

```ts
// Create a quota pool with multiple connections
const pool = await createQuotaPool({
  name: "production-openai-pool",
  groupId: "team-engineering",
  connectionIds: ["conn-prod-1", "conn-prod-2", "conn-prod-3"],
});

// Background synchronization generates combos automatically
await syncQuotaCombos(pool.id);
// Creates: qtSd/team-engineering/openai/gpt-4o-mini
//          qtSd/team-engineering/openai/gpt-4o
//          qtSd/team-engineering/openai/text-embedding-3-small
//          ... etc

// Client request using a pooled key
const response = await fetch("/v1/chat/completions", {
  method: "POST",
  headers: { 
    "Authorization": "Bearer sk-pooled-key-abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ 
    model: "qtSd/team-engineering/openai/gpt-4o-mini",
    messages: [{ role: "user", content: "Hello, quota pool!" }]
  })
});
// The combo executor checks pool quota and per-connection concurrency
// before routing to the optimal connection

```

## Key Source Files and Components

| Component | Path | Purpose |
|-----------|------|---------|
| Strategy constant & sync logic | [`src/lib/quota/quotaCombos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaCombos.ts) | Defines `QUOTA_SHARE_STRATEGY`, implements `syncQuotaCombos` and cleanup functions |
| Model naming utilities | [`src/lib/quota/quotaModelNaming.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaModelNaming.ts) | Generates `qtSd/<group>/<provider>/<model>` identifiers |
| Combo executor | [`open-sse/services/combo.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/services/combo.ts) | Routes quota-share requests through pool-aware execution path |
| Pool management UI | `src/app/(dashboard)/dashboard/costs/quota-share/QuotaSharePageClient.tsx` | Administrative interface for quota pool configuration |
| Test specifications | [`tests/unit/quota-share-strategy.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/tests/unit/quota-share-strategy.test.ts) | Documents expected quota-share behavior |

## Summary

- **Quota-share strategy** is declared as the constant `"quota-share"` in [`src/lib/quota/quotaCombos.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/quota/quotaCombos.ts) and forces dedicated execution handling
- **Virtual combos** are auto-generated for every provider model, named with the pattern `qtSd/<groupSlug>/<provider>/<model>`
- **Group-scoped naming** ensures pools within the same quota group share interchangeable virtual model identifiers
- **Pool-wide concurrency limits** combine per-connection Max Concurrent settings and enforce them across all pooled keys
- **Lifecycle management** prunes stale combos safely using group+provider scoping, preventing collateral deletion
- **Access control** hides quota-share models by default and exposes them selectively to quota-exclusive keys via filtering functions

## Frequently Asked Questions

### How does OmniRoute prevent one pool from consuming another pool's quota?

OmniRoute isolates quota pools through **group-scoped combo naming**. Each virtual combo includes the quota group's slug in its identifier, and the quota-share executor validates that a request's API key has access to the specified pool before counting usage. Pools in different groups generate combos with different namespaces, making cross-pool quota consumption impossible even with model name collisions.

### What happens when a pool's connections have different Max Concurrent settings?

The quota-share executor respects each connection's individual limit while tracking concurrency **pool-wide**. If connection A allows 10 concurrent requests and connection B allows 5, the system won't route more than 15 concurrent requests through the pool total, and no more than 5 through connection B specifically. Excess requests are queued with configurable timeout behavior.

### Can quota-share pools span multiple providers?

No. Quota-share pools are **provider-specific by design**. The `syncQuotaCombos` function validates that all connections in a pool belong to the same provider, and the naming convention embeds the provider identifier. This ensures that quota limits, pricing tiers, and model availability remain consistent across all connections in a pool. Cross-provider routing requires separate pools within the same quota group.

### How do I migrate an existing API key to use quota-share routing?

Migrate keys by assigning them to a **quota group** and configuring the group's pools in [`QuotaSharePageClient.tsx`](https://github.com/diegosouzapw/OmniRoute/blob/main/QuotaSharePageClient.tsx). Once a key is quota-exclusive, `buildQuotaExclusiveModels` automatically replaces its standard model catalog with the appropriate `qtSd/` prefixed combos. No client-side code changes are required—the virtual model names are drop-in replacements for standard provider model identifiers.