Claude Code Token Usage Logs

Where Token Usage Appears

Claude Code and Agent SDK workflows can expose token usage in several places: structured CLI output, SDK result messages, monitoring events, and local transcript records. The local JSONL transcript is useful because assistant message records often carry usage fields near the turn that produced them.

Do not assume every transcript line has usage. In real local samples checked for this build, usage appeared on assistant message records, while user messages, metadata, attachments, and queue records had different shapes. A parser should aggregate only numeric usage fields it actually finds.

Fields To Separate

A useful token review separates base input tokens, cache creation input tokens, cache read input tokens, and output tokens. It should also preserve model, timestamp, request ID, session ID, line number, and any unknown usage keys so later reviewers can trace the estimate back to raw evidence.

Cache fields matter because pricing differs by category. A session with heavy cache reads can look huge by raw token count while costing less than the same number of uncached input tokens. A session with repeated cache writes can have the opposite profile.

• Base input tokens: prompt and context charged at the model input rate.
• Cache creation tokens: context written into prompt cache, often priced above base input.
• Cache read tokens: cached context retrieved, priced below base input.
• Output tokens: model response tokens, usually the highest per-token category.

Estimate, Not Invoice

Use transcript-derived cost estimates for engineering questions: did a run loop, which turn was expensive, did cache behavior dominate, and did the session produce a useful result? Do not use local estimates to bill customers, charge departments, or make irreversible financial decisions.

Pricing can also vary by model release, provider, region, prompt caching duration, batch processing, data residency, and product plan. Record the pricing table date beside any exported analysis.

A Practical Review Workflow

Start with the free Claude Code token usage analyzer to find total tokens, estimated cost, and top expensive turns. Then open the raw transcript or session log viewer for those line numbers. Finally, compare the result with the work outcome, repository diff, CI output, and official billing portal if money is the decision point.

For dashboard-level monitoring, aggregate the same categories into OpenTelemetry metrics and logs. For one-off review, a local transcript plus an exported CSV is usually enough.