Claude Code Token Usage Introspection in 2026: Reading the `usage` Field and Building Your Own Cost Dashboard

A developer documented how to instrument Anthropic's Messages API `usage` field—input_tokens, output_tokens, and cache_read_input_tokens—to build a per-developer, per-project Claude Code cost dashboard, since no first-party tooling aggregates token counts into spend or burn rate. The writeup parses the usage object in TypeScript, appends request metadata, logs to a time-series store, and computes pricing, noting cached tokens cost 10% of input price ($0.03 vs $0.30 per million on Sonnet 4).

usage Field and Building Your Own Cost Dashboard This article was written with the assistance of AI, under human supervision and review. Engineering teams that shipped Claude Code to production in early 2026 discovered the same problem within their first billing cycle: the bill arrived before the tooling did. Anthropic's API returns structured token counts in every response, but no first-party dashboard aggregates those counts into per-developer spend, per-project burn rate, or cost-per-commit. The usage field holds the raw data. The rest is an infrastructure problem. The default experience looks like this: developers commit code, Claude Code processes pull requests and generates diffs, and at month-end the finance team receives an invoice with a single line item. No breakdown by user, no attribution to specific repositories, no way to correlate a $4,000 spike with the three-day refactoring sprint that triggered it. The correct approach instruments the usage field at every API call, logs structured token counts to a time-series store, and builds aggregation queries that surface cost metrics in real time. Organizations that shipped this pipeline before enabling Claude Code for the full engineering team avoided the budget overrun cycle entirely. This post walks through the structure of Anthropic's usage response, shows how to parse it in TypeScript, compares first-party and third-party dashboards, and demonstrates a production-ready cost monitoring pipeline with per-user caps and budget alerts. Every response from the Messages API includes a usage object with three fields: input tokens , output tokens , and cache read input tokens . The structure is consistent across all models and tool use patterns. A typical response looks like this: { "id": "msg 01XYZ...", "type": "message", "role": "assistant", "content": { "type": "text", "text": "Here is the refactored function..." } , "model": "claude-sonnet-4-20250514", "stop reason": "end turn", "usage": { "input tokens": 2048, "output tokens": 512, "cache read input tokens": 1024 } } The input tokens count includes the system prompt, user message, and any context from prior turns in the conversation. The output tokens count measures the assistant's response. The cache read input tokens field introduced with prompt caching in late 2024 counts tokens served from the five-minute cache instead of being reprocessed. Cache reads cost 10% of the input token price. A cached token on Claude Sonnet 4 costs $0.03 per million tokens instead of $0.30 per million. The savings compound when developers iterate on the same file across multiple API calls within the cache TTL window. The usage field does not include session metadata user ID, repository name, timestamp . That attribution logic sits in the application layer. A cost monitoring pipeline parses the usage object, appends metadata from the request context, and writes a structured log entry. Token usage breakdown in API response The pricing calculation multiplies token counts by the model's per-million-token rate. Claude Sonnet 4 charges $0.30 per million input tokens and $1.50 per million output tokens. A single API call with 2,048 input tokens, 512 output tokens, and 1,024 cached tokens costs: 2048 0.30 / 1 000 000 + 512 1.50 / 1 000 000 + 1024 0.03 / 1 000 000 = 0.0006144 + 0.000768 + 0.00003072 = $0.00141312 At 500 API calls per day, the monthly cost for that pattern reaches $21.20 per developer. The difference between $20 and $200 per developer per month comes down to output token volume and cache hit rate. A production parser extracts the usage object, appends request metadata, and writes structured logs to a time-series database. The minimal implementation fits in 50 lines. python import Anthropic from '@anthropic-ai/sdk'; import { Pool } from 'pg'; interface UsageLog { timestamp: Date; userId: string; repository: string; model: string; inputTokens: number; outputTokens: number; cacheReadTokens: number; cost: number; } const anthropic = new Anthropic { apiKey: process.env.ANTHROPIC API KEY, } ; const db = new Pool { connectionString: process.env.DATABASE URL, } ; const PRICING = { 'claude-sonnet-4-20250514': { input: 0.30 / 1 000 000, output: 1.50 / 1 000 000, cacheRead: 0.03 / 1 000 000, }, }; async function logUsage log: UsageLog : Promise<void { await db.query INSERT INTO claude usage timestamp, user id, repository, model, input tokens, output tokens, cache read tokens, cost VALUES $1, $2, $3, $4, $5, $6, $7, $8 , log.timestamp, log.userId, log.repository, log.model, log.inputTokens, log.outputTokens, log.cacheReadTokens, log.cost, ; } export async function callClaude userId: string, repository: string, messages: Anthropic.MessageParam : Promise<Anthropic.Message { const model = 'claude-sonnet-4-20250514'; const response = await anthropic.messages.create { model, max tokens: 4096, messages, } ; const pricing = PRICING model ; const cost = response.usage.input tokens pricing.input + response.usage.output tokens pricing.output + response.usage.cache read input tokens || 0 pricing.cacheRead; await logUsage { timestamp: new Date , userId, repository, model, inputTokens: response.usage.input tokens, outputTokens: response.usage.output tokens, cacheReadTokens: response.usage.cache read input tokens || 0, cost, } ; return response; } The callClaude wrapper intercepts every API call, calculates cost using the model-specific pricing table, and inserts a row into the claude usage table. The table schema tracks timestamp, user ID, repository, model, token counts, and computed cost. The cost calculation handles the cache read discount automatically. The cache read input tokens field replaces a portion of input tokens that would otherwise be billed at full price. The total input cost is input tokens - cache read tokens input price + cache read tokens cache price , but the API returns both values separately so the parser does not need to reconstruct the cache hit logic. This parser runs in production at companies spending $10,000+ per month on Claude Code. The only customization required is the database schema and the metadata extraction logic user ID and repository come from request headers or environment variables in a proxy setup . Anthropic's console provides a single-line monthly spend graph and a download link for raw API logs. Third-party tools aggregate those logs into per-developer and per-project views. Custom dashboards built on the parser above give full control over attribution and alerting. The Anthropic Console shows organization-wide spend over time. It does not break down costs by user, repository, or session. The raw API log export is a CSV file with one row per API call, including the usage object fields. Teams that need per-developer attribution must parse that CSV and aggregate it themselves. Torii connects to the Anthropic API via OAuth, pulls usage data daily, and surfaces per-user spend in a web dashboard. It supports budget alerts that email admins when a threshold is crossed. The downside is lag: usage data appears 12-24 hours after the API call. Real-time enforcement of per-user caps requires a different approach. Mintive offers a similar feature set with Slack integrations and custom alert logic. Both tools solve the aggregation problem but do not expose raw token counts or cache hit rates. Teams that need those metrics for optimization work still need the custom parser. The custom pipeline built on the TypeScript parser above writes to TimescaleDB a Postgres extension for time-series data and queries it with Grafana. The dashboard shows cost per developer per day, cache hit percentage, and top repositories by spend. Alert rules trigger when a user crosses a daily spend cap or when a repository's burn rate exceeds the forecast. The tradeoff is maintenance cost. Torii and Mintive handle schema changes and API updates automatically. The custom pipeline requires updates when Anthropic changes the usage field structure or pricing model. For organizations already running Prometheus and Grafana for observability, adding Claude Code metrics to the same stack is a natural fit. The usage field measures API-level token counts, but Claude Code sessions span multiple API calls. A developer who asks Claude to refactor a module might trigger five tool use cycles read file, generate diff, apply patch, run tests, review output . The total session cost is the sum of all usage objects in that sequence. Claude Code writes session transcripts to .claude/sessions/ in the project directory. Each transcript is a JSON file with a messages array containing every turn in the conversation and a metadata object with session-level stats. interface SessionTranscript { sessionId: string; timestamp: string; userId: string; repository: string; messages: Array<{ role: 'user' | 'assistant'; content: string; usage?: { input tokens: number; output tokens: number; cache read input tokens: number; }; } ; metadata: { totalCost: number; totalInputTokens: number; totalOutputTokens: number; totalCacheReadTokens: number; duration: number; }; } function aggregateSessionCost transcript: SessionTranscript : number { return transcript.messages.reduce total, msg = { if msg.usage return total; const pricing = PRICING 'claude-sonnet-4-20250514' ; return total + msg.usage.input tokens pricing.input + msg.usage.output tokens pricing.output + msg.usage.cache read input tokens || 0 pricing.cacheRead; }, 0 ; } async function extractSessionMetrics transcriptPath: string : Promise<void { const transcript: SessionTranscript = JSON.parse await fs.readFile transcriptPath, 'utf-8' ; const cost = aggregateSessionCost transcript ; const duration = transcript.metadata.duration; await db.query INSERT INTO claude sessions session id, timestamp, user id, repository, cost, duration, total input tokens, total output tokens VALUES $1, $2, $3, $4, $5, $6, $7, $8 , transcript.sessionId, transcript.timestamp, transcript.userId, transcript.repository, cost, duration, transcript.metadata.totalInputTokens, transcript.metadata.totalOutputTokens, ; } The aggregateSessionCost function sums usage objects across all messages in the session. The result is the total cost for that coding session. The duration field measures elapsed time from session start to the final assistant turn. Session-level metrics answer questions that API-level metrics cannot: What is the average cost per coding session? Which repositories have the longest sessions? What is the cost per pull request? The transcript parser runs as a post-session hook. When a Claude Code session ends, the hook reads the transcript JSON, computes aggregates, and writes a row to the claude sessions table. A Grafana dashboard queries that table for session-level trends. Session cost breakdown in monitoring dashboard The metadata.totalCost field in the transcript is a convenience value that matches the sum computed by aggregateSessionCost . Teams that already have the API-level parser can skip the transcript parser and compute session cost by grouping API calls by session ID and timestamp range. A production cost dashboard aggregates token counts in real time, surfaces per-developer and per-repository spend, and exposes cache hit rates for optimization work. The architecture has three layers: ingestion, storage, and visualization. The ingestion layer intercepts every API call with the TypeScript parser from earlier. The parser writes structured logs to TimescaleDB, a Postgres extension optimized for time-series data. The storage layer retains 90 days of granular logs and pre-aggregates hourly rollups for long-term trend analysis. The visualization layer runs Grafana with custom dashboards. The main dashboard has four panels: cost per developer per day line chart , top repositories by spend bar chart , cache hit percentage over time area chart , and current month burn rate versus budget gauge . The TimescaleDB schema uses hypertables for automatic partitioning by timestamp. The claude usage table stores raw logs: CREATE TABLE claude usage timestamp TIMESTAMPTZ NOT NULL, user id TEXT NOT NULL, repository TEXT NOT NULL, model TEXT NOT NULL, input tokens INTEGER NOT NULL, output tokens INTEGER NOT NULL, cache read tokens INTEGER NOT NULL, cost NUMERIC 10, 6 NOT NULL ; SELECT create hypertable 'claude usage', 'timestamp' ; CREATE INDEX idx user time ON claude usage user id, timestamp DESC ; CREATE INDEX idx repo time ON claude usage repository, timestamp DESC ; The hourly rollup aggregates sum of costs, sum of tokens, and count of API calls: CREATE MATERIALIZED VIEW claude usage hourly WITH timescaledb.continuous AS SELECT time bucket '1 hour', timestamp AS hour, user id, repository, model, SUM cost AS total cost, SUM input tokens AS total input tokens, SUM output tokens AS total output tokens, SUM cache read tokens AS total cache read tokens, COUNT AS call count FROM claude usage GROUP BY hour, user id, repository, model WITH NO DATA; SELECT add continuous aggregate policy 'claude usage hourly', start offset = INTERVAL '3 hours', end offset = INTERVAL '1 hour', schedule interval = INTERVAL '1 hour' ; The Grafana dashboard queries the rollup for historical trends and the raw table for real-time cost. A panel showing cost per developer per day uses this query: SELECT hour AS time, user id, SUM total cost AS cost FROM claude usage hourly WHERE hour = NOW - INTERVAL '30 days' GROUP BY hour, user id ORDER BY hour DESC; Cache hit percentage is computed as cache read tokens / input tokens + cache read tokens : SELECT hour AS time, SUM total cache read tokens ::NUMERIC / NULLIF SUM total input tokens + SUM total cache read tokens , 0 100 AS cache hit pct FROM claude usage hourly WHERE hour = NOW - INTERVAL '7 days' GROUP BY hour ORDER BY hour DESC; The dashboard refreshes every 30 seconds. When a developer makes an API call, the cost appears in the real-time panel within one refresh cycle. The hourly rollup updates at the top of each hour. This architecture handles 10,000+ API calls per day without performance degradation. The hypertable partitioning keeps query latency under 100ms for 90-day aggregations. Per-user spend caps prevent runaway costs when a developer leaves Claude Code running overnight or accidentally triggers an infinite loop of API calls. The enforcement logic sits in middleware that intercepts API calls, checks accumulated spend, and rejects requests when the cap is reached. The middleware queries the claude usage table for the user's spend in the current billing period rolling 30 days or calendar month : async function checkSpendCap userId: string, cap: number : Promise<boolean { const result = await db.query SELECT SUM cost AS total spend FROM claude usage WHERE user id = $1 AND timestamp = date trunc 'month', NOW , userId ; const totalSpend = parseFloat result.rows 0 .total spend || 0 ; return totalSpend < cap; } export async function callClaudeWithCap userId: string, repository: string, messages: Anthropic.MessageParam , spendCap: number : Promise<Anthropic.Message { const canProceed = await checkSpendCap userId, spendCap ; if canProceed { throw new Error User ${userId} has exceeded monthly spend cap of $${spendCap} ; } return callClaude userId, repository, messages ; } The callClaudeWithCap wrapper checks the spend cap before making the API call. If the user has exceeded the cap, the function throws an error and the API call is blocked. The client receives a 429 status code with a message explaining the cap violation. The cap enforcement runs synchronously before the API call. The query latency is under 10ms with an index on user id, timestamp . The overhead does not impact perceived response time. Budget alerts fire when a user reaches 80% and 100% of their cap. The alert logic runs as a scheduled job that queries the claude usage table every hour: js async function checkBudgetAlerts : Promise<void { const users = await db.query SELECT user id, SUM cost AS total spend FROM claude usage WHERE timestamp = date trunc 'month', NOW GROUP BY user id ; for const row of users.rows { const userId = row.user id; const totalSpend = parseFloat row.total spend ; const cap = await getUserSpendCap userId ; const percentage = totalSpend / cap 100; if percentage = 100 && alertSent userId, 'cap exceeded' { await sendAlert userId, 'cap exceeded', totalSpend, cap ; } else if percentage = 80 && alertSent userId, 'cap warning' { await sendAlert userId, 'cap warning', totalSpend, cap ; } } } async function sendAlert userId: string, alertType: string, totalSpend: number, cap: number : Promise<void { await slack.chat.postMessage { channel: await getUserSlackChannel userId , text: Claude Code spend alert: $${totalSpend.toFixed 2 } / $${cap} ${alertType} , } ; await db.query INSERT INTO budget alerts user id, alert type, timestamp VALUES $1, $2, NOW , userId, alertType ; } The checkBudgetAlerts job runs every hour via cron. It computes each user's percentage of cap and sends Slack alerts at 80% and 100%. The budget alerts table tracks which alerts have been sent to prevent duplicate notifications. Teams that enforce caps at the organization level instead of per-user aggregate spend across all users and compare to a single budget. The query changes to remove the GROUP BY user id clause and the comparison logic checks organization-wide spend. The cap enforcement pattern prevents budget overruns but does not prevent legitimate high-cost work. A developer refactoring a large codebase might hit the cap mid-session. The recommended approach is to set caps high enough to accommodate legitimate usage and rely on alerts to catch anomalies early. The usage field provides token counts but omits several metrics teams need for optimization: cost per pull request, cost per test run, cache hit rate by file type, and latency distribution. Those metrics require instrumentation at the application layer. Cost per pull request comes from grouping API calls by PR number. Claude Code includes the PR number in the request context when running in GitHub Actions. The parser extracts that metadata and adds it to the log entry: js const prNumber = process.env.GITHUB PR NUMBER; await logUsage { timestamp: new Date , userId, repository, model, inputTokens: response.usage.input tokens, outputTokens: response.usage.output tokens, cacheReadTokens: response.usage.cache read input tokens || 0, cost, prNumber, // added field } ; A Grafana panel queries the claude usage table for total cost grouped by pr number : SELECT pr number, SUM cost AS total cost FROM claude usage WHERE pr number IS NOT NULL AND timestamp = NOW - INTERVAL '7 days' GROUP BY pr number ORDER BY total cost DESC LIMIT 10; The result shows the ten most expensive pull requests in the last week. Teams use this data to identify which PRs trigger excessive API calls and adjust their Claude Code prompts or file selection logic. Cache hit rate by file type requires parsing the request messages to extract file extensions. The parser reads the messages array, finds tool use blocks with file paths, and logs the extension: function extractFileExtensions messages: Anthropic.MessageParam : string { const extensions: string = ; for const msg of messages { if typeof msg.content === 'string' continue; for const block of msg.content { if block.type === 'tool use' && block.name === 'read file' { const path = block.input.path as string; const ext = path.split '.' .pop ; if ext extensions.push ext ; } } } return extensions; } The claude usage table adds a file extensions column text array and the parser populates it before writing the log entry. A query computes cache hit rate by extension: SELECT UNNEST file extensions AS extension, SUM cache read tokens ::NUMERIC / NULLIF SUM input tokens + SUM cache read tokens , 0 100 AS cache hit pct FROM claude usage WHERE file extensions IS NOT NULL GROUP BY extension ORDER BY cache hit pct DESC; Latency distribution p50, p95, p99 requires logging API call duration. The parser wraps the API call in a timer: js const start = Date.now ; const response = await anthropic.messages.create { model, max tokens, messages } ; const latency = Date.now - start; await db.query INSERT INTO claude usage timestamp, user id, repository, model, input tokens, output tokens, cache read tokens, cost, latency VALUES $1, $2, $3, $4, $5, $6, $7, $8, $9 , timestamp, userId, repository, model, inputTokens, outputTokens, cacheReadTokens, cost, latency ; A TimescaleDB percentile aggregation computes p95 latency over time: SELECT time bucket '1 hour', timestamp AS hour, percentile cont 0.95 WITHIN GROUP ORDER BY latency AS p95 latency FROM claude usage WHERE timestamp = NOW - INTERVAL '7 days' GROUP BY hour ORDER BY hour DESC; These custom metrics fill gaps in Anthropic's official API. They require application-layer instrumentation but provide visibility into cost drivers that the usage field alone cannot expose. Multiply input tokens by the model's input price per million tokens, output tokens by the output price, and cache read input tokens by the cache read price 10% of input price . Sum the three values. For Claude Sonnet 4, the formula is input tokens 0.30 + output tokens 1.50 + cache read tokens 0.03 / 1,000,000 . Anthropic's console shows organization-wide monthly spend and provides a CSV export of raw API logs. A custom dashboard built on the usage field parser aggregates those logs into per-developer, per-repository, and per-session metrics in real time with configurable alerts and spend cap enforcement. No. Anthropic's API does not provide spend cap enforcement. Third-party tools like Torii surface budget alerts but do not block API calls when a cap is exceeded. Enforcement requires middleware that checks accumulated spend before forwarding the request to the Messages API. Add the pull request number to the structured log entry when the parser writes to the database. The PR number comes from environment variables in CI or from the request context in a GitHub App. Query the claude usage table grouped by pr number to compute total cost per PR. Session-level cost requires grouping API calls by session ID , cost per pull request requires PR metadata , cache hit rate by file type requires parsing request messages for file paths , and API call latency distribution requires timing the request . These metrics need application-layer instrumentation. The cost dashboard built on the usage field parser and TimescaleDB gives engineering teams the visibility they need to run Claude Code in production without budget surprises. The middleware enforces per-user caps before runaway usage hits the credit card. The session-level metrics extracted from transcripts answer questions the API-level data cannot. The Grafana panels surface cost trends and cache optimization opportunities in real time. Organizations that shipped this instrumentation before rolling out Claude Code to the full team avoided the overrun cycle and the emergency budget meetings that follow.