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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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