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(analytics): track pinned vs auto-routed requests

Tashfeen57b4562dada3
diff --git a/client/src/pages/AnalyticsPage.tsx b/client/src/pages/AnalyticsPage.tsx
index 32beeb52..07d1bb9b 100644
--- a/client/src/pages/AnalyticsPage.tsx
+++ b/client/src/pages/AnalyticsPage.tsx
@@ -111,6 +111,14 @@ export default function AnalyticsPage() {
? `The number shown projects your pace from the last ${spanLabel} of data to a full 30 days.`
: `The number shown is your real 30-day total.`)
+ // Pinned = the client named a specific model instead of auto-routing.
+ // Honored = that model actually served it (the rest failed over).
+ const pinned = summary?.pinnedRequests ?? 0
+ const pinHonored = summary?.pinHonoredRequests ?? 0
+ const requestsHint = pinned > 0
+ ? `${pinned} of these requests pinned a specific model by name. ${pinHonored} were served by the pinned model; ${pinned - pinHonored} failed over to a different one. The rest were auto-routed.`
+ : 'All requests in this period were auto-routed; no client pinned a specific model by name.'
+
return (
<div>
<PageHeader
@@ -135,7 +143,7 @@ export default function AnalyticsPage() {
<div className="space-y-6">
{/* Summary stats */}
<div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-6 gap-3">
- <Stat label="Requests" value={summary?.totalRequests ?? 0} />
+ <Stat label="Requests" value={summary?.totalRequests ?? 0} hint={requestsHint} />
<Stat label="Success rate" value={`${summary?.successRate ?? 0}%`} />
<Stat label="Input tokens" value={formatTokens(summary?.totalInputTokens)} />
<Stat label="Output tokens" value={formatTokens(summary?.totalOutputTokens)} />
@@ -212,6 +220,7 @@ export default function AnalyticsPage() {
<TableHead className="pl-4">Model</TableHead>
<TableHead>Provider</TableHead>
<TableHead className="text-right">Requests</TableHead>
+ <TableHead className="text-right">Pinned</TableHead>
<TableHead className="text-right">Success</TableHead>
<TableHead className="text-right">Latency</TableHead>
<TableHead className="text-right">In tokens</TableHead>
@@ -225,6 +234,7 @@ export default function AnalyticsPage() {
<TableCell className="pl-4 text-sm font-medium">{m.displayName}</TableCell>
<TableCell className="text-xs text-muted-foreground">{m.platform}</TableCell>
<TableCell className="text-right tabular-nums">{m.requests}</TableCell>
+ <TableCell className="text-right tabular-nums">{m.pinnedRequests > 0 ? m.pinnedRequests : '—'}</TableCell>
<TableCell className="text-right tabular-nums">{m.successRate}%</TableCell>
<TableCell className="text-right tabular-nums">{m.avgLatencyMs} ms</TableCell>
<TableCell className="text-right tabular-nums">{formatTokens(m.totalInputTokens)}</TableCell>
diff --git a/server/src/__tests__/routes/analytics.test.ts b/server/src/__tests__/routes/analytics.test.ts
index 913bb3ad..cf3e14a6 100644
--- a/server/src/__tests__/routes/analytics.test.ts
+++ b/server/src/__tests__/routes/analytics.test.ts
@@ -130,4 +130,39 @@ describe('Analytics API', () => {
expect(status).toBe(200);
expect(body[0].estimatedCost).toBe(2.6);
});
+
+ describe('pinned vs auto tracking', () => {
+ function insertPinnedRequest(modelId: string, requestedModel: string | null, createdAt: string) {
+ getDb().prepare(`
+ INSERT INTO requests (platform, model_id, requested_model, status, input_tokens, output_tokens, latency_ms, error, created_at)
+ VALUES ('test', ?, ?, 'success', 1, 2, 3, NULL, ?)
+ `).run(modelId, requestedModel, createdAt);
+ }
+
+ it('summary splits pinned, honored, and auto requests', async () => {
+ insertPinnedRequest('model-a', 'model-a', '2026-05-29 11:00:00'); // pin honored
+ insertPinnedRequest('model-b', 'model-a', '2026-05-29 11:01:00'); // pin overridden by failover
+ insertPinnedRequest('model-b', null, '2026-05-29 11:02:00'); // auto-routed
+
+ const { status, body } = await request(app, '/api/analytics/summary?range=24h');
+
+ expect(status).toBe(200);
+ expect(body.totalRequests).toBe(3);
+ expect(body.pinnedRequests).toBe(2);
+ expect(body.pinHonoredRequests).toBe(1);
+ });
+
+ it('by-model counts only requests the model served because it was pinned', async () => {
+ insertPinnedRequest('model-a', 'model-a', '2026-05-29 11:00:00'); // pinned + served
+ insertPinnedRequest('model-a', null, '2026-05-29 11:01:00'); // auto, same model
+ insertPinnedRequest('model-a', 'model-x', '2026-05-29 11:02:00'); // failover landed here
+
+ const { status, body } = await request(app, '/api/analytics/by-model?range=24h');
+
+ expect(status).toBe(200);
+ const row = body.find((r: any) => r.modelId === 'model-a');
+ expect(row.requests).toBe(3);
+ expect(row.pinnedRequests).toBe(1);
+ });
+ });
});
diff --git a/server/src/__tests__/routes/proxy-pinned-model.test.ts b/server/src/__tests__/routes/proxy-pinned-model.test.ts
new file mode 100644
index 00000000..b0e2cc2d
--- /dev/null
+++ b/server/src/__tests__/routes/proxy-pinned-model.test.ts
@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb, getDb, getUnifiedApiKey } from '../../db/index.js';
+import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';
+
+let dashToken = '';
+
+async function request(app: Express, method: string, path: string, body?: any, headers: Record<string, string> = {}) {
+ const server = app.listen(0);
+ const addr = server.address() as any;
+ const url = `http://127.0.0.1:${addr.port}${path}`;
+
+ const res = await fetch(url, {
+ method,
+ headers: { ...(body ? { 'Content-Type': 'application/json' } : {}), ...(isGatedApiPath(path) && !('Authorization' in headers) ? { Authorization: `Bearer ${dashToken}` } : {}), ...headers },
+ body: body ? JSON.stringify(body) : undefined,
+ });
+
+ const data = await res.text();
+ server.close();
+
+ let json: any = null;
+ try { json = JSON.parse(data); } catch {}
+
+ return { status: res.status, body: json };
+}
+
+function authHeaders() {
+ return { Authorization: `Bearer ${getUnifiedApiKey()}` };
+}
+
+// requested_model logging: a pinned request records the model id the client
+// named; an auto request records NULL. This is what lets analytics split
+// pinned vs auto traffic and surface failover overrides.
+describe('requested_model analytics logging', () => {
+ let app: Express;
+ let groqModelId: string;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ app = createApp();
+ dashToken = mintDashboardToken();
+ // Any enabled groq model from the seeded catalog will do as the pin target.
+ groqModelId = (getDb().prepare(`
+ SELECT m.model_id FROM models m
+ JOIN fallback_config fc ON fc.model_db_id = m.id
+ WHERE m.platform = 'groq' AND m.enabled = 1
+ ORDER BY fc.priority LIMIT 1
+ `).get() as { model_id: string }).model_id;
+ });
+
+ beforeEach(async () => {
+ const db = getDb();
+ db.prepare('DELETE FROM api_keys').run();
+ db.prepare('DELETE FROM requests').run();
+
+ const addKey = await request(app, 'POST', '/api/keys', {
+ platform: 'groq',
+ key: 'gsk_pinned_model_test',
+ label: 'pinned-model',
+ });
+ expect(addKey.status).toBe(201);
+
+ const origFetch = global.fetch;
+ vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+ const urlStr = typeof url === 'string' ? url : url.toString();
+ if (urlStr.includes('api.groq.com')) {
+ return {
+ ok: true,
+ json: () => Promise.resolve({
+ id: 'chatcmpl-pin', object: 'chat.completion', created: 1, model: groqModelId,
+ choices: [{ index: 0, message: { role: 'assistant', content: 'hi' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 2, completion_tokens: 1, total_tokens: 3 },
+ }),
+ } as any;
+ }
+ return origFetch(url, init);
+ });
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ it('logs the pinned model id when the client names a model', async () => {
+ const { status } = await request(app, 'POST', '/v1/chat/completions', {
+ model: groqModelId,
+ messages: [{ role: 'user', content: 'hi' }],
+ }, authHeaders());
+ expect(status).toBe(200);
+
+ const row = getDb().prepare('SELECT model_id, requested_model FROM requests ORDER BY id DESC LIMIT 1').get() as any;
+ expect(row.requested_model).toBe(groqModelId);
+ expect(row.model_id).toBe(groqModelId); // pin honored
+ });
+
+ it.each([['auto'], [undefined]])('logs NULL requested_model for auto routing (model: %s)', async (model) => {
+ const { status } = await request(app, 'POST', '/v1/chat/completions', {
+ ...(model ? { model } : {}),
+ messages: [{ role: 'user', content: 'hi' }],
+ }, authHeaders());
+ expect(status).toBe(200);
+
+ const row = getDb().prepare('SELECT requested_model FROM requests ORDER BY id DESC LIMIT 1').get() as any;
+ expect(row.requested_model).toBeNull();
+ });
+});
diff --git a/server/src/db/index.ts b/server/src/db/index.ts
index 02f8275d..d4fba2d3 100644
--- a/server/src/db/index.ts
+++ b/server/src/db/index.ts
@@ -175,6 +175,18 @@ function createTables(db: Database.Database) {
ensureApiKeysBaseUrlColumn(db);
ensureModelsKeyIdColumn(db);
ensureRequestTtfbColumn(db);
+ ensureRequestRequestedModelColumn(db);
+}
+
+// `requested_model` is the model id the CLIENT pinned in the request body.
+// NULL when the request was auto-routed ('auto' or omitted model field).
+// requested_model = model_id means the pin was honored; a different model_id
+// means rate limits or failures forced a failover to another model.
+function ensureRequestRequestedModelColumn(db: Database.Database) {
+ const columns = db.prepare('PRAGMA table_info(requests)').all() as { name: string }[];
+ if (!columns.some(col => col.name === 'requested_model')) {
+ db.prepare('ALTER TABLE requests ADD COLUMN requested_model TEXT').run();
+ }
}
// `ttfb_ms` is the time-to-first-byte for streaming responses (ms from dispatch
diff --git a/server/src/routes/analytics.ts b/server/src/routes/analytics.ts
index 9c1172d2..4c5048cf 100644
--- a/server/src/routes/analytics.ts
+++ b/server/src/routes/analytics.ts
@@ -43,6 +43,8 @@ analyticsRouter.get('/summary', (req: Request, res: Response) => {
SUM(r.output_tokens) as total_output_tokens,
AVG(r.latency_ms) as avg_latency_ms,
MIN(r.created_at) as first_request_at,
+ SUM(CASE WHEN r.requested_model IS NOT NULL THEN 1 ELSE 0 END) as pinned_count,
+ SUM(CASE WHEN r.requested_model = r.model_id THEN 1 ELSE 0 END) as pin_honored_count,
SUM(CASE WHEN r.status = 'success' THEN
r.input_tokens * COALESCE(m.paid_input_per_m, ?) / 1000000.0 +
r.output_tokens * COALESCE(m.paid_output_per_m, ?) / 1000000.0
@@ -62,6 +64,11 @@ analyticsRouter.get('/summary', (req: Request, res: Response) => {
totalOutputTokens: stats.total_output_tokens ?? 0,
avgLatencyMs: Math.round(stats.avg_latency_ms ?? 0),
estimatedCostSavings: Math.round((stats.est_savings ?? 0) * 100) / 100,
+ // Pinned = requests where the client named a specific model (not 'auto').
+ // Honored = the pinned model actually served it; the difference is
+ // failovers that overrode the pin.
+ pinnedRequests: stats.pinned_count ?? 0,
+ pinHonoredRequests: stats.pin_honored_count ?? 0,
// Lets the client project savings from the ACTUAL data span (a 2-day-old
// install shouldn't extrapolate as if the whole range had traffic).
firstRequestAt: stats.first_request_at ?? null,
@@ -84,6 +91,7 @@ analyticsRouter.get('/by-model', (req: Request, res: Response) => {
AVG(r.latency_ms) as avg_latency_ms,
SUM(r.input_tokens) as total_input_tokens,
SUM(r.output_tokens) as total_output_tokens,
+ SUM(CASE WHEN r.requested_model = r.model_id THEN 1 ELSE 0 END) as pinned_requests,
SUM(CASE WHEN r.status = 'success' THEN
r.input_tokens * COALESCE(m.paid_input_per_m, ?) / 1000000.0 +
r.output_tokens * COALESCE(m.paid_output_per_m, ?) / 1000000.0
@@ -104,6 +112,8 @@ analyticsRouter.get('/by-model', (req: Request, res: Response) => {
avgLatencyMs: Math.round(r.avg_latency_ms),
totalInputTokens: r.total_input_tokens ?? 0,
totalOutputTokens: r.total_output_tokens ?? 0,
+ // Requests this model served because the client pinned it by name.
+ pinnedRequests: r.pinned_requests ?? 0,
estimatedCost: Math.round((r.est_cost ?? 0) * 100) / 100,
})));
});
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index 397647cb..3d7fa5cd 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -566,6 +566,11 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
preferredModel = getStickyModel(messages);
}
+ // For analytics: the model id the client pinned, null when auto-routed
+ // ('auto' or omitted). Logged with every request row so pinned vs auto
+ // traffic and failover overrides are visible.
+ const pinnedModelId = requestedModel && !isAutoModel(requestedModel) ? requestedModel : null;
+
// Retry loop: on 429/rate limit, skip that model+key and try the next one
const skipKeys = new Set<string>();
let lastError: any = null;
@@ -634,7 +639,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
// instead of handing the client a valid-looking empty stream
// (production case: nemotron-3-super returning nothing on large
// contexts while the request logs as success).
- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, Date.now() - start, 'empty completion (stream produced no chunks)');
+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, Date.now() - start, 'empty completion (stream produced no chunks)', null, pinnedModelId);
skipKeys.add(`${route.platform}:${route.modelId}:${route.keyId}`);
setCooldown(route.platform, route.modelId, route.keyId, getCooldownDurationForLimit(route.platform, route.modelId, route.keyId, { rpd: route.rpdLimit, tpd: route.tpdLimit }));
recordRateLimitHit(route.modelDbId);
@@ -647,7 +652,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
recordTokens(route.platform, route.modelId, route.keyId, estimatedInputTokens + totalOutputTokens);
recordSuccess(route.modelDbId);
setStickyModel(messages, route.modelDbId);
- logRequest(route.platform, route.modelId, route.keyId, 'success', estimatedInputTokens, totalOutputTokens, Date.now() - start, null, ttfbMs);
+ logRequest(route.platform, route.modelId, route.keyId, 'success', estimatedInputTokens, totalOutputTokens, Date.now() - start, null, ttfbMs, pinnedModelId);
return;
} catch (streamErr: any) {
if (streamStarted) {
@@ -659,7 +664,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
const payload = { error: { message: `Provider error (${route.displayName}): stream interrupted`, type: 'stream_error' } };
try { res.write(`data: ${JSON.stringify(payload)}\n\n`); } catch { /* socket gone */ }
try { res.write('data: [DONE]\n\n'); res.end(); } catch { /* socket gone */ }
- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, sanitizeProviderErrorMessage(streamErr.message));
+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, totalOutputTokens, Date.now() - start, sanitizeProviderErrorMessage(streamErr.message), null, pinnedModelId);
return;
}
// Pre-stream error — bubble to outer retry/502 handler.
@@ -677,7 +682,7 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
const respMsg = result.choices?.[0]?.message;
const respText = contentToString(respMsg?.content ?? '');
if (!respText && (respMsg?.tool_calls?.length ?? 0) === 0) {
- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, Date.now() - start, 'empty completion (no content, no tool_calls)');
+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, Date.now() - start, 'empty completion (no content, no tool_calls)', null, pinnedModelId);
skipKeys.add(`${route.platform}:${route.modelId}:${route.keyId}`);
setCooldown(route.platform, route.modelId, route.keyId, getCooldownDurationForLimit(route.platform, route.modelId, route.keyId, { rpd: route.rpdLimit, tpd: route.tpdLimit }));
recordRateLimitHit(route.modelDbId);
@@ -711,14 +716,14 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
route.platform, route.modelId, route.keyId, 'success',
result.usage?.prompt_tokens ?? 0,
result.usage?.completion_tokens ?? 0,
- Date.now() - start, null,
+ Date.now() - start, null, null, pinnedModelId,
);
return;
}
} catch (err: any) {
const latency = Date.now() - start;
const safeError = sanitizeProviderErrorMessage(err.message);
- logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, latency, safeError);
+ logRequest(route.platform, route.modelId, route.keyId, 'error', estimatedInputTokens, 0, latency, safeError, null, pinnedModelId);
if (isRetryableError(err)) {
// Put this model+key on cooldown and try the next one
@@ -771,13 +776,17 @@ export function logRequest(
latencyMs: number,
error: string | null,
ttfbMs: number | null = null,
+ // The model id the client pinned; null for auto-routed requests. Lets
+ // analytics split pinned vs auto traffic and detect failover overrides
+ // (requested_model set but != model_id).
+ requestedModel: string | null = null,
) {
try {
const db = getDb();
db.prepare(`
- INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, error, ttfb_ms)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
- `).run(platform, modelId, keyId, status, inputTokens, outputTokens, latencyMs, error, ttfbMs);
+ INSERT INTO requests (platform, model_id, key_id, status, input_tokens, output_tokens, latency_ms, error, ttfb_ms, requested_model)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ `).run(platform, modelId, keyId, status, inputTokens, outputTokens, latencyMs, error, ttfbMs, requestedModel);
pruneRequestAnalytics({ db });
} catch (e) {
console.error('Failed to log request:', e);