Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

quota observability (#344)

Ashutosh Sahoo4ab13001e88b
diff --git a/client/src/pages/KeysPage.tsx b/client/src/pages/KeysPage.tsx
index 96282f9f..d29e9b1f 100644
--- a/client/src/pages/KeysPage.tsx
+++ b/client/src/pages/KeysPage.tsx
@@ -8,7 +8,7 @@ import { Label } from '@/components/ui/label'
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
import { Switch } from '@/components/ui/switch'
import { PageHeader } from '@/components/page-header'
-import type { ApiKey, Platform } from '../../../shared/types'
+import type { ApiKey, Platform, ProviderQuotaState } from '../../../shared/types'
import { Pencil, ExternalLink, Globe } from 'lucide-react'
import { formatSqliteUtcToLocalTime } from '@/lib/utils'
import { useI18n } from '@/i18n'
@@ -109,6 +109,55 @@ interface HealthPlatform {
interface HealthData {
platforms: HealthPlatform[]
keys: { id: number; platform: string; status: string; lastCheckedAt: string | null }[]
+ quotaStates: ProviderQuotaState[]
+}
+
+function formatQuotaNumber(value: number | null): string {
+ return value == null ? '—' : new Intl.NumberFormat().format(value)
+}
+
+function formatResetAt(value: string | null): string {
+ if (!value) return '—'
+ const date = new Date(value)
+ return Number.isNaN(date.getTime()) ? '—' : date.toLocaleString()
+}
+
+function QuotaSignalsSection({ states }: { states: ProviderQuotaState[] }) {
+ return (
+ <section>
+ <h2 className="text-sm font-medium mb-3">Quota signals</h2>
+ {states.length === 0 ? (
+ <div className="rounded-3xl border border-dashed p-6 text-sm text-muted-foreground bg-card">
+ No quota observations yet. The dashboard will fill in after providers return headers, quota errors, or validation signals.
+ </div>
+ ) : (
+ <div className="rounded-3xl border divide-y bg-card overflow-hidden">
+ {states.map((state) => (
+ <div key={`${state.platform}:${state.keyId}:${state.quotaPoolKey}:${state.metric}`} className="px-4 py-3.5 text-sm">
+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+ <span className="font-medium">{state.platform}</span>
+ <span className="text-muted-foreground">key #{state.keyId}</span>
+ <span className="text-muted-foreground">pool {state.quotaPoolKey}</span>
+ <span className="text-xs px-2 py-0.5 rounded-full bg-muted text-muted-foreground">{state.metric}</span>
+ <span className="ml-auto text-xs text-muted-foreground">
+ {state.source} · {Math.round(state.confidence * 100)}%
+ </span>
+ </div>
+ <div className="mt-2 grid gap-2 text-xs text-muted-foreground sm:grid-cols-2 lg:grid-cols-4">
+ <div><span className="text-foreground">Limit</span> {formatQuotaNumber(state.limit)}</div>
+ <div><span className="text-foreground">Remaining</span> {formatQuotaNumber(state.remaining)}</div>
+ <div><span className="text-foreground">Reset</span> {formatResetAt(state.resetAt)}</div>
+ <div><span className="text-foreground">Observed</span> {formatSqliteUtcToLocalTime(state.observedAt, { hour: '2-digit', minute: '2-digit' })}</div>
+ </div>
+ {state.notes && (
+ <p className="mt-2 text-xs text-muted-foreground">{state.notes}</p>
+ )}
+ </div>
+ ))}
+ </div>
+ )}
+ </section>
+ )
}
function UnifiedKeySection() {
@@ -672,6 +721,8 @@ export default function KeysPage() {
{tab === 'providers' && (
<>
+ <QuotaSignalsSection states={(healthData?.quotaStates ?? []).slice(0, 24)} />
+
<section>
<h2 className="text-sm font-medium mb-3">{t('keys.addProvider')}</h2>
<form onSubmit={handleSubmit} className="flex flex-wrap gap-3 rounded-3xl border p-4 bg-card">
diff --git a/package-lock.json b/package-lock.json
index 06a1c725..665ef193 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1238,7 +1238,6 @@
"os": [
"aix"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1255,7 +1254,6 @@
"os": [
"android"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1272,7 +1270,6 @@
"os": [
"android"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1289,7 +1286,6 @@
"os": [
"android"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1306,7 +1302,6 @@
"os": [
"darwin"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1323,7 +1318,6 @@
"os": [
"darwin"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1340,7 +1334,6 @@
"os": [
"freebsd"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1357,7 +1350,6 @@
"os": [
"freebsd"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1374,7 +1366,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1391,7 +1382,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1408,7 +1398,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1425,7 +1414,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1442,7 +1430,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1459,7 +1446,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1476,7 +1462,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1493,7 +1478,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1510,7 +1494,6 @@
"os": [
"linux"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1527,7 +1510,6 @@
"os": [
"netbsd"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1544,7 +1526,6 @@
"os": [
"netbsd"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1561,7 +1542,6 @@
"os": [
"openbsd"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1578,7 +1558,6 @@
"os": [
"openbsd"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1595,7 +1574,6 @@
"os": [
"openharmony"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1612,7 +1590,6 @@
"os": [
"sunos"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1629,7 +1606,6 @@
"os": [
"win32"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1646,7 +1622,6 @@
"os": [
"win32"
],
- "peer": true,
"engines": {
"node": ">=18"
}
@@ -1663,7 +1638,6 @@
"os": [
"win32"
],
- "peer": true,
"engines": {
"node": ">=18"
}
diff --git a/server/src/db/migrations.ts b/server/src/db/migrations.ts
index 0f659aba..abee479f 100644
--- a/server/src/db/migrations.ts
+++ b/server/src/db/migrations.ts
@@ -173,6 +173,50 @@ function createTables(db: Database.Database) {
CREATE INDEX IF NOT EXISTS idx_rate_limit_usage_lookup ON rate_limit_usage(platform, model_id, key_id, kind, created_at_ms);
CREATE INDEX IF NOT EXISTS idx_rate_limit_cooldowns_expires ON rate_limit_cooldowns(expires_at_ms);
CREATE INDEX IF NOT EXISTS idx_api_keys_platform ON api_keys(platform);
+
+ CREATE TABLE IF NOT EXISTS provider_quota_state (
+ platform TEXT NOT NULL,
+ key_id INTEGER NOT NULL,
+ quota_pool_key TEXT NOT NULL,
+ metric TEXT NOT NULL,
+ limit_value INTEGER,
+ remaining_value INTEGER,
+ reset_at TEXT,
+ reset_strategy TEXT NOT NULL DEFAULT 'unknown',
+ source TEXT NOT NULL DEFAULT 'probe',
+ confidence REAL NOT NULL DEFAULT 0,
+ notes TEXT,
+ observed_at TEXT NOT NULL DEFAULT (datetime('now')),
+ updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+ PRIMARY KEY (platform, key_id, quota_pool_key, metric)
+ );
+ CREATE INDEX IF NOT EXISTS idx_provider_quota_state_platform ON provider_quota_state(platform, key_id, updated_at);
+ CREATE INDEX IF NOT EXISTS idx_provider_quota_state_reset_at ON provider_quota_state(reset_at);
+
+ CREATE TABLE IF NOT EXISTS provider_quota_observations (
+ id TEXT PRIMARY KEY,
+ platform TEXT NOT NULL,
+ key_id INTEGER NOT NULL,
+ provider_account_id TEXT,
+ model_id TEXT,
+ quota_pool_key TEXT NOT NULL,
+ metric TEXT NOT NULL,
+ status_code INTEGER,
+ limit_value INTEGER,
+ remaining_value INTEGER,
+ reset_at TEXT,
+ retry_after_ms INTEGER,
+ reset_strategy TEXT NOT NULL DEFAULT 'unknown',
+ source TEXT NOT NULL DEFAULT 'probe',
+ confidence REAL NOT NULL DEFAULT 0,
+ notes TEXT,
+ raw_json TEXT,
+ endpoint TEXT,
+ observed_at TEXT NOT NULL DEFAULT (datetime('now')),
+ created_at TEXT NOT NULL DEFAULT (datetime('now'))
+ );
+ CREATE INDEX IF NOT EXISTS idx_provider_quota_observations_platform ON provider_quota_observations(platform, key_id, observed_at);
+ CREATE INDEX IF NOT EXISTS idx_provider_quota_observations_reset_at ON provider_quota_observations(reset_at);
`);
ensureRequestKeyIdColumn(db);
diff --git a/server/src/providers/base.ts b/server/src/providers/base.ts
index 85cc638c..104ac13c 100644
--- a/server/src/providers/base.ts
+++ b/server/src/providers/base.ts
@@ -6,6 +6,7 @@ import type {
ChatToolChoice,
Platform,
} from '@freellmapi/shared/types.js';
+import type { QuotaObservationContext } from '../services/provider-quota.js';
import { proxyFetch } from '../lib/proxy.js';
/** A provider HTTP error carrying the upstream status and, when the response
@@ -66,6 +67,7 @@ export abstract class BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): Promise<ChatCompletionResponse>;
abstract streamChatCompletion(
@@ -73,9 +75,10 @@ export abstract class BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): AsyncGenerator<ChatCompletionChunk>;
- abstract validateKey(apiKey: string): Promise<boolean>;
+ abstract validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean>;
protected async fetchWithTimeout(
url: string,
diff --git a/server/src/providers/cloudflare.ts b/server/src/providers/cloudflare.ts
index 94f0a0b0..cf1eabdc 100644
--- a/server/src/providers/cloudflare.ts
+++ b/server/src/providers/cloudflare.ts
@@ -5,6 +5,7 @@ import type {
} from '@freellmapi/shared/types.js';
import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';
import { contentToString } from '../lib/content.js';
+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';
/**
* Cloudflare Workers AI provider.
@@ -34,6 +35,7 @@ export class CloudflareProvider extends BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): Promise<ChatCompletionResponse> {
const { accountId, token } = this.parseKey(apiKey);
const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1/chat/completions`;
@@ -55,6 +57,14 @@ export class CloudflareProvider extends BaseProvider {
parallel_tool_calls: options?.parallel_tool_calls,
}),
});
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'chat/completions',
+ });
if (!res.ok) {
const err = await res.json().catch(() => ({}));
@@ -71,6 +81,7 @@ export class CloudflareProvider extends BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): AsyncGenerator<ChatCompletionChunk> {
const { accountId, token } = this.parseKey(apiKey);
const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1/chat/completions`;
@@ -93,6 +104,14 @@ export class CloudflareProvider extends BaseProvider {
stream: true,
}),
});
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'chat/completions',
+ });
if (!res.ok) {
const err = await res.json().catch(() => ({}));
@@ -102,7 +121,7 @@ export class CloudflareProvider extends BaseProvider {
yield* this.readSseStream(res);
}
- async validateKey(apiKey: string): Promise<boolean> {
+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {
// Transport errors propagate — health.ts marks status='error' without
// counting toward auto-disable. Only confirmed bad/inactive tokens disable.
const { accountId, token } = this.parseKey(apiKey);
@@ -114,12 +133,14 @@ export class CloudflareProvider extends BaseProvider {
const userResult = await this.verifyAt(
'https://api.cloudflare.com/client/v4/user/tokens/verify',
token,
+ quotaContext,
);
if (userResult !== 'auth-failed') return userResult;
const accountResult = await this.verifyAt(
`https://api.cloudflare.com/client/v4/accounts/${accountId}/tokens/verify`,
token,
+ quotaContext,
);
if (accountResult === 'auth-failed') return false;
return accountResult;
@@ -128,12 +149,20 @@ export class CloudflareProvider extends BaseProvider {
// Hits a Cloudflare token-verify endpoint. Returns true/false for a definitive
// active/inactive verdict, or 'auth-failed' when the token lacks access to
// THIS endpoint (401/403) so the caller can try the other scope.
- private async verifyAt(url: string, token: string): Promise<boolean | 'auth-failed'> {
+ private async verifyAt(url: string, token: string, quotaContext?: QuotaObservationContext): Promise<boolean | 'auth-failed'> {
const res = await this.fetchWithTimeout(
url,
{ method: 'GET', headers: { 'Authorization': `Bearer ${token}` } },
10000,
);
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId: quotaContext?.modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'tokens/verify',
+ });
if (res.status === 401 || res.status === 403) return 'auth-failed';
if (!res.ok) return true; // unexpected non-2xx that isn't auth — don't disable
const data = await res.json() as any;
diff --git a/server/src/providers/cohere.ts b/server/src/providers/cohere.ts
index b5903d06..ab1728e6 100644
--- a/server/src/providers/cohere.ts
+++ b/server/src/providers/cohere.ts
@@ -6,6 +6,7 @@ import type {
} from '@freellmapi/shared/types.js';
import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';
import { flattenMessageContent } from '../lib/content.js';
+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';
import { stripSchemaKeys } from '../lib/tool-args.js';
const API_BASE = 'https://api.cohere.ai/compatibility/v1';
@@ -36,6 +37,7 @@ export class CohereProvider extends BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): Promise<ChatCompletionResponse> {
const body: Record<string, unknown> = {
model: modelId,
@@ -55,6 +57,14 @@ export class CohereProvider extends BaseProvider {
},
body: JSON.stringify(body),
});
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'chat/completions',
+ });
if (!res.ok) {
const err = await res.json().catch(() => ({}));
@@ -71,6 +81,7 @@ export class CohereProvider extends BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): AsyncGenerator<ChatCompletionChunk> {
const body: Record<string, unknown> = {
model: modelId,
@@ -91,6 +102,14 @@ export class CohereProvider extends BaseProvider {
},
body: JSON.stringify(body),
});
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'chat/completions',
+ });
if (!res.ok) {
const err = await res.json().catch(() => ({}));
@@ -100,13 +119,21 @@ export class CohereProvider extends BaseProvider {
yield* this.readSseStream(res);
}
- async validateKey(apiKey: string): Promise<boolean> {
+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {
// Transport errors propagate — health.ts marks status='error' without
// counting toward auto-disable. Only confirmed 401/403 disables a key.
const res = await this.fetchWithTimeout(`${API_BASE}/models`, {
method: 'GET',
headers: { 'Authorization': `Bearer ${apiKey}` },
}, 10000);
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId: quotaContext?.modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'models',
+ });
return res.status !== 401 && res.status !== 403;
}
}
diff --git a/server/src/providers/google.ts b/server/src/providers/google.ts
index e0f8882c..ec3004fd 100644
--- a/server/src/providers/google.ts
+++ b/server/src/providers/google.ts
@@ -10,6 +10,7 @@ import type {
import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';
import { contentToString } from '../lib/content.js';
import { proxyFetch } from '../lib/proxy.js';
+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';
const API_BASE = 'https://generativelanguage.googleapis.com/v1beta';
@@ -391,6 +392,7 @@ export class GoogleProvider extends BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): Promise<ChatCompletionResponse> {
const { contents, systemInstruction } = await toGeminiContents(messages);
@@ -416,6 +418,15 @@ export class GoogleProvider extends BaseProvider {
body: JSON.stringify(body),
});
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'chat/completions',
+ });
+
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw providerHttpError(res, `Google API error ${res.status}: ${(err as any).error?.message ?? res.statusText}`);
@@ -457,6 +468,7 @@ export class GoogleProvider extends BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): AsyncGenerator<ChatCompletionChunk> {
const { contents, systemInstruction } = await toGeminiContents(messages);
@@ -480,6 +492,15 @@ export class GoogleProvider extends BaseProvider {
body: JSON.stringify(body),
});
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'chat/completions',
+ });
+
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw providerHttpError(res, `Google API error ${res.status}: ${(err as any).error?.message ?? res.statusText}`);
@@ -597,7 +618,7 @@ export class GoogleProvider extends BaseProvider {
}
}
- async validateKey(apiKey: string): Promise<boolean> {
+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {
// Transport errors propagate — health.ts marks status='error' without
// counting toward auto-disable.
const res = await this.fetchWithTimeout(
@@ -605,6 +626,14 @@ export class GoogleProvider extends BaseProvider {
{ method: 'GET' },
10000,
);
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId: quotaContext?.modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'models',
+ });
if (res.ok) return true;
// Google's error taxonomy is NOT the usual 401/403-means-bad-key (#268):
diff --git a/server/src/providers/openai-compat.ts b/server/src/providers/openai-compat.ts
index f430fd29..86caae9c 100644
--- a/server/src/providers/openai-compat.ts
+++ b/server/src/providers/openai-compat.ts
@@ -8,6 +8,7 @@ import type {
import { BaseProvider, providerHttpError, type CompletionOptions } from './base.js';
import { rescueInlineToolCalls } from '../lib/tool-call-rescue.js';
import { repairToolArguments, toolSchemaMap } from '../lib/tool-args.js';
+import { recordQuotaObservationsFromResponse, type QuotaObservationContext } from '../services/provider-quota.js';
/**
* Generic provider for platforms that use an OpenAI-compatible API.
@@ -95,6 +96,7 @@ export class OpenAICompatProvider extends BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): Promise<ChatCompletionResponse> {
const res = await this.fetchWithTimeout(`${this.baseUrl}/chat/completions`, {
method: 'POST',
@@ -115,6 +117,15 @@ export class OpenAICompatProvider extends BaseProvider {
}),
}, options?.timeoutMs ?? this.timeoutMs);
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'chat/completions',
+ });
+
if (!res.ok) {
const err = await res.json().catch(() => ({}));
const rescued = this.rescueFailedGeneration(err, options);
@@ -157,6 +168,7 @@ export class OpenAICompatProvider extends BaseProvider {
messages: ChatMessage[],
modelId: string,
options?: CompletionOptions,
+ quotaContext?: QuotaObservationContext,
): AsyncGenerator<ChatCompletionChunk> {
const res = await this.fetchWithTimeout(`${this.baseUrl}/chat/completions`, {
method: 'POST',
@@ -178,6 +190,15 @@ export class OpenAICompatProvider extends BaseProvider {
}),
}, this.timeoutMs);
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ modelId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'chat/completions',
+ });
+
if (!res.ok) {
const err = await res.json().catch(() => ({}));
const rescued = this.rescueFailedGeneration(err, options);
@@ -195,7 +216,7 @@ export class OpenAICompatProvider extends BaseProvider {
yield* this.readSseStream(res);
}
- async validateKey(apiKey: string): Promise<boolean> {
+ async validateKey(apiKey: string, quotaContext?: QuotaObservationContext): Promise<boolean> {
// Note: transport errors (DNS / timeout / TLS) propagate to the caller.
// health.ts catches them and marks status='error' WITHOUT incrementing
// the consecutive-failure counter — only confirmed 401/403 disables a key.
@@ -212,6 +233,13 @@ export class OpenAICompatProvider extends BaseProvider {
...this.extraHeaders,
},
}, 30000);
+ recordQuotaObservationsFromResponse(res, {
+ platform: this.platform,
+ keyId: quotaContext?.keyId,
+ providerAccountId: quotaContext?.providerAccountId,
+ quotaPoolKey: quotaContext?.quotaPoolKey,
+ endpoint: 'models',
+ });
return res.status !== 401 && res.status !== 403;
}
}
diff --git a/server/src/routes/health.ts b/server/src/routes/health.ts
index 171ad835..79aa9bdc 100644
--- a/server/src/routes/health.ts
+++ b/server/src/routes/health.ts
@@ -3,6 +3,7 @@ import type { Request, Response } from 'express';
import { getDb } from '../db/index.js';
import { checkKeyHealth, checkAllKeys } from '../services/health.js';
import { hasProvider } from '../providers/index.js';
+import { getQuotaStateForKeys } from '../services/provider-quota.js';
export const healthRouter = Router();
@@ -51,6 +52,7 @@ healthRouter.get('/', (_req: Request, res: Response) => {
createdAt: k.created_at,
lastCheckedAt: k.last_checked_at,
})),
+ quotaStates: getQuotaStateForKeys(),
});
});
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index 6e5a5173..6748c09b 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -16,6 +16,8 @@ import { getContextHandoffMode, recordIncomingMessages, maybeInjectContextHandof
import { isFusionModel, runFusion, fusionConfigSchema, FusionError, FUSION_MODEL_ID } from '../services/fusion.js';
import { isRetryableError, isPaymentRequiredError, isModelNotFoundError, isModelAccessForbiddenError } from '../lib/error-classify.js';
import { logRequest } from '../lib/request-log.js';
+import type { Platform } from '@freellmapi/shared/types.js';
+import { inferQuotaPoolKey, type QuotaObservationContext } from '../services/provider-quota.js';
import { isUnifyEnabled, getModelGroups, resolveRequestedIdToMembers } from '../services/model-groups.js';
import { buildModelListing } from '../services/model-listing.js';
@@ -63,6 +65,17 @@ export function extractApiToken(req: Request): string | undefined {
return trimmed || undefined;
}
+function quotaContextForRoute(route: RouteResult, endpoint: string): QuotaObservationContext {
+ return {
+ platform: route.platform as Platform,
+ keyId: route.keyId,
+ modelId: route.modelId,
+ quotaPoolKey: inferQuotaPoolKey(route.platform as Platform, route.modelId),
+ endpoint,
+ origin: 'proxy',
+ };
+}
+
export function getRequestGroupId(req: Request): string {
const raw = req.headers['x-request-id'];
const value = Array.isArray(raw) ? raw[0] : raw;
@@ -1003,6 +1016,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
const gen = route.provider.streamChatCompletion(
route.apiKey, outboundMessages, route.modelId,
{ temperature, max_tokens, top_p, tools, tool_choice, parallel_tool_calls },
+ quotaContextForRoute(route, 'chat/completions'),
);
for await (const chunk of gen) {
@@ -1200,6 +1214,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
const result = await route.provider.chatCompletion(
route.apiKey, outboundMessages, route.modelId,
{ temperature, max_tokens, top_p, tools, tool_choice, parallel_tool_calls },
+ quotaContextForRoute(route, 'chat/completions'),
);
// Empty completion (no text, no tool calls) → fail over rather than
diff --git a/server/src/routes/responses.ts b/server/src/routes/responses.ts
index c8936d74..14ff2b1a 100644
--- a/server/src/routes/responses.ts
+++ b/server/src/routes/responses.ts
@@ -7,6 +7,7 @@ import type {
ChatToolCall,
ChatToolDefinition,
ChatToolChoice,
+ Platform,
} from '@freellmapi/shared/types.js';
import { routeRequest, recordRateLimitHit, recordSuccess, hasEnabledToolsModel, type RouteResult } from '../services/router.js';
import { recordRequest, recordTokens, setCooldown, getCooldownDurationForLimit, PAYMENT_REQUIRED_COOLDOWN_MS, learnLimitFromError } from '../services/ratelimit.js';
@@ -28,6 +29,7 @@ import {
logRequest,
} from './proxy.js';
import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';
+import { inferQuotaPoolKey, type QuotaObservationContext } from '../services/provider-quota.js';
export const responsesRouter = Router();
@@ -264,6 +266,17 @@ export function buildResponseObject(opts: {
};
}
+function quotaContextForRoute(route: RouteResult, endpoint: string): QuotaObservationContext {
+ return {
+ platform: route.platform as Platform,
+ keyId: route.keyId,
+ modelId: route.modelId,
+ quotaPoolKey: inferQuotaPoolKey(route.platform as Platform, route.modelId),
+ endpoint,
+ origin: 'responses',
+ };
+}
+
responsesRouter.post('/responses', async (req: Request, res: Response) => {
const start = Date.now();
const requestGroupId = getRequestGroupId(req);
@@ -419,7 +432,13 @@ responsesRouter.post('/responses', async (req: Request, res: Response) => {
}
};
- const gen = route.provider.streamChatCompletion(route.apiKey, messages, route.modelId, completionOpts);
+ const gen = route.provider.streamChatCompletion(
+ route.apiKey,
+ messages,
+ route.modelId,
+ completionOpts,
+ quotaContextForRoute(route, 'responses'),
+ );
for await (const chunk of gen) {
// In-band upstream error frame ({"error":...} inside a 200 SSE
@@ -634,7 +653,13 @@ responsesRouter.post('/responses', async (req: Request, res: Response) => {
logRequest(route.platform, route.modelId, route.keyId, 'success', estimatedInputTokens, totalOutputTokens, Date.now() - start, null);
return;
} else {
- const result = await route.provider.chatCompletion(route.apiKey, messages, route.modelId, completionOpts);
+ const result = await route.provider.chatCompletion(
+ route.apiKey,
+ messages,
+ route.modelId,
+ completionOpts,
+ quotaContextForRoute(route, 'responses'),
+ );
const msg = result.choices[0]?.message;
let text = contentToString(msg?.content ?? '');
diff --git a/server/src/services/health.ts b/server/src/services/health.ts
index 00caecca..58cd0181 100644
--- a/server/src/services/health.ts
+++ b/server/src/services/health.ts
@@ -2,6 +2,7 @@ import { getDb } from '../db/index.js';
import { resolveProvider } from '../providers/index.js';
import { decrypt } from '../lib/crypto.js';
import type { Platform, KeyStatus } from '@freellmapi/shared/types.js';
+import { inferQuotaPoolKey } from './provider-quota.js';
const CHECK_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
const CONSECUTIVE_FAILURES_TO_DISABLE = 3;
@@ -19,7 +20,13 @@ export async function checkKeyHealth(keyId: number): Promise<KeyStatus> {
try {
const apiKey = decrypt(row.encrypted_key, row.iv, row.auth_tag);
- const isValid = await provider.validateKey(apiKey);
+ const isValid = await provider.validateKey(apiKey, {
+ platform: row.platform as Platform,
+ keyId,
+ quotaPoolKey: inferQuotaPoolKey(row.platform as Platform, null),
+ endpoint: 'models',
+ origin: 'health',
+ });
const status: KeyStatus = isValid ? 'healthy' : 'invalid';
diff --git a/server/src/services/provider-quota.ts b/server/src/services/provider-quota.ts
new file mode 100644
index 00000000..7025d270
--- /dev/null
+++ b/server/src/services/provider-quota.ts
@@ -0,0 +1,441 @@
+import crypto from 'crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { getDb } from '../db/index.js';
+import type {
+ Platform,
+ QuotaMetric,
+ QuotaObservationSource,
+ QuotaResetStrategy,
+ ProviderQuotaObservation,
+ ProviderQuotaState,
+} from '@freellmapi/shared/types.js';
+
+export interface QuotaObservationContext {
+ platform: Platform;
+ keyId?: number;
+ providerAccountId?: string | null;
+ modelId?: string | null;
+ quotaPoolKey?: string | null;
+ endpoint?: string | null;
+ origin?: 'health' | 'proxy' | 'responses' | 'manual' | 'probe';
+}
+
+export interface QuotaObservationInput {
+ platform?: Platform;
+ keyId?: number;
+ providerAccountId?: string | null;
+ modelId?: string | null;
+ quotaPoolKey?: string | null;
+ metric?: QuotaMetric;
+ limit?: number | null;
+ remaining?: number | null;
+ resetAt?: string | null;
+ retryAfterMs?: number | null;
+ resetStrategy?: QuotaResetStrategy;
+ source?: QuotaObservationSource;
+ statusCode?: number | null;
+ notes?: string | null;
+ rawJson?: string | null;
+ endpoint?: string | null;
+ confidence?: number;
+ observedAt?: string;
+}
+
+export interface QuotaObservationView extends ProviderQuotaState {
+ providerAccountId: string | null;
+ modelId: string | null;
+ endpoint: string | null;
+ statusCode: number | null;
+ retryAfterMs: number | null;
+ rawJson: string | null;
+ createdAt: string;
+}
+
+const contextStore = new AsyncLocalStorage<QuotaObservationContext>();
+
+const DEFAULT_CONFIDENCE: Record<QuotaObservationSource, number> = {
+ header: 1,
+ quota_api: 1,
+ error_body: 0.75,
+ local_usage: 0.45,
+ documentation: 0.35,
+ probe: 0.6,
+};
+
+const SOURCE_PRIORITY: Record<QuotaObservationSource, number> = {
+ header: 5,
+ quota_api: 5,
+ error_body: 4,
+ probe: 3,
+ local_usage: 2,
+ documentation: 1,
+};
+
+export function runWithQuotaObservationContext<T>(context: QuotaObservationContext, fn: () => T): T {
+ return contextStore.run(context, fn);
+}
+
+export function getQuotaObservationContext(): QuotaObservationContext | undefined {
+ return contextStore.getStore();
+}
+
+function isoNow(): string {
+ return new Date().toISOString();
+}
+
+function toSqliteUtc(value: Date | string | number): string {
+ const date = value instanceof Date ? value : new Date(value);
+ return date.toISOString().replace('T', ' ').replace('Z', '');
+}
+
+function parseHeaderNumber(raw: string | null): number | null {
+ if (!raw) return null;
+ const n = Number(raw.trim());
+ return Number.isFinite(n) ? n : null;
+}
+
+function parseResetAtFromHeader(raw: string | null, now = Date.now()): string | null {
+ const parsed = parseHeaderNumber(raw);
+ if (parsed === null) return null;
+ if (parsed > 1_000_000_000_000) return new Date(parsed).toISOString();
+ if (parsed > 1_000_000_000) return new Date(parsed * 1000).toISOString();
+ return new Date(now + parsed * 1000).toISOString();
+}
+
+function parseRetryAfterMs(raw: string | null): number | null {
+ if (!raw) return null;
+ const seconds = Number(raw.trim());
+ if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds * 1000));
+ const asDate = new Date(raw);
+ const ms = asDate.getTime();
+ if (Number.isNaN(ms)) return null;
+ return Math.max(0, ms - Date.now());
+}
+
+function pickBetterSource(existing: QuotaObservationSource | null | undefined, next: QuotaObservationSource): QuotaObservationSource {
+ if (!existing) return next;
+ return SOURCE_PRIORITY[next] >= SOURCE_PRIORITY[existing] ? next : existing;
+}
+
+function inferPoolForPlatform(platform: Platform, modelId?: string | null): string {
+ const normalizedModelId = modelId?.trim() ?? '';
+ if (platform === 'openrouter') return normalizedModelId.endsWith(':free') ? 'openrouter::free' : 'openrouter::account';
+ if (platform === 'google') return 'google::project';
+ if (platform === 'groq') return 'groq::account';
+ if (platform === 'cerebras') return 'cerebras::shared';
+ if (platform === 'sambanova') return 'sambanova::shared';
+ if (platform === 'nvidia') return 'nvidia::credit-pool';
+ if (platform === 'mistral') return 'mistral::experiment-pool';
+ if (platform === 'github') return 'github::account';
+ if (platform === 'cohere') return 'cohere::trial-pool';
+ if (platform === 'cloudflare') return 'cloudflare::account';
+ if (platform === 'zhipu') return 'zhipu::account';
+ if (platform === 'ollama') return 'ollama::cloud';
+ if (platform === 'kilo') return 'kilo::anonymous';
+ if (platform === 'pollinations') return 'pollinations::anonymous';
+ if (platform === 'llm7') return 'llm7::anonymous';
+ if (platform === 'huggingface') return 'huggingface::router';
+ if (platform === 'opencode') return 'opencode::promo';
+ return normalizedModelId ? `${platform}::${normalizedModelId}` : `${platform}::account`;
+}
+
+function isSharedPool(platform: Platform): boolean {
+ return ['openrouter', 'google', 'groq', 'cerebras', 'sambanova', 'nvidia', 'mistral', 'github', 'cohere', 'cloudflare', 'zhipu', 'ollama', 'kilo', 'pollinations', 'llm7', 'huggingface', 'opencode'].includes(platform);
+}
+
+type HeaderSpec = { metric: QuotaMetric; limit: string; remaining?: string; reset?: string; strategy?: QuotaResetStrategy };
+
+const HEADER_SPECS: Partial<Record<Platform, HeaderSpec[]>> = {
+ groq: [
+ { metric: 'requests', limit: 'x-ratelimit-limit-requests', remaining: 'x-ratelimit-remaining-requests', reset: 'x-ratelimit-reset-requests', strategy: 'provider_reported' },
+ { metric: 'tokens', limit: 'x-ratelimit-limit-tokens', remaining: 'x-ratelimit-remaining-tokens', reset: 'x-ratelimit-reset-tokens', strategy: 'provider_reported' },
+ ],
+ cerebras: [
+ { metric: 'requests', limit: 'x-ratelimit-limit-requests-day', remaining: 'x-ratelimit-remaining-requests-day', reset: 'x-ratelimit-reset-requests-day', strategy: 'provider_reported' },
+ { metric: 'tokens', limit: 'x-ratelimit-limit-tokens-minute', remaining: 'x-ratelimit-remaining-tokens-minute', reset: 'x-ratelimit-reset-tokens-minute', strategy: 'token_bucket' },
+ ],
+ openrouter: [
+ { metric: 'requests', limit: 'x-ratelimit-limit-requests', remaining: 'x-ratelimit-remaining-requests', reset: 'x-ratelimit-reset-requests', strategy: 'provider_reported' },
+ { metric: 'tokens', limit: 'x-ratelimit-limit-tokens', remaining: 'x-ratelimit-remaining-tokens', reset: 'x-ratelimit-reset-tokens', strategy: 'provider_reported' },
+ ],
+};
+
+function extractContext(opts: Pick<QuotaObservationInput, 'platform' | 'modelId' | 'quotaPoolKey' | 'keyId' | 'providerAccountId' | 'endpoint'> = {}) {
+ const context = getQuotaObservationContext();
+ const platform = opts.platform ?? context?.platform;
+ if (!platform) return null;
+ return {
+ platform,
+ keyId: opts.keyId ?? context?.keyId ?? 0,
+ providerAccountId: opts.providerAccountId ?? context?.providerAccountId ?? null,
+ modelId: opts.modelId ?? context?.modelId ?? null,
+ quotaPoolKey: opts.quotaPoolKey ?? context?.quotaPoolKey ?? inferPoolForPlatform(platform, opts.modelId ?? context?.modelId),
+ endpoint: opts.endpoint ?? context?.endpoint ?? null,
+ };
+}
+
+function maybeAddObservation(
+ observations: QuotaObservationInput[],
+ base: NonNullable<ReturnType<typeof extractContext>>,
+ metric: QuotaMetric,
+ limitRaw: string | null,
+ remainingRaw: string | null | undefined,
+ resetRaw: string | null | undefined,
+ strategy: QuotaResetStrategy,
+): void {
+ const limit = parseHeaderNumber(limitRaw);
+ const remaining = parseHeaderNumber(remainingRaw ?? null);
+ const resetAt = parseResetAtFromHeader(resetRaw ?? null);
+ if (limit === null && remaining === null && resetAt === null) return;
+ observations.push({
+ ...base,
+ metric,
+ limit,
+ remaining,
+ resetAt,
+ resetStrategy: strategy,
+ source: 'header',
+ confidence: 1,
+ });
+}
+
+export function inferQuotaPoolKey(platform: Platform, modelId?: string | null): string {
+ return inferPoolForPlatform(platform, modelId);
+}
+
+export function parseQuotaObservationsFromResponse(
+ response: Response,
+ opts: Pick<QuotaObservationInput, 'platform' | 'modelId' | 'quotaPoolKey' | 'keyId' | 'providerAccountId' | 'endpoint'> = {},
+): QuotaObservationInput[] {
+ const base = extractContext(opts);
+ if (!base) return [];
+
+ const headers = response.headers;
+ const get = (name: string) => headers?.get?.(name) ?? null;
+ const observations: QuotaObservationInput[] = [];
+ const specs = HEADER_SPECS[base.platform];
+ if (specs) {
+ for (const spec of specs) {
+ maybeAddObservation(observations, base, spec.metric, get(spec.limit), spec.remaining ? get(spec.remaining) : null, spec.reset ? get(spec.reset) : null, spec.strategy ?? 'provider_reported');
+ }
+ }
+
+ const retryAfterMs = parseRetryAfterMs(get('retry-after'));
+ if (retryAfterMs !== null) {
+ observations.push({
+ ...base,
+ metric: 'requests',
+ limit: parseHeaderNumber(get('x-ratelimit-limit-requests')),
+ remaining: 0,
+ resetAt: new Date(Date.now() + retryAfterMs).toISOString(),
+ retryAfterMs,
+ resetStrategy: 'provider_reported',
+ source: response.status === 429 ? 'header' : 'error_body',
+ confidence: response.status === 429 ? 1 : 0.8,
+ notes: `retry-after=${retryAfterMs}ms`,
+ });
+ }
+
+ if (response.status === 429 || response.status === 402) {
+ observations.push({
+ ...base,
+ metric: 'requests',
+ limit: parseHeaderNumber(get('x-ratelimit-limit-requests')),
+ remaining: 0,
+ resetAt: get('x-ratelimit-reset-requests') ? parseResetAtFromHeader(get('x-ratelimit-reset-requests')) : null,
+ retryAfterMs,
+ resetStrategy: 'unknown',
+ source: 'error_body',
+ confidence: 0.55,
+ notes: response.status === 402 ? 'upstream payment/credit exhaustion' : 'rate limited',
+ });
+ }
+
+ if (observations.length === 0 && isSharedPool(base.platform) && response.status === 200) {
+ observations.push({
+ ...base,
+ metric: 'requests',
+ limit: null,
+ remaining: null,
+ resetAt: null,
+ resetStrategy: 'unknown',
+ source: 'probe',
+ confidence: 0.1,
+ notes: 'no quota headers exposed',
+ });
+ }
+
+ return observations;
+}
+
+export function recordQuotaObservation(input: QuotaObservationInput): ProviderQuotaObservation | null {
+ const context = getQuotaObservationContext();
+ const platform = input.platform ?? context?.platform;
+ if (!platform) return null;
+
+ const keyId = input.keyId ?? context?.keyId ?? 0;
+ const quotaPoolKey = input.quotaPoolKey ?? context?.quotaPoolKey ?? inferPoolForPlatform(platform, input.modelId ?? context?.modelId);
+ const metric = input.metric ?? 'requests';
+ const source = input.source ?? 'probe';
+ const resetStrategy = input.resetStrategy ?? 'unknown';
+ const confidence = input.confidence ?? DEFAULT_CONFIDENCE[source];
+ const observedAt = input.observedAt ?? isoNow();
+ const limitValue = input.limit ?? null;
+ const remainingValue = input.remaining ?? null;
+ const resetAt = input.resetAt ?? null;
+ const retryAfterMs = input.retryAfterMs ?? null;
+ const notes = input.notes ?? null;
+ const providerAccountId = input.providerAccountId ?? context?.providerAccountId ?? null;
+ const modelId = input.modelId ?? context?.modelId ?? null;
+ const endpoint = input.endpoint ?? context?.endpoint ?? null;
+ const statusCode = input.statusCode ?? null;
+ const rawJson = input.rawJson ?? null;
+ let db;
+ try {
+ db = getDb();
+ } catch {
+ return null;
+ }
+ const id = crypto.randomUUID();
+ const nowSql = toSqliteUtc(observedAt);
+ const updatedAt = nowSql;
+
+ const prev = db.prepare(`
+ SELECT confidence, notes, source
+ FROM provider_quota_state
+ WHERE platform = ?
+ AND key_id = ?
+ AND quota_pool_key = ?
+ AND metric = ?
+ `).get(platform, keyId, quotaPoolKey, metric) as { confidence: number; notes: string | null; source: QuotaObservationSource } | undefined;
+
+ const nextConfidence = Math.max(prev?.confidence ?? 0, confidence);
+ const nextNotes = notes ?? prev?.notes ?? null;
+ const nextSource = pickBetterSource(prev?.source, source);
+
+ db.transaction(() => {
+ db.prepare(`
+ INSERT INTO provider_quota_state (
+ platform, key_id, quota_pool_key, metric, limit_value, remaining_value,
+ reset_at, reset_strategy, source, confidence, notes, observed_at, updated_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ ON CONFLICT(platform, key_id, quota_pool_key, metric) DO UPDATE SET
+ limit_value = COALESCE(excluded.limit_value, provider_quota_state.limit_value),
+ remaining_value = COALESCE(excluded.remaining_value, provider_quota_state.remaining_value),
+ reset_at = COALESCE(excluded.reset_at, provider_quota_state.reset_at),
+ reset_strategy = CASE
+ WHEN excluded.reset_strategy != 'unknown' THEN excluded.reset_strategy
+ ELSE provider_quota_state.reset_strategy
+ END,
+ confidence = MAX(provider_quota_state.confidence, excluded.confidence),
+ notes = COALESCE(excluded.notes, provider_quota_state.notes),
+ observed_at = excluded.observed_at,
+ updated_at = datetime('now')
+ `).run(
+ platform, keyId, quotaPoolKey, metric, limitValue, remainingValue, resetAt, resetStrategy, source, nextConfidence, nextNotes, nowSql, updatedAt,
+ );
+
+ db.prepare(`
+ UPDATE provider_quota_state
+ SET source = ?
+ WHERE platform = ?
+ AND key_id = ?
+ AND quota_pool_key = ?
+ AND metric = ?
+ `).run(nextSource, platform, keyId, quotaPoolKey, metric);
+
+ db.prepare(`
+ INSERT INTO provider_quota_observations (
+ id, platform, key_id, provider_account_id, model_id, quota_pool_key, metric,
+ status_code, limit_value, remaining_value, reset_at, retry_after_ms,
+ reset_strategy, source, confidence, notes, raw_json, endpoint, observed_at, created_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ `).run(
+ id, platform, keyId, providerAccountId, modelId, quotaPoolKey, metric,
+ statusCode, limitValue, remainingValue, resetAt, retryAfterMs,
+ resetStrategy, source, confidence, notes, rawJson, endpoint, nowSql, nowSql,
+ );
+ })();
+
+ return {
+ id,
+ platform,
+ keyId,
+ providerAccountId,
+ modelId,
+ quotaPoolKey,
+ metric,
+ statusCode,
+ limit: limitValue,
+ remaining: remainingValue,
+ resetAt,
+ retryAfterMs,
+ resetStrategy,
+ source,
+ confidence: nextConfidence,
+ notes: nextNotes,
+ observedAt: nowSql,
+ updatedAt,
+ endpoint,
+ rawJson,
+ createdAt: nowSql,
+ };
+}
+
+export function recordQuotaObservationsFromResponse(
+ response: Response,
+ opts: Pick<QuotaObservationInput, 'platform' | 'modelId' | 'quotaPoolKey' | 'keyId' | 'providerAccountId' | 'endpoint'> = {},
+): ProviderQuotaObservation[] {
+ return parseQuotaObservationsFromResponse(response, opts)
+ .map(recordQuotaObservation)
+ .filter((row): row is ProviderQuotaObservation => row !== null);
+}
+
+export function getQuotaStateForKeys(): QuotaObservationView[] {
+ let db;
+ try {
+ db = getDb();
+ } catch {
+ return [];
+ }
+ return db.prepare(`
+ WITH latest AS (
+ SELECT
+ oq.*,
+ ROW_NUMBER() OVER (
+ PARTITION BY oq.platform, oq.key_id, oq.quota_pool_key, oq.metric
+ ORDER BY oq.observed_at DESC, oq.created_at DESC
+ ) AS rn
+ FROM provider_quota_observations oq
+ )
+ SELECT
+ pqs.platform,
+ pqs.key_id AS keyId,
+ pqs.quota_pool_key AS quotaPoolKey,
+ pqs.metric,
+ pqs.limit_value AS "limit",
+ pqs.remaining_value AS remaining,
+ pqs.reset_at AS resetAt,
+ pqs.reset_strategy AS resetStrategy,
+ pqs.source,
+ pqs.confidence,
+ pqs.notes,
+ pqs.observed_at AS observedAt,
+ pqs.updated_at AS updatedAt,
+ NULL AS providerAccountId,
+ latest.model_id AS modelId,
+ latest.endpoint AS endpoint,
+ latest.status_code AS statusCode,
+ latest.retry_after_ms AS retryAfterMs,
+ latest.raw_json AS rawJson,
+ latest.created_at AS createdAt
+ FROM provider_quota_state pqs
+ LEFT JOIN latest
+ ON latest.platform = pqs.platform
+ AND latest.key_id = pqs.key_id
+ AND latest.quota_pool_key = pqs.quota_pool_key
+ AND latest.metric = pqs.metric
+ AND latest.rn = 1
+ ORDER BY pqs.platform ASC, pqs.key_id ASC, pqs.quota_pool_key ASC, pqs.metric ASC
+ `).all() as QuotaObservationView[];
+}
diff --git a/shared/types.ts b/shared/types.ts
index dba39844..762734bc 100644
--- a/shared/types.ts
+++ b/shared/types.ts
@@ -13,6 +13,7 @@ export type Platform =
| 'cerebras'
| 'nvidia'
| 'mistral'
+ | 'sambanova'
| 'openrouter'
| 'github'
| 'cohere'
@@ -312,3 +313,36 @@ export interface RateLimitStatus {
available: boolean;
nextResetAt: string | null;
}
+
+// ---- Provider Quota Observability ----
+
+export type QuotaMetric = 'requests' | 'tokens' | 'credits' | 'neurons';
+export type QuotaResetStrategy = 'fixed_calendar' | 'rolling_window' | 'token_bucket' | 'provider_reported' | 'unknown';
+export type QuotaObservationSource = 'header' | 'quota_api' | 'error_body' | 'local_usage' | 'documentation' | 'probe';
+
+export interface ProviderQuotaState {
+ platform: Platform;
+ keyId: number;
+ quotaPoolKey: string;
+ metric: QuotaMetric;
+ limit: number | null;
+ remaining: number | null;
+ resetAt: string | null;
+ resetStrategy: QuotaResetStrategy;
+ source: QuotaObservationSource;
+ confidence: number;
+ notes: string | null;
+ observedAt: string;
+ updatedAt: string;
+}
+
+export interface ProviderQuotaObservation extends ProviderQuotaState {
+ id: string;
+ statusCode: number | null;
+ retryAfterMs: number | null;
+ providerAccountId: string | null;
+ modelId: string | null;
+ endpoint: string | null;
+ rawJson: string | null;
+ createdAt: string;
+}