feat: usage stats page with time-series token tracking (#147)

* feat: usage stats page with time-series token tracking

- Background snapshot recording (piggybacks on quota refresh, ~5min interval)
- UsageStatsStore: JSON persistence, 7-day retention, delta computation
- GET /admin/usage-stats/summary — live cumulative totals
- GET /admin/usage-stats/history — time-series deltas with hourly/daily granularity
- Pure SVG line charts (input/output tokens + request count)
- Granularity (hourly/daily) and range (24h/3d/7d) selectors
- 13 backend tests (snapshot, delta, aggregation, retention, API routes)
- i18n: en + zh

* fix: usage stats review fixes — chart coords, refresh, cleanup

---------

Co-authored-by: icebear0828 <icebear0828@users.noreply.github.com>

CHANGELOG.md

@@ -15,6 +15,12 @@
   - 后台额度刷新周期性重试 banned 账号，成功即自动解封
 - 上游 401 token 吊销（"token has been invalidated"）自动标记过期并切换下一个账号
   - 之前 401 直接透传给客户端，不标记也不重试
+- Usage Stats 页面（`#/usage-stats`）：累计 token 用量汇总 + 时间趋势图
+  - 后台每 5 分钟记录用量快照，保留 7 天历史
+  - `GET /admin/usage-stats/summary` 实时累计汇总
+  - `GET /admin/usage-stats/history?granularity=hourly|daily&hours=N` 时间序列增量
+  - 纯 SVG 折线图（input/output tokens + 请求数），无外部图表库
+  - 支持按小时/按天粒度，24h/3d/7d 时间范围切换
 - Account Management 页面（`#/account-management`）：批量删除、批量改状态（active/disabled）、导入导出
   - `POST /auth/accounts/batch-delete` 和 `POST /auth/accounts/batch-status` 批量端点
   - 状态摘要条可点击筛选，复用 AccountTable 选择/分页/Shift 多选

shared/hooks/use-usage-stats.ts

@@ -0,0 +1,70 @@
+/**
+ * Hooks for fetching usage stats data.
+ */
+
+import { useState, useEffect, useCallback } from "preact/hooks";
+
+export interface UsageSummary {
+  total_input_tokens: number;
+  total_output_tokens: number;
+  total_request_count: number;
+  total_accounts: number;
+  active_accounts: number;
+}
+
+export interface UsageDataPoint {
+  timestamp: string;
+  input_tokens: number;
+  output_tokens: number;
+  request_count: number;
+}
+
+export type Granularity = "raw" | "hourly" | "daily";
+
+export function useUsageSummary(refreshIntervalMs = 30_000) {
+  const [summary, setSummary] = useState<UsageSummary | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  const load = useCallback(async () => {
+    try {
+      const resp = await fetch("/admin/usage-stats/summary");
+      if (resp.ok) setSummary(await resp.json());
+    } catch { /* ignore */ }
+    setLoading(false);
+  }, []);
+
+  useEffect(() => {
+    load();
+    const id = setInterval(load, refreshIntervalMs);
+    return () => clearInterval(id);
+  }, [load, refreshIntervalMs]);
+
+  return { summary, loading };
+}
+
+export function useUsageHistory(granularity: Granularity, hours: number, refreshIntervalMs = 60_000) {
+  const [dataPoints, setDataPoints] = useState<UsageDataPoint[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  const load = useCallback(async () => {
+    try {
+      const resp = await fetch(
+        `/admin/usage-stats/history?granularity=${granularity}&hours=${hours}`,
+      );
+      if (resp.ok) {
+        const body = await resp.json();
+        setDataPoints(body.data_points);
+      }
+    } catch { /* ignore */ }
+    setLoading(false);
+  }, [granularity, hours]);
+
+  useEffect(() => {
+    setLoading(true);
+    load();
+    const id = setInterval(load, refreshIntervalMs);
+    return () => clearInterval(id);
+  }, [load, refreshIntervalMs]);
+
+  return { dataPoints, loading };
+}

shared/i18n/translations.ts

@@ -210,6 +210,16 @@ export const translations = {
     deleteSuccess: "Deleted",
     statusChangeSuccess: "Updated",
     cancel: "Cancel",
+    usageStats: "Usage Stats",
+    totalInputTokens: "Input Tokens",
+    totalOutputTokens: "Output Tokens",
+    totalRequestCount: "Total Requests",
+    activeAccounts: "Active Accounts",
+    granularityHourly: "Hourly",
+    granularityDaily: "Daily",
+    last24h: "Last 24h",
+    last3d: "Last 3d",
+    last7d: "Last 7d",
   },
   zh: {
     serverOnline: "\u670d\u52a1\u8fd0\u884c\u4e2d",
@@ -425,6 +435,16 @@ export const translations = {
     deleteSuccess: "已删除",
     statusChangeSuccess: "已更新",
     cancel: "取消",
+    usageStats: "用量统计",
+    totalInputTokens: "输入 Token",
+    totalOutputTokens: "输出 Token",
+    totalRequestCount: "总请求数",
+    activeAccounts: "活跃账号",
+    granularityHourly: "按小时",
+    granularityDaily: "按天",
+    last24h: "最近 24h",
+    last3d: "最近 3 天",
+    last7d: "最近 7 天",
   },
 } as const;
 

src/auth/__tests__/usage-stats.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Tests for UsageStatsStore — snapshot recording, delta computation, aggregation.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../../paths.js", () => ({
+  getDataDir: vi.fn(() => "/tmp/test-data"),
+}));
+
+import { UsageStatsStore, type UsageStatsPersistence, type UsageSnapshot } from "../usage-stats.js";
+import type { AccountPool } from "../account-pool.js";
+
+function createMockPersistence(initial: UsageSnapshot[] = []): UsageStatsPersistence & { saved: UsageSnapshot[] } {
+  const store = {
+    saved: initial,
+    load: () => ({ version: 1 as const, snapshots: [...initial] }),
+    save: vi.fn((data: { version: 1; snapshots: UsageSnapshot[] }) => {
+      store.saved = data.snapshots;
+    }),
+  };
+  return store;
+}
+
+function createMockPool(entries: Array<{
+  status: string;
+  input_tokens: number;
+  output_tokens: number;
+  request_count: number;
+}>): AccountPool {
+  return {
+    getAllEntries: () =>
+      entries.map((e, i) => ({
+        id: `entry-${i}`,
+        status: e.status,
+        usage: {
+          input_tokens: e.input_tokens,
+          output_tokens: e.output_tokens,
+          request_count: e.request_count,
+        },
+      })),
+  } as unknown as AccountPool;
+}
+
+describe("UsageStatsStore", () => {
+  let persistence: ReturnType<typeof createMockPersistence>;
+  let store: UsageStatsStore;
+
+  beforeEach(() => {
+    persistence = createMockPersistence();
+    store = new UsageStatsStore(persistence);
+  });
+
+  describe("recordSnapshot", () => {
+    it("records cumulative totals from all accounts", () => {
+      const pool = createMockPool([
+        { status: "active", input_tokens: 1000, output_tokens: 200, request_count: 5 },
+        { status: "active", input_tokens: 500, output_tokens: 100, request_count: 3 },
+        { status: "expired", input_tokens: 300, output_tokens: 50, request_count: 2 },
+      ]);
+
+      store.recordSnapshot(pool);
+
+      expect(store.snapshotCount).toBe(1);
+      expect(persistence.save).toHaveBeenCalledTimes(1);
+
+      const saved = persistence.saved;
+      expect(saved).toHaveLength(1);
+      expect(saved[0].totals).toEqual({
+        input_tokens: 1800,
+        output_tokens: 350,
+        request_count: 10,
+        active_accounts: 2,
+      });
+    });
+
+    it("handles empty pool", () => {
+      const pool = createMockPool([]);
+      store.recordSnapshot(pool);
+
+      expect(store.snapshotCount).toBe(1);
+      expect(persistence.saved[0].totals).toEqual({
+        input_tokens: 0,
+        output_tokens: 0,
+        request_count: 0,
+        active_accounts: 0,
+      });
+    });
+  });
+
+  describe("getSummary", () => {
+    it("returns live totals from pool", () => {
+      const pool = createMockPool([
+        { status: "active", input_tokens: 1000, output_tokens: 200, request_count: 5 },
+        { status: "disabled", input_tokens: 500, output_tokens: 100, request_count: 3 },
+      ]);
+
+      const summary = store.getSummary(pool);
+      expect(summary).toEqual({
+        total_input_tokens: 1500,
+        total_output_tokens: 300,
+        total_request_count: 8,
+        total_accounts: 2,
+        active_accounts: 1,
+      });
+    });
+  });
+
+  describe("getHistory", () => {
+    it("returns empty for less than 2 snapshots", () => {
+      expect(store.getHistory(24, "hourly")).toEqual([]);
+    });
+
+    it("computes deltas between consecutive snapshots", () => {
+      const now = Date.now();
+      const snapshots: UsageSnapshot[] = [
+        {
+          timestamp: new Date(now - 3600_000).toISOString(),
+          totals: { input_tokens: 100, output_tokens: 20, request_count: 2, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(now - 1800_000).toISOString(),
+          totals: { input_tokens: 300, output_tokens: 50, request_count: 5, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(now).toISOString(),
+          totals: { input_tokens: 600, output_tokens: 100, request_count: 10, active_accounts: 1 },
+        },
+      ];
+
+      persistence = createMockPersistence(snapshots);
+      store = new UsageStatsStore(persistence);
+
+      const raw = store.getHistory(2, "raw");
+      expect(raw).toHaveLength(2);
+      expect(raw[0].input_tokens).toBe(200);
+      expect(raw[0].output_tokens).toBe(30);
+      expect(raw[0].request_count).toBe(3);
+      expect(raw[1].input_tokens).toBe(300);
+      expect(raw[1].output_tokens).toBe(50);
+      expect(raw[1].request_count).toBe(5);
+    });
+
+    it("clamps negative deltas to zero (account removal)", () => {
+      const now = Date.now();
+      const snapshots: UsageSnapshot[] = [
+        {
+          timestamp: new Date(now - 3600_000).toISOString(),
+          totals: { input_tokens: 1000, output_tokens: 200, request_count: 10, active_accounts: 2 },
+        },
+        {
+          timestamp: new Date(now).toISOString(),
+          totals: { input_tokens: 500, output_tokens: 100, request_count: 5, active_accounts: 1 },
+        },
+      ];
+
+      persistence = createMockPersistence(snapshots);
+      store = new UsageStatsStore(persistence);
+
+      const raw = store.getHistory(2, "raw");
+      expect(raw).toHaveLength(1);
+      expect(raw[0].input_tokens).toBe(0);
+      expect(raw[0].output_tokens).toBe(0);
+      expect(raw[0].request_count).toBe(0);
+    });
+
+    it("aggregates into hourly buckets", () => {
+      const now = Date.now();
+      const hourStart = Math.floor(now / 3600_000) * 3600_000;
+
+      const snapshots: UsageSnapshot[] = [
+        {
+          timestamp: new Date(hourStart - 1800_000).toISOString(),
+          totals: { input_tokens: 0, output_tokens: 0, request_count: 0, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(hourStart - 900_000).toISOString(),
+          totals: { input_tokens: 100, output_tokens: 10, request_count: 1, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(hourStart + 100_000).toISOString(),
+          totals: { input_tokens: 300, output_tokens: 30, request_count: 3, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(hourStart + 200_000).toISOString(),
+          totals: { input_tokens: 500, output_tokens: 50, request_count: 5, active_accounts: 1 },
+        },
+      ];
+
+      persistence = createMockPersistence(snapshots);
+      store = new UsageStatsStore(persistence);
+
+      const hourly = store.getHistory(2, "hourly");
+      // Two buckets: one before hourStart, one at/after hourStart
+      expect(hourly).toHaveLength(2);
+
+      // Previous hour bucket: delta 0→100 = 100
+      expect(hourly[0].input_tokens).toBe(100);
+      // Current hour bucket: delta 100→300 + 300→500 = 200 + 200 = 400
+      expect(hourly[1].input_tokens).toBe(400);
+    });
+
+    it("filters by time range", () => {
+      const now = Date.now();
+      const snapshots: UsageSnapshot[] = [
+        {
+          timestamp: new Date(now - 48 * 3600_000).toISOString(), // 48h ago
+          totals: { input_tokens: 100, output_tokens: 10, request_count: 1, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(now - 12 * 3600_000).toISOString(), // 12h ago
+          totals: { input_tokens: 500, output_tokens: 50, request_count: 5, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(now).toISOString(),
+          totals: { input_tokens: 1000, output_tokens: 100, request_count: 10, active_accounts: 1 },
+        },
+      ];
+
+      persistence = createMockPersistence(snapshots);
+      store = new UsageStatsStore(persistence);
+
+      // Only last 24h → only the last two snapshots qualify → 1 delta
+      const raw = store.getHistory(24, "raw");
+      expect(raw).toHaveLength(1);
+      expect(raw[0].input_tokens).toBe(500);
+    });
+  });
+
+  describe("retention", () => {
+    it("prunes snapshots older than 7 days on record", () => {
+      const now = Date.now();
+      const old: UsageSnapshot[] = [
+        {
+          timestamp: new Date(now - 8 * 24 * 3600_000).toISOString(), // 8 days ago
+          totals: { input_tokens: 100, output_tokens: 10, request_count: 1, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(now - 1 * 3600_000).toISOString(), // 1h ago
+          totals: { input_tokens: 500, output_tokens: 50, request_count: 5, active_accounts: 1 },
+        },
+      ];
+
+      persistence = createMockPersistence(old);
+      store = new UsageStatsStore(persistence);
+
+      const pool = createMockPool([
+        { status: "active", input_tokens: 1000, output_tokens: 100, request_count: 10 },
+      ]);
+      store.recordSnapshot(pool);
+
+      // Old snapshot pruned, recent + new remain
+      expect(store.snapshotCount).toBe(2);
+    });
+  });
+});

src/auth/usage-refresher.ts

@@ -21,6 +21,7 @@ import {
 import type { AccountPool } from "./account-pool.js";
 import type { CookieJar } from "../proxy/cookie-jar.js";
 import type { ProxyPool } from "../proxy/proxy-pool.js";
+import type { UsageStatsStore } from "./usage-stats.js";
 
 /** Check if a CodexApiError indicates the account is banned/suspended (non-CF 403). */
 function isBanError(err: unknown): boolean {
@@ -44,6 +45,7 @@ let _refreshTimer: ReturnType<typeof setTimeout> | null = null;
 let _accountPool: AccountPool | null = null;
 let _cookieJar: CookieJar | null = null;
 let _proxyPool: ProxyPool | null = null;
+let _usageStats: UsageStatsStore | null = null;
 
 async function fetchQuotaForAllAccounts(
   pool: AccountPool,
@@ -143,6 +145,15 @@ async function fetchQuotaForAllAccounts(
   }
 
   console.log(`[QuotaRefresh] Done: ${succeeded}/${entries.length} succeeded`);
+
+  // Record usage snapshot for time-series history
+  if (_usageStats) {
+    try {
+      _usageStats.recordSnapshot(pool);
+    } catch (err) {
+      console.warn("[QuotaRefresh] Failed to record usage snapshot:", err instanceof Error ? err.message : err);
+    }
+  }
 }
 
 function scheduleNext(
@@ -167,10 +178,12 @@ export function startQuotaRefresh(
   accountPool: AccountPool,
   cookieJar: CookieJar,
   proxyPool?: ProxyPool,
+  usageStats?: UsageStatsStore,
 ): void {
   _accountPool = accountPool;
   _cookieJar = cookieJar;
   _proxyPool = proxyPool ?? null;
+  _usageStats = usageStats ?? null;
 
   _refreshTimer = setTimeout(async () => {
     try {

src/auth/usage-stats.ts

@@ -0,0 +1,233 @@
+/**
+ * Usage Stats — time-series snapshot recording and aggregation.
+ *
+ * Records periodic snapshots of cumulative token usage across all accounts.
+ * Snapshots are persisted to data/usage-history.json and pruned to 7 days.
+ * Aggregation (delta computation, bucketing) happens on read.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  existsSync,
+  mkdirSync,
+} from "fs";
+import { resolve, dirname } from "path";
+import { getDataDir } from "../paths.js";
+import type { AccountPool } from "./account-pool.js";
+
+// ── Types ──────────────────────────────────────────────────────────
+
+export interface UsageSnapshot {
+  timestamp: string; // ISO 8601
+  totals: {
+    input_tokens: number;
+    output_tokens: number;
+    request_count: number;
+    active_accounts: number;
+  };
+}
+
+interface UsageHistoryFile {
+  version: 1;
+  snapshots: UsageSnapshot[];
+}
+
+export interface UsageDataPoint {
+  timestamp: string;
+  input_tokens: number;
+  output_tokens: number;
+  request_count: number;
+}
+
+export interface UsageSummary {
+  total_input_tokens: number;
+  total_output_tokens: number;
+  total_request_count: number;
+  total_accounts: number;
+  active_accounts: number;
+}
+
+// ── Constants ──────────────────────────────────────────────────────
+
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const HISTORY_FILE = "usage-history.json";
+
+// ── Persistence interface (injectable for testing) ─────────────────
+
+export interface UsageStatsPersistence {
+  load(): UsageHistoryFile;
+  save(data: UsageHistoryFile): void;
+}
+
+export function createFsUsageStatsPersistence(): UsageStatsPersistence {
+  function getFilePath(): string {
+    return resolve(getDataDir(), HISTORY_FILE);
+  }
+
+  return {
+    load(): UsageHistoryFile {
+      try {
+        const filePath = getFilePath();
+        if (!existsSync(filePath)) return { version: 1, snapshots: [] };
+        const raw = readFileSync(filePath, "utf-8");
+        const data = JSON.parse(raw) as UsageHistoryFile;
+        if (!Array.isArray(data.snapshots)) return { version: 1, snapshots: [] };
+        return data;
+      } catch {
+        return { version: 1, snapshots: [] };
+      }
+    },
+
+    save(data: UsageHistoryFile): void {
+      try {
+        const filePath = getFilePath();
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+        const tmpFile = filePath + ".tmp";
+        writeFileSync(tmpFile, JSON.stringify(data), "utf-8");
+        renameSync(tmpFile, filePath);
+      } catch (err) {
+        console.error("[UsageStats] Failed to persist:", err instanceof Error ? err.message : err);
+      }
+    },
+  };
+}
+
+// ── Store ──────────────────────────────────────────────────────────
+
+export class UsageStatsStore {
+  private persistence: UsageStatsPersistence;
+  private snapshots: UsageSnapshot[];
+
+  constructor(persistence?: UsageStatsPersistence) {
+    this.persistence = persistence ?? createFsUsageStatsPersistence();
+    this.snapshots = this.persistence.load().snapshots;
+  }
+
+  /** Take a snapshot of current cumulative usage across all accounts. */
+  recordSnapshot(pool: AccountPool): void {
+    const entries = pool.getAllEntries();
+    const now = new Date().toISOString();
+
+    let input_tokens = 0;
+    let output_tokens = 0;
+    let request_count = 0;
+    let active_accounts = 0;
+
+    for (const entry of entries) {
+      input_tokens += entry.usage.input_tokens;
+      output_tokens += entry.usage.output_tokens;
+      request_count += entry.usage.request_count;
+      if (entry.status === "active") active_accounts++;
+    }
+
+    this.snapshots.push({
+      timestamp: now,
+      totals: { input_tokens, output_tokens, request_count, active_accounts },
+    });
+
+    // Prune old snapshots
+    const cutoff = Date.now() - MAX_AGE_MS;
+    this.snapshots = this.snapshots.filter(
+      (s) => new Date(s.timestamp).getTime() >= cutoff,
+    );
+
+    this.persistence.save({ version: 1, snapshots: this.snapshots });
+  }
+
+  /** Get current cumulative summary from live pool data. */
+  getSummary(pool: AccountPool): UsageSummary {
+    const entries = pool.getAllEntries();
+    let total_input_tokens = 0;
+    let total_output_tokens = 0;
+    let total_request_count = 0;
+    let active_accounts = 0;
+
+    for (const entry of entries) {
+      total_input_tokens += entry.usage.input_tokens;
+      total_output_tokens += entry.usage.output_tokens;
+      total_request_count += entry.usage.request_count;
+      if (entry.status === "active") active_accounts++;
+    }
+
+    return {
+      total_input_tokens,
+      total_output_tokens,
+      total_request_count,
+      total_accounts: entries.length,
+      active_accounts,
+    };
+  }
+
+  /**
+   * Get usage history as delta data points, aggregated by granularity.
+   * @param hours - how many hours of history to return
+   * @param granularity - "raw" | "hourly" | "daily"
+   */
+  getHistory(
+    hours: number,
+    granularity: "raw" | "hourly" | "daily",
+  ): UsageDataPoint[] {
+    const cutoff = Date.now() - hours * 60 * 60 * 1000;
+    const filtered = this.snapshots.filter(
+      (s) => new Date(s.timestamp).getTime() >= cutoff,
+    );
+
+    if (filtered.length < 2) return [];
+
+    // Compute deltas between consecutive snapshots
+    const deltas: UsageDataPoint[] = [];
+    for (let i = 1; i < filtered.length; i++) {
+      const prev = filtered[i - 1].totals;
+      const curr = filtered[i].totals;
+      deltas.push({
+        timestamp: filtered[i].timestamp,
+        input_tokens: Math.max(0, curr.input_tokens - prev.input_tokens),
+        output_tokens: Math.max(0, curr.output_tokens - prev.output_tokens),
+        request_count: Math.max(0, curr.request_count - prev.request_count),
+      });
+    }
+
+    if (granularity === "raw") return deltas;
+
+    // Bucket into time intervals
+    const bucketMs = granularity === "hourly" ? 3600_000 : 86400_000;
+    return bucketize(deltas, bucketMs);
+  }
+
+  /** Get raw snapshot count (for testing). */
+  get snapshotCount(): number {
+    return this.snapshots.length;
+  }
+}
+
+function bucketize(deltas: UsageDataPoint[], bucketMs: number): UsageDataPoint[] {
+  if (deltas.length === 0) return [];
+
+  const buckets = new Map<number, UsageDataPoint>();
+
+  for (const d of deltas) {
+    const t = new Date(d.timestamp).getTime();
+    const bucketKey = Math.floor(t / bucketMs) * bucketMs;
+
+    const existing = buckets.get(bucketKey);
+    if (existing) {
+      existing.input_tokens += d.input_tokens;
+      existing.output_tokens += d.output_tokens;
+      existing.request_count += d.request_count;
+    } else {
+      buckets.set(bucketKey, {
+        timestamp: new Date(bucketKey).toISOString(),
+        input_tokens: d.input_tokens,
+        output_tokens: d.output_tokens,
+        request_count: d.request_count,
+      });
+    }
+  }
+
+  return [...buckets.values()].sort(
+    (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+  );
+}

src/index.ts

@@ -25,6 +25,7 @@ import { initTransport } from "./tls/transport.js";
 import { loadStaticModels } from "./models/model-store.js";
 import { startModelRefresh, stopModelRefresh } from "./models/model-fetcher.js";
 import { startQuotaRefresh, stopQuotaRefresh } from "./auth/usage-refresher.js";
+import { UsageStatsStore } from "./auth/usage-stats.js";
 
 export interface ServerHandle {
   close: () => Promise<void>;
@@ -77,7 +78,8 @@ export async function startServer(options?: StartOptions): Promise<ServerHandle>
   const geminiRoutes = createGeminiRoutes(accountPool, cookieJar, proxyPool);
   const responsesRoutes = createResponsesRoutes(accountPool, cookieJar, proxyPool);
   const proxyRoutes = createProxyRoutes(proxyPool, accountPool);
-  const webRoutes = createWebRoutes(accountPool);
+  const usageStats = new UsageStatsStore();
+  const webRoutes = createWebRoutes(accountPool, usageStats);
 
   app.route("/", authRoutes);
   app.route("/", accountRoutes);
@@ -128,7 +130,7 @@ export async function startServer(options?: StartOptions): Promise<ServerHandle>
   startModelRefresh(accountPool, cookieJar, proxyPool);
 
   // Start background quota refresh
-  startQuotaRefresh(accountPool, cookieJar, proxyPool);
+  startQuotaRefresh(accountPool, cookieJar, proxyPool, usageStats);
 
   // Start proxy health check timer (if proxies exist)
   proxyPool.startHealthCheckTimer();

src/routes/__tests__/usage-stats.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Tests for usage stats API routes.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("../../paths.js", () => ({
+  getDataDir: vi.fn(() => "/tmp/test-data"),
+}));
+
+import { Hono } from "hono";
+import { UsageStatsStore, type UsageStatsPersistence, type UsageSnapshot } from "../../auth/usage-stats.js";
+import { createUsageStatsRoutes } from "../admin/usage-stats.js";
+import type { AccountPool } from "../../auth/account-pool.js";
+
+function createMockPool(totals: { input_tokens: number; output_tokens: number; request_count: number }): AccountPool {
+  return {
+    getAllEntries: () => [
+      {
+        id: "e1",
+        status: "active",
+        usage: totals,
+      },
+    ],
+  } as unknown as AccountPool;
+}
+
+function createStore(snapshots: UsageSnapshot[] = []): UsageStatsStore {
+  const persistence: UsageStatsPersistence = {
+    load: () => ({ version: 1, snapshots: [...snapshots] }),
+    save: vi.fn(),
+  };
+  return new UsageStatsStore(persistence);
+}
+
+describe("usage stats routes", () => {
+  describe("GET /admin/usage-stats/summary", () => {
+    it("returns cumulative totals", async () => {
+      const pool = createMockPool({ input_tokens: 5000, output_tokens: 1000, request_count: 20 });
+      const store = createStore();
+      const app = new Hono();
+      app.route("/", createUsageStatsRoutes(pool, store));
+
+      const res = await app.request("/admin/usage-stats/summary");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(body.total_input_tokens).toBe(5000);
+      expect(body.total_output_tokens).toBe(1000);
+      expect(body.total_request_count).toBe(20);
+      expect(body.total_accounts).toBe(1);
+      expect(body.active_accounts).toBe(1);
+    });
+  });
+
+  describe("GET /admin/usage-stats/history", () => {
+    it("returns empty data_points when no history", async () => {
+      const pool = createMockPool({ input_tokens: 0, output_tokens: 0, request_count: 0 });
+      const store = createStore();
+      const app = new Hono();
+      app.route("/", createUsageStatsRoutes(pool, store));
+
+      const res = await app.request("/admin/usage-stats/history");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(body.granularity).toBe("hourly");
+      expect(body.data_points).toEqual([]);
+    });
+
+    it("returns delta data points with raw granularity", async () => {
+      const now = Date.now();
+      const snapshots: UsageSnapshot[] = [
+        {
+          timestamp: new Date(now - 3600_000).toISOString(),
+          totals: { input_tokens: 100, output_tokens: 10, request_count: 1, active_accounts: 1 },
+        },
+        {
+          timestamp: new Date(now).toISOString(),
+          totals: { input_tokens: 500, output_tokens: 50, request_count: 5, active_accounts: 1 },
+        },
+      ];
+
+      const pool = createMockPool({ input_tokens: 500, output_tokens: 50, request_count: 5 });
+      const store = createStore(snapshots);
+      const app = new Hono();
+      app.route("/", createUsageStatsRoutes(pool, store));
+
+      const res = await app.request("/admin/usage-stats/history?granularity=raw&hours=2");
+      expect(res.status).toBe(200);
+
+      const body = await res.json();
+      expect(body.granularity).toBe("raw");
+      expect(body.data_points).toHaveLength(1);
+      expect(body.data_points[0].input_tokens).toBe(400);
+    });
+
+    it("rejects invalid granularity", async () => {
+      const pool = createMockPool({ input_tokens: 0, output_tokens: 0, request_count: 0 });
+      const store = createStore();
+      const app = new Hono();
+      app.route("/", createUsageStatsRoutes(pool, store));
+
+      const res = await app.request("/admin/usage-stats/history?granularity=yearly");
+      expect(res.status).toBe(400);
+    });
+  });
+});

src/routes/admin/usage-stats.ts

@@ -0,0 +1,42 @@
+/**
+ * Usage stats API routes.
+ *
+ * GET /admin/usage-stats/summary  — current cumulative totals
+ * GET /admin/usage-stats/history  — time-series delta data points
+ */
+
+import { Hono } from "hono";
+import type { AccountPool } from "../../auth/account-pool.js";
+import type { UsageStatsStore } from "../../auth/usage-stats.js";
+
+export function createUsageStatsRoutes(
+  pool: AccountPool,
+  statsStore: UsageStatsStore,
+): Hono {
+  const app = new Hono();
+
+  app.get("/admin/usage-stats/summary", (c) => {
+    return c.json(statsStore.getSummary(pool));
+  });
+
+  app.get("/admin/usage-stats/history", (c) => {
+    const granularity = c.req.query("granularity") ?? "hourly";
+    if (granularity !== "raw" && granularity !== "hourly" && granularity !== "daily") {
+      c.status(400);
+      return c.json({ error: "Invalid granularity. Must be raw, hourly, or daily." });
+    }
+
+    const hoursStr = c.req.query("hours") ?? "24";
+    const hours = Math.min(Math.max(1, parseInt(hoursStr, 10) || 24), 168);
+
+    const data_points = statsStore.getHistory(hours, granularity);
+
+    return c.json({
+      granularity,
+      hours,
+      data_points,
+    });
+  });
+
+  return app;
+}

src/routes/web.ts

@@ -8,8 +8,10 @@ import { createHealthRoutes } from "./admin/health.js";
 import { createUpdateRoutes } from "./admin/update.js";
 import { createConnectionRoutes } from "./admin/connection.js";
 import { createSettingsRoutes } from "./admin/settings.js";
+import { createUsageStatsRoutes } from "./admin/usage-stats.js";
+import type { UsageStatsStore } from "../auth/usage-stats.js";
 
-export function createWebRoutes(accountPool: AccountPool): Hono {
+export function createWebRoutes(accountPool: AccountPool, usageStats: UsageStatsStore): Hono {
   const app = new Hono();
 
   const publicDir = getPublicDir();
@@ -68,6 +70,7 @@ export function createWebRoutes(accountPool: AccountPool): Hono {
   app.route("/", createUpdateRoutes());
   app.route("/", createConnectionRoutes(accountPool));
   app.route("/", createSettingsRoutes());
+  app.route("/", createUsageStatsRoutes(accountPool, usageStats));
 
   return app;
 }

web/src/App.tsx

@@ -16,6 +16,7 @@ import { TestConnection } from "./components/TestConnection";
 import { Footer } from "./components/Footer";
 import { ProxySettings } from "./pages/ProxySettings";
 import { AccountManagement } from "./pages/AccountManagement";
+import { UsageStats } from "./pages/UsageStats";
 import { useAccounts } from "../../shared/hooks/use-accounts";
 import { useProxies } from "../../shared/hooks/use-proxies";
 import { useStatus } from "../../shared/hooks/use-status";
@@ -185,15 +186,22 @@ function useHash(): string {
   return hash;
 }
 
+function PageRouter({ hash }: { hash: string }) {
+  switch (hash) {
+    case "#/proxy-settings": return <ProxySettingsPage />;
+    case "#/account-management": return <AccountManagement />;
+    case "#/usage-stats": return <UsageStats />;
+    default: return <Dashboard />;
+  }
+}
+
 export function App() {
   const hash = useHash();
-  const isProxySettings = hash === "#/proxy-settings";
-  const isAccountManagement = hash === "#/account-management";
 
   return (
     <I18nProvider>
       <ThemeProvider>
-        {isProxySettings ? <ProxySettingsPage /> : isAccountManagement ? <AccountManagement /> : <Dashboard />}
+        <PageRouter hash={hash} />
       </ThemeProvider>
     </I18nProvider>
   );

web/src/components/AccountList.tsx

@@ -76,6 +76,12 @@ export function AccountList({ accounts, loading, onDelete, onRefresh, refreshing
           >
             {t("manageAccounts")} →
           </a>
+          <a
+            href="#/usage-stats"
+            class="text-[0.75rem] text-primary hover:text-primary/80 font-medium transition-colors"
+          >
+            {t("usageStats")} &rarr;
+          </a>
           {onExport && onImport && (
             <AccountImportExport onExport={onExport} onImport={onImport} selectedIds={selectedIds} />
           )}

web/src/components/UsageChart.tsx

@@ -0,0 +1,221 @@
+/**
+ * Pure SVG line chart for token usage trends.
+ * No external chart library — renders <polyline> with axis labels.
+ */
+
+import { useMemo } from "preact/hooks";
+import type { UsageDataPoint } from "../../../shared/hooks/use-usage-stats";
+
+interface UsageChartProps {
+  data: UsageDataPoint[];
+  height?: number;
+}
+
+const PADDING = { top: 20, right: 20, bottom: 40, left: 65 };
+
+export function formatNumber(n: number): string {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + "K";
+  return String(n);
+}
+
+function formatTime(iso: string): string {
+  const d = new Date(iso);
+  return `${String(d.getMonth() + 1).padStart(2, "0")}/${String(d.getDate()).padStart(2, "0")} ${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+}
+
+export function UsageChart({ data, height = 260 }: UsageChartProps) {
+  const width = 720; // SVG viewBox width, responsive via CSS
+
+  const reqHeight = Math.round(height * 0.6);
+
+  const { inputPoints, outputPoints, requestPoints, xLabels, yTokenLabels, yReqLabels } = useMemo(() => {
+    if (data.length === 0) {
+      return { inputPoints: "", outputPoints: "", requestPoints: "", xLabels: [], yTokenLabels: [], yReqLabels: [] };
+    }
+
+    const chartW = width - PADDING.left - PADDING.right;
+    const chartH = height - PADDING.top - PADDING.bottom;
+    const reqChartH = reqHeight - PADDING.top - PADDING.bottom;
+
+    const maxInput = Math.max(...data.map((d) => d.input_tokens));
+    const maxOutput = Math.max(...data.map((d) => d.output_tokens));
+    const yMaxT = Math.max(maxInput, maxOutput, 1);
+    const yMaxR = Math.max(...data.map((d) => d.request_count), 1);
+
+    const toX = (i: number) => PADDING.left + (i / Math.max(data.length - 1, 1)) * chartW;
+    const toYTokens = (v: number) => PADDING.top + chartH - (v / yMaxT) * chartH;
+    const toYReqs = (v: number) => PADDING.top + reqChartH - (v / yMaxR) * reqChartH;
+
+    const inp = data.map((d, i) => `${toX(i)},${toYTokens(d.input_tokens)}`).join(" ");
+    const out = data.map((d, i) => `${toX(i)},${toYTokens(d.output_tokens)}`).join(" ");
+    const req = data.map((d, i) => `${toX(i)},${toYReqs(d.request_count)}`).join(" ");
+
+    // X axis labels (up to 6)
+    const step = Math.max(1, Math.floor(data.length / 5));
+    const xl = [];
+    for (let i = 0; i < data.length; i += step) {
+      xl.push({ x: toX(i), label: formatTime(data[i].timestamp) });
+    }
+
+    // Y axis labels (5 ticks)
+    const yTL = [];
+    const yRL = [];
+    for (let i = 0; i <= 4; i++) {
+      const frac = i / 4;
+      yTL.push({ y: PADDING.top + chartH - frac * chartH, label: formatNumber(Math.round(yMaxT * frac)) });
+      yRL.push({ y: PADDING.top + reqChartH - frac * reqChartH, label: formatNumber(Math.round(yMaxR * frac)) });
+    }
+
+    return { inputPoints: inp, outputPoints: out, requestPoints: req, xLabels: xl, yTokenLabels: yTL, yReqLabels: yRL };
+  }, [data, height, reqHeight]);
+
+  if (data.length === 0) {
+    return (
+      <div class="text-center py-12 text-slate-400 dark:text-text-dim text-sm">
+        No usage data yet
+      </div>
+    );
+  }
+
+  return (
+    <div class="space-y-6">
+      {/* Token chart */}
+      <div>
+        <div class="flex items-center gap-4 mb-2 text-xs text-slate-500 dark:text-text-dim">
+          <span class="flex items-center gap-1">
+            <span class="inline-block w-3 h-0.5 bg-blue-500 rounded" /> Input Tokens
+          </span>
+          <span class="flex items-center gap-1">
+            <span class="inline-block w-3 h-0.5 bg-emerald-500 rounded" /> Output Tokens
+          </span>
+        </div>
+        <svg
+          viewBox={`0 0 ${width} ${height}`}
+          class="w-full"
+          style={{ maxHeight: `${height}px` }}
+        >
+          {/* Grid lines */}
+          {yTokenLabels.map((tick) => (
+            <line
+              key={`grid-${tick.y}`}
+              x1={PADDING.left}
+              y1={tick.y}
+              x2={width - PADDING.right}
+              y2={tick.y}
+              stroke="currentColor"
+              class="text-gray-200 dark:text-border-dark"
+              stroke-width="0.5"
+            />
+          ))}
+
+          {/* Y axis labels */}
+          {yTokenLabels.map((tick) => (
+            <text
+              key={`yl-${tick.y}`}
+              x={PADDING.left - 8}
+              y={tick.y + 3}
+              text-anchor="end"
+              class="fill-slate-400 dark:fill-text-dim"
+              font-size="10"
+            >
+              {tick.label}
+            </text>
+          ))}
+
+          {/* X axis labels */}
+          {xLabels.map((tick) => (
+            <text
+              key={`xl-${tick.x}`}
+              x={tick.x}
+              y={height - 8}
+              text-anchor="middle"
+              class="fill-slate-400 dark:fill-text-dim"
+              font-size="9"
+            >
+              {tick.label}
+            </text>
+          ))}
+
+          {/* Lines */}
+          <polyline
+            points={inputPoints}
+            fill="none"
+            stroke="#3b82f6"
+            stroke-width="2"
+            stroke-linejoin="round"
+          />
+          <polyline
+            points={outputPoints}
+            fill="none"
+            stroke="#10b981"
+            stroke-width="2"
+            stroke-linejoin="round"
+          />
+        </svg>
+      </div>
+
+      {/* Request count chart */}
+      <div>
+        <div class="flex items-center gap-4 mb-2 text-xs text-slate-500 dark:text-text-dim">
+          <span class="flex items-center gap-1">
+            <span class="inline-block w-3 h-0.5 bg-amber-500 rounded" /> Requests
+          </span>
+        </div>
+        <svg
+          viewBox={`0 0 ${width} ${reqHeight}`}
+          class="w-full"
+          style={{ maxHeight: `${reqHeight}px` }}
+        >
+          {/* Grid lines */}
+          {yReqLabels.map((tick) => (
+            <line
+              key={`rgrid-${tick.y}`}
+              x1={PADDING.left}
+              y1={tick.y}
+              x2={width - PADDING.right}
+              y2={tick.y}
+              stroke="currentColor"
+              class="text-gray-200 dark:text-border-dark"
+              stroke-width="0.5"
+            />
+          ))}
+
+          {yReqLabels.map((tick) => (
+            <text
+              key={`ryl-${tick.y}`}
+              x={PADDING.left - 8}
+              y={tick.y + 3}
+              text-anchor="end"
+              class="fill-slate-400 dark:fill-text-dim"
+              font-size="10"
+            >
+              {tick.label}
+            </text>
+          ))}
+
+          {xLabels.map((tick) => (
+            <text
+              key={`rxl-${tick.x}`}
+              x={tick.x}
+              y={reqHeight - 8}
+              text-anchor="middle"
+              class="fill-slate-400 dark:fill-text-dim"
+              font-size="9"
+            >
+              {tick.label}
+            </text>
+          ))}
+
+          <polyline
+            points={requestPoints}
+            fill="none"
+            stroke="#f59e0b"
+            stroke-width="2"
+            stroke-linejoin="round"
+          />
+        </svg>
+      </div>
+    </div>
+  );
+}

web/src/pages/UsageStats.tsx

@@ -0,0 +1,114 @@
+import { useState } from "preact/hooks";
+import { useT } from "../../../shared/i18n/context";
+import { useUsageSummary, useUsageHistory, type Granularity } from "../../../shared/hooks/use-usage-stats";
+import { UsageChart, formatNumber } from "../components/UsageChart";
+import type { TranslationKey } from "../../../shared/i18n/translations";
+
+const granularityOptions: Array<{ value: Granularity; label: TranslationKey }> = [
+  { value: "hourly", label: "granularityHourly" },
+  { value: "daily", label: "granularityDaily" },
+];
+
+const rangeOptions: Array<{ hours: number; label: TranslationKey }> = [
+  { hours: 24, label: "last24h" },
+  { hours: 72, label: "last3d" },
+  { hours: 168, label: "last7d" },
+];
+
+export function UsageStats() {
+  const t = useT();
+  const { summary, loading: summaryLoading } = useUsageSummary();
+  const [granularity, setGranularity] = useState<Granularity>("hourly");
+  const [hours, setHours] = useState(24);
+  const { dataPoints, loading: historyLoading } = useUsageHistory(granularity, hours);
+
+  return (
+    <div class="min-h-screen bg-slate-50 dark:bg-bg-dark flex flex-col">
+      {/* Header */}
+      <header class="sticky top-0 z-50 bg-white dark:bg-card-dark border-b border-gray-200 dark:border-border-dark px-4 py-3">
+        <div class="max-w-[1100px] mx-auto flex items-center gap-3">
+          <a
+            href="#/"
+            class="text-sm text-slate-500 dark:text-text-dim hover:text-primary transition-colors"
+          >
+            &larr; {t("backToDashboard")}
+          </a>
+          <h1 class="text-base font-semibold text-slate-800 dark:text-text-main">
+            {t("usageStats")}
+          </h1>
+        </div>
+      </header>
+
+      <main class="flex-grow px-4 md:px-8 py-6 max-w-[1100px] mx-auto w-full">
+        {/* Summary cards */}
+        <div class="grid grid-cols-2 md:grid-cols-4 gap-3 mb-6">
+          <SummaryCard
+            label={t("totalInputTokens")}
+            value={summaryLoading ? "—" : formatNumber(summary?.total_input_tokens ?? 0)}
+          />
+          <SummaryCard
+            label={t("totalOutputTokens")}
+            value={summaryLoading ? "—" : formatNumber(summary?.total_output_tokens ?? 0)}
+          />
+          <SummaryCard
+            label={t("totalRequestCount")}
+            value={summaryLoading ? "—" : formatNumber(summary?.total_request_count ?? 0)}
+          />
+          <SummaryCard
+            label={t("activeAccounts")}
+            value={summaryLoading ? "—" : `${summary?.active_accounts ?? 0} / ${summary?.total_accounts ?? 0}`}
+          />
+        </div>
+
+        {/* Controls */}
+        <div class="flex flex-wrap gap-2 mb-4">
+          {granularityOptions.map(({ value, label }) => (
+            <button
+              key={value}
+              onClick={() => setGranularity(value)}
+              class={`px-3 py-1 text-xs font-medium rounded-full border transition-colors ${
+                granularity === value
+                  ? "bg-primary text-white border-primary"
+                  : "bg-white dark:bg-card-dark border-gray-200 dark:border-border-dark text-slate-600 dark:text-text-dim hover:border-primary/50"
+              }`}
+            >
+              {t(label)}
+            </button>
+          ))}
+          <div class="w-px h-5 bg-gray-200 dark:bg-border-dark self-center" />
+          {rangeOptions.map(({ hours: h, label }) => (
+            <button
+              key={h}
+              onClick={() => setHours(h)}
+              class={`px-3 py-1 text-xs font-medium rounded-full border transition-colors ${
+                hours === h
+                  ? "bg-primary text-white border-primary"
+                  : "bg-white dark:bg-card-dark border-gray-200 dark:border-border-dark text-slate-600 dark:text-text-dim hover:border-primary/50"
+              }`}
+            >
+              {t(label)}
+            </button>
+          ))}
+        </div>
+
+        {/* Chart */}
+        <div class="bg-white dark:bg-card-dark rounded-xl border border-gray-200 dark:border-border-dark p-4">
+          {historyLoading ? (
+            <div class="text-center py-12 text-slate-400 dark:text-text-dim text-sm">Loading...</div>
+          ) : (
+            <UsageChart data={dataPoints} />
+          )}
+        </div>
+      </main>
+    </div>
+  );
+}
+
+function SummaryCard({ label, value }: { label: string; value: string }) {
+  return (
+    <div class="bg-white dark:bg-card-dark rounded-xl border border-gray-200 dark:border-border-dark p-4">
+      <div class="text-xs text-slate-500 dark:text-text-dim mb-1">{label}</div>
+      <div class="text-lg font-semibold text-slate-800 dark:text-text-main">{value}</div>
+    </div>
+  );
+}