Cost Attribution Insights -- Usage by Key and Agent

2026-03-20

What We Built

Two new cost attribution endpoints that break down usage spend by API key and by agent. These complement the existing by-model and by-cost-center views, giving teams four dimensions of cost visibility: model, cost center, API key, and agent.

The by-key endpoint joins usage events with API key metadata to show per-key spend with budget utilization percentage. The by-agent endpoint groups usage by agent ID extracted from request metadata and calculates a quality-per-dollar efficiency score using BrainstormRouter's quality scoring system.

Both endpoints are available via JWT auth (dashboard) and API key auth (SDK), following the existing dual-auth pattern established in Phase 033.

Why It Matters

Enterprise teams running multiple agents and services through BrainstormRouter need to know which keys and agents are burning budget. Without per-key attribution, a single runaway agent can exhaust a shared budget before anyone notices. Without per-agent attribution, there is no way to compare agent efficiency -- an agent that costs 10x more but produces equivalent quality is invisible.

These endpoints power the dashboard's cost centers page and enable programmatic budget monitoring via the SDKs.

How It Works

The query layer in src/api/usage-queries.ts adds two new functions:

• getUsageByKey() joins usage_events with api_keys to aggregate cost per key, computing utilizationPct = totalCost / budgetLimit * 100
• getUsageByAgent() groups by metadata->>'agentId' and calculates efficiencyScore = avgQuality / totalCost * 100

Both use the existing execQuery() pattern with explicit tenantId in WHERE clauses (no RLS dependence), getPeriodStart() for time windowing, and the str() helper for safe type coercion.

The route file src/api/routes/auth-usage.ts is a focused Hono sub-app mounted into the main auth router, following the established pattern.

The Numbers

• 2 new query functions with full tenant isolation
• 2 new REST endpoints with period filtering (day/week/month)
• 4 new SDK methods (2 TS, 2 Python sync + async)
• Dashboard API client extended with typed response types
• Budget utilization calculated in real-time from actual spend vs. key budget caps

Competitive Edge

Portkey and OpenRouter provide per-model cost breakdowns but lack per-key and per-agent attribution. BrainstormRouter is the only gateway that combines per-key budget utilization tracking with per-agent efficiency scoring derived from its quality scoring intelligence system. This transforms cost visibility from "which models cost money" to "which teams and agents are getting the best value."

Lockstep Checklist

• [x] API Routes: src/api/routes/auth-usage.ts created, mounted in src/api/routes/auth.ts.
• [x] TS SDK: packages/sdk-ts/src/resources/usage.ts updated with byKey() and byAgent() methods and types.
• [x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/usage.py updated with by_key() and by_agent() on both sync and async classes.
• [x] MCP Schemas: N/A -- these are read-only analytics endpoints, not agent-facing tools.
• [x] Master Record: Cost attribution added to usage analytics capability.