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

feat(proxy): /v1/usage reports per-key spend with monthly caps (#1568) (#1614)

tashdroid68ae4f8a1b10
diff --git a/server/src/__tests__/routes/proxy-usage.test.ts b/server/src/__tests__/routes/proxy-usage.test.ts
index 7dd27293..7c8f0dcc 100644
--- a/server/src/__tests__/routes/proxy-usage.test.ts
+++ b/server/src/__tests__/routes/proxy-usage.test.ts
@@ -66,6 +66,38 @@ describe('GET /v1/usage', () => {
expect(body.requests).toBeUndefined();
});
+ it('breaks usage down per provider key with its monthly caps (#1568 follow-up)', async () => {
+ // A second key WITH caps, plus spend, so the response must show both keys
+ // separately and echo the caps exactly as checkMonthlyBudget enforces them.
+ const db = getDb();
+ const secret = encrypt('synthetic-capped-key');
+ const keyId = Number(db.prepare(`INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, enabled, status, monthly_request_cap, monthly_token_cap)
+ VALUES ('openrouter', 'capped', ?, ?, ?, 1, 'healthy', 100, 250000)`).run(secret.encrypted, secret.iv, secret.authTag).lastInsertRowid);
+ const model = (db.prepare("SELECT model_id FROM models WHERE platform = 'openrouter' LIMIT 1").get() as { model_id: string }).model_id;
+ db.prepare(`INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms)
+ VALUES ('openrouter', ?, ?, 'success', 50, 10, 1)`).run(model, keyId);
+
+ const res = await fetch(`${baseUrl}/v1/usage`, { headers: { Authorization: `Bearer ${token}` } });
+ expect(res.status).toBe(200);
+ const body = await res.json() as any;
+ const capped = body.byKey.find((k: any) => k.keyId === keyId);
+ expect(capped).toBeTruthy();
+ expect(capped.platform).toBe('openrouter');
+ expect(capped.label).toBe('capped');
+ expect(capped.enabled).toBe(true);
+ expect(capped.requests).toBe(1);
+ expect(capped.tokens).toBe(60);
+ expect(capped.requestCap).toBe(100);
+ expect(capped.tokenCap).toBe(250000);
+ // The uncapped groq key reports null caps, not 0 (0 would read as "cap of zero").
+ const uncapped = body.byKey.find((k: any) => k.platform === 'groq');
+ expect(uncapped.requestCap).toBeNull();
+ expect(uncapped.tokenCap).toBeNull();
+ // byKey sums to the same totals as byPlatform.
+ const sum = body.byKey.reduce((acc: number, k: any) => acc + k.tokens, 0);
+ expect(sum).toBe(body.tokens);
+ });
+
it('rejects a missing or bogus key like every other /v1 route', async () => {
const anonymous = await fetch(`${baseUrl}/v1/usage`);
expect(anonymous.status).toBe(401);
diff --git a/server/src/docs/openapi.ts b/server/src/docs/openapi.ts
index e5185c45..5588863f 100644
--- a/server/src/docs/openapi.ts
+++ b/server/src/docs/openapi.ts
@@ -636,7 +636,7 @@ export const openapiSpec = {
'the per-key monthly caps enforce, so these numbers always agree with a 429 quota_exceeded ' +
'response. Mirrors OpenRouter GET /api/v1/auth/key and LiteLLM /key/info.',
responses: {
- '200': { description: 'Usage roll-up: month, resetsAt, requests, tokens, byPlatform[].' },
+ '200': { description: 'Usage roll-up: month, resetsAt, requests, tokens, byPlatform[], byKey[] (per provider key: label, enabled, requests, tokens, requestCap, tokenCap; null cap = unlimited).' },
'401': { $ref: '#/components/responses/Unauthorized' },
'403': { description: 'Called with a client-profile key; usage is install-wide, so only the unified key may read it.' },
},
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index b7410144..16084e1b 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -515,6 +515,30 @@ proxyRouter.get('/usage', (req: Request, res: Response) => {
ORDER BY tokens DESC, requests DESC
`).all(month) as { platform: string; requests: number; tokens: number }[];
+ // Per-provider-key rows (#1568 follow-up): "groq ate 90M" still doesn't say
+ // WHICH account did it, or whether that account is about to hit the monthly
+ // cap the caller keeps being 429'd on. LiteLLM's /key/info reports limits and
+ // spend together for the same reason. Caps echo api_keys (0 = unlimited), so
+ // the answer matches checkMonthlyBudget's verdict exactly. Deleted keys keep
+ // their ledger rows orphaned; they surface under the platform 'removed' with
+ // no caps, same as the platform roll-up above.
+ const byKey = db.prepare(`
+ SELECT u.key_id AS keyId,
+ COALESCE(k.platform, 'removed') AS platform,
+ COALESCE(k.label, '') AS label,
+ COALESCE(k.enabled, 0) AS enabled,
+ u.requests AS requests, u.tokens AS tokens,
+ COALESCE(k.monthly_request_cap, 0) AS requestCap,
+ COALESCE(k.monthly_token_cap, 0) AS tokenCap
+ FROM key_monthly_usage u
+ LEFT JOIN api_keys k ON k.id = u.key_id
+ WHERE u.month = ? AND (u.requests > 0 OR u.tokens > 0)
+ ORDER BY u.tokens DESC, u.requests DESC
+ `).all(month) as {
+ keyId: number; platform: string; label: string; enabled: number;
+ requests: number; tokens: number; requestCap: number; tokenCap: number;
+ }[];
+
res.json({
object: 'usage',
month,
@@ -522,6 +546,18 @@ proxyRouter.get('/usage', (req: Request, res: Response) => {
requests: totals.requests,
tokens: totals.tokens,
byPlatform,
+ byKey: byKey.map(k => ({
+ keyId: k.keyId,
+ platform: k.platform,
+ label: k.label,
+ enabled: k.enabled === 1,
+ requests: k.requests,
+ tokens: k.tokens,
+ // null = unlimited, matching how the dashboard renders "no cap" and
+ // sparing a script from treating 0 as "cap of zero requests".
+ requestCap: k.requestCap > 0 ? k.requestCap : null,
+ tokenCap: k.tokenCap > 0 ? k.tokenCap : null,
+ })),
});
});