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

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:

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 (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 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) and implemented in the resilience layer (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.

// 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:

• 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

// 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	Defines QUOTA_SHARE_STRATEGY, implements syncQuotaCombos and cleanup functions
Model naming utilities	src/lib/quota/quotaModelNaming.ts	Generates qtSd/<group>/<provider>/<model> identifiers
Combo executor	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	Documents expected quota-share behavior

Summary

• Quota-share strategy is declared as the constant "quota-share" in 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. 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.

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