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): GET /v1/usage — month-to-date consumption behind the key (#1600)

tashdroid064c6325af89
diff --git a/server/src/__tests__/routes/docs.test.ts b/server/src/__tests__/routes/docs.test.ts
index 8a4a7f32..00b20b65 100644
--- a/server/src/__tests__/routes/docs.test.ts
+++ b/server/src/__tests__/routes/docs.test.ts
@@ -72,11 +72,12 @@ describe('OpenAPI docs routes', () => {
}
});
- // Guard against re-introducing the stale fork endpoint: the fork's spec
- // documented GET /v1/usage, which has never existed on this router.
- it('does not expose a phantom /v1/usage endpoint', async () => {
+ // GET /v1/usage used to be a phantom inherited from the fork's spec. It is
+ // real now (#1568): an authenticated route, so it must answer 401 without a
+ // key and must never 404.
+ it('serves /v1/usage instead of 404ing on it', async () => {
const { status } = await request(app, 'GET', '/v1/usage');
- expect(status).toBe(404);
+ expect(status).not.toBe(404);
});
it('has internally consistent $ref pointers', () => {
diff --git a/server/src/__tests__/routes/proxy-usage.test.ts b/server/src/__tests__/routes/proxy-usage.test.ts
new file mode 100644
index 00000000..7dd27293
--- /dev/null
+++ b/server/src/__tests__/routes/proxy-usage.test.ts
@@ -0,0 +1,75 @@
+import { beforeAll, afterAll, describe, it, expect } from 'vitest';
+import { once } from 'node:events';
+import type { Server } from 'node:http';
+import { createApp } from '../../app.js';
+import { initDb, getDb, getUnifiedApiKey } from '../../db/index.js';
+import { encrypt } from '../../lib/crypto.js';
+import { hashClientProfileKey } from '../../lib/system-prompt.js';
+
+// GET /v1/usage (#1568): OpenRouter (GET /api/v1/auth/key) and LiteLLM
+// (/key/info) let a key-holder see its own consumption; until now the only
+// way to answer "what ate my tokens" was opening the dashboard. The payload
+// must come from key_monthly_usage — the SAME ledger the monthly caps enforce
+// — so the numbers can never disagree with a 429 the client just got.
+
+let server: Server;
+let baseUrl: string;
+let token: string;
+const PROFILE_TOKEN = 'sk-cp-' + 'a'.repeat(48);
+
+beforeAll(async () => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ const db = getDb();
+ const secret = encrypt('synthetic-usage-test-key');
+ const keyId = Number(db.prepare(`INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, enabled, status)
+ VALUES ('groq', 'usage-test', ?, ?, ?, 1, 'healthy')`).run(secret.encrypted, secret.iv, secret.authTag).lastInsertRowid);
+ const model = (db.prepare("SELECT model_id FROM models WHERE platform = 'groq' LIMIT 1").get() as { model_id: string }).model_id;
+ // Two successes (counted) and one error (never counted) via the ledger trigger.
+ db.prepare(`INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms)
+ VALUES ('groq', ?, ?, 'success', 100, 40, 1)`).run(model, keyId);
+ db.prepare(`INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms)
+ VALUES ('groq', ?, ?, 'success', 7, 3, 1)`).run(model, keyId);
+ db.prepare(`INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms)
+ VALUES ('groq', ?, ?, 'error', 9999, 9999, 1)`).run(model, keyId);
+ token = getUnifiedApiKey();
+ const profileSecret = encrypt(PROFILE_TOKEN);
+ db.prepare(`INSERT INTO client_profiles (name, token_hash, encrypted_key, iv, auth_tag, enabled)
+ VALUES ('downstream', ?, ?, ?, ?, 1)`).run(hashClientProfileKey(PROFILE_TOKEN), profileSecret.encrypted, profileSecret.iv, profileSecret.authTag);
+ server = createApp().listen(0, '127.0.0.1');
+ await once(server, 'listening');
+ baseUrl = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+});
+afterAll(() => new Promise<void>((resolve, reject) => server.close(err => err ? reject(err) : resolve())));
+
+describe('GET /v1/usage', () => {
+ it('reports month-to-date usage from the budget ledger, split by platform', async () => {
+ const res = await fetch(`${baseUrl}/v1/usage`, { headers: { Authorization: `Bearer ${token}` } });
+ expect(res.status).toBe(200);
+ const body = await res.json() as any;
+ expect(body.object).toBe('usage');
+ expect(body.month).toMatch(/^\d{4}-\d{2}$/);
+ expect(typeof body.resetsAt).toBe('string');
+ // Only the two successes count; the error row never enters the ledger.
+ expect(body.requests).toBe(2);
+ expect(body.tokens).toBe(150);
+ const groq = body.byPlatform.find((p: any) => p.platform === 'groq');
+ expect(groq).toBeTruthy();
+ expect(groq.requests).toBe(2);
+ expect(groq.tokens).toBe(150);
+ });
+
+ it('refuses a client-profile key: the ledger is install-wide, not per client', async () => {
+ const res = await fetch(`${baseUrl}/v1/usage`, { headers: { Authorization: `Bearer ${PROFILE_TOKEN}` } });
+ expect(res.status).toBe(403);
+ const body = await res.json() as any;
+ expect(body.requests).toBeUndefined();
+ });
+
+ 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);
+ const bogus = await fetch(`${baseUrl}/v1/usage`, { headers: { Authorization: 'Bearer ***' } });
+ expect(bogus.status).toBe(401);
+ });
+});
diff --git a/server/src/docs/openapi.ts b/server/src/docs/openapi.ts
index 3f65bbf5..e5185c45 100644
--- a/server/src/docs/openapi.ts
+++ b/server/src/docs/openapi.ts
@@ -624,6 +624,24 @@ export const openapiSpec = {
},
},
},
+ '/v1/usage': {
+ get: {
+ tags: ['Models'],
+ operationId: 'getUsage',
+ summary: 'Month-to-date consumption for this gateway',
+ description:
+ 'Unified API key only (client-profile keys get 403). ' +
+ 'Returns the current calendar month\'s successful requests and tokens, split by provider ' +
+ 'platform, plus the UTC instant when the monthly window resets. Read from the same ledger ' +
+ '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[].' },
+ '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.' },
+ },
+ },
+ },
'/v1beta/models': {
get: {
tags: ['Gemini'],
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index e1ca1bda..bfbcef75 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -4,7 +4,7 @@ import type { Request, Response } from 'express';
import { z } from 'zod';
import type { ChatMessage, ChatToolCall, TokenUsage } from '@freellmapi/shared/types.js';
import { type RouteResult, type ResolvedChain, type ChainRow, routeRequest, resolveRoutingChain, resolveModelGroupCandidates, resolveStickyPreference, hasEnabledVisionModel, hasEnabledToolsModel, routingReserveTokens, failureAttributionFor } from '../services/router.js';
-import { secondsUntilNextMonth } from '../services/key-budget.js';
+import { secondsUntilNextMonth, nextMonthResetAt } from '../services/key-budget.js';
import { runEmbeddings, EmbeddingsError } from '../services/embeddings.js';
import { runRerank, RerankError, rerankRetryAfterSec } from '../services/rerank.js';
import { runSearch, SearchError, searchRetryAfterSec, listSearchEngines } from '../services/search.js';
@@ -472,6 +472,60 @@ proxyRouter.get('/models', (req: Request, res: Response) => {
});
+// GET /v1/usage — self-service consumption for inference clients (#1568).
+//
+// OpenRouter exposes GET /api/v1/auth/key (usage + limits for the calling key)
+// and LiteLLM exposes /key/info; every agent user who wonders "what happened
+// to my 120M tokens" currently has to open the dashboard to find out. This
+// puts the same answer behind the key that spent the tokens: one month-to-date
+// roll-up of successful proxied requests, split by provider platform, plus
+// when the window resets.
+//
+// Reads the durable key_monthly_usage ledger (the per-key monthly-cap source),
+// NOT the analytics table, so retention pruning can never make the answer
+// disagree with what the caps enforce. Aggregated per PROVIDER key joined to
+// api_keys for the platform label; requests whose key was deleted have already
+// dropped out of the ledger's join and are reported under "removed".
+//
+// The ledger is install-wide (requests are not tagged with the client profile
+// that sent them), so only the unified key may read it. A client-profile key
+// (sk-cp-...) is handed to a downstream client and must not see what every
+// other client spent.
+proxyRouter.get('/usage', (req: Request, res: Response) => {
+ const auth = requireInferenceAuth(req, res);
+ if (!auth) return;
+ if (auth.kind !== 'unified') {
+ res.status(403).json({ error: { message: 'Usage is only available to the unified API key', type: 'permission_error' } });
+ return;
+ }
+
+ const month = new Date().toISOString().slice(0, 7);
+ const db = getDb();
+ const totals = db.prepare(`
+ SELECT COALESCE(SUM(requests), 0) AS requests, COALESCE(SUM(tokens), 0) AS tokens
+ FROM key_monthly_usage WHERE month = ?
+ `).get(month) as { requests: number; tokens: number };
+ const byPlatform = db.prepare(`
+ SELECT COALESCE(k.platform, 'removed') AS platform,
+ SUM(u.requests) AS requests, SUM(u.tokens) AS tokens
+ FROM key_monthly_usage u
+ LEFT JOIN api_keys k ON k.id = u.key_id
+ WHERE u.month = ?
+ GROUP BY COALESCE(k.platform, 'removed')
+ ORDER BY tokens DESC, requests DESC
+ `).all(month) as { platform: string; requests: number; tokens: number }[];
+
+ res.json({
+ object: 'usage',
+ month,
+ resetsAt: nextMonthResetAt(),
+ requests: totals.requests,
+ tokens: totals.tokens,
+ byPlatform,
+ });
+});
+
+
const MAX_RETRIES = 20;
// Echo-tolerant tool calls: agents replay OUR responses back as history, and