Verified against first-party measurements, Claude Code 2.1.288 to 2.1.292 · Updated
First-party Claude usage research
Claude usage research at ClaudeUsage.dev consists of first-party engineering measurements of Claude Code telemetry, promotional rate limits, model-usage accounting, and what a real Claude Code task costs. We conduct controlled tests across cloud and local sessions to verify what underlying APIs report, isolate differences between session ledgers and local transcripts, and document exact experimental conditions alongside strict technical limitations.
About this research
This page contains the actual experiments, conditions, measurements, and limitations behind ClaudeUsage.dev's first-party findings. Each study ends with a link to the practical guide that applies its findings to a specific Claude usage question.
Research at a glance
Summary of active first-party telemetry studies, core questions, primary observations, and evidence scope.
| Study | Core Question | Key Finding | Evidence Scope |
|---|---|---|---|
Study 1 Jump to details ↓ | Do cloud sessions under active promotional credits consume reported 5-hour or 7-day plan limits? | Under active promotional Cloud Session Credits, Claude Code reported rateLimitType as ccr_promotional with 5-hour and 7-day plan utilization remaining at 0 across four observed checkpoints. | Single 22-min Opus 5.5 cloud session; direct observation during active promotional period. |
Study 2 Jump to details ↓ | Why can Claude Code's model-usage and cost accounting diverge from a total reconstructed from the local JSONL transcript? | A transcript-reconstructed cost came in 5.65% below Claude Code's own total in a controlled 3-turn session; Claude Code counted WebSearch-associated Haiku 4.5 calls and post-turn Opus requests absent from the main transcript. | Mechanism observed across two cloud sessions for WebSearch; exact 5.65% discrepancy belongs to primary 3-turn session. |
Study 3 Jump to details ↓ | What internal data structures populate statusline fields, and how does statusline execution behave in headless cloud sessions? | Statusline cost uses Claude Code's cumulative list-price ledger (3.9% higher than transcript-derived cost in this session); context measures latest response against resolved window; a configured statusline did not execute in the tested headless cloud session. | Claude Code 2.1.289; 4 measured turns combined with shipped-code inspection and Anthropic documentation. |
Study 4 Read the study → | How much do model choice, effort level and a long cached context change the API-equivalent cost of the same Claude Code build task? | Sonnet 5.5 High's median task cost was about 0.21x Opus 5.5 High's ($0.0925 vs $0.4456). Running the Opus task after ~205k tokens of cached context raised its median to $1.5157, about 3.4x; irrelevant Vim docs did much the same. | 22 runs of one Next.js task, Claude Code 2.1.292, two stages reported separately. API-equivalent cost at list price, not subscription quota. |
Cloud Session Credits and Claude's reported plan usage
When Anthropic granted promotional Cloud Session Credits ($100 for Pro, $250 for Max) for cloud-based Claude Code sessions, users needed to know whether intensive cloud execution consumed their normal 5-hour and 7-day subscription plan quotas while promotional credits remained active.
Exact experimental conditions
claude.ai/code)Control baseline: executed without claude -p, without Agent SDK wrappers, and without background subagent fanout.
Observed telemetry & rate-limit checkpoints
Across four separate rate-limit events during the 22-minute session, Claude Code's runtime telemetry returned consistent rate-limit state:
| Checkpoint (UTC) | rateLimitType | status | 5h Utilization | 7d Utilization | Reported 5h resetsAt (UTC) |
|---|---|---|---|---|---|
| 22:39 | ccr_promotional | allowed | 0 | 0 | 03:30 |
| 22:40 | ccr_promotional | allowed | 0 | 0 | 03:40 |
| 22:51 | ccr_promotional | allowed | 0 | 0 | 03:50 |
| 23:01 | ccr_promotional | allowed | 0 | 0 | 04:00 |
The promotional bucket reset timestamp returned by the backend was 2026-11-05T08:00:00Z, which corresponds exactly to midnight Pacific time immediately following November 4, 2026.
“In our October 3 test while promotional Cloud Session Credits were active, Claude Code identified the active rate-limit bucket as ccr_promotional. Across four rate-limit events during approximately 22 minutes of Opus 5.5 cloud work, its reported five-hour and seven-day utilization fields remained at 0.”
Supporting observation: The reported five-hour reset timestamp moved forward with the clock (from 03:30 to 04:00 UTC) rather than remaining fixed during the observation.
What this evidence does NOT establish
- No universal claim: Does not prove that cloud sessions never consume plan limits in any circumstance or future configuration.
- Post-promotional behavior: Does not establish what quota behavior applies after promotional credits expire on November 5, 2026 at 08:00 UTC.
- Internal formulas: Does not prove Anthropic's internal backend quota calculation or billing formulas.
- Token interpretation: Summed usage tokens (8,348,115) reflect cumulative request contexts dominated by 97.0% prompt cache reads, not 8.35 million net newly generated tokens.
Model work Claude Code counts outside the main local transcript
Users reconstructing Claude Code costs by summing model requests in the local JSONL session transcript (~/.claude/projects/) often notice their numbers come out lower than Claude Code's own reported session totals. We ran a controlled sequence to isolate where and why the numbers diverge.
Controlled sequence parameters
Turn 1: No web calls (baseline reconciliation).
Turn 2: 2 WebFetch calls (testing fetched document token handling).
Turn 3: 2 WebSearch calls (testing side-model query execution).
Turn-by-turn reconciliation & side-model attribution
In this no-web baseline turn, Claude Code's own accounting and the model requests present in the local JSONL transcript reconciled exactly.
Behaved conditionally: one fetch produced a Haiku request of 226 input and 81 output tokens; one ~67 KB documentation fetch returned fetched content without a corresponding Haiku model request.
For two WebSearch calls, Claude Code attributed 24,725 Haiku 4.5 input tokens and 848 output tokens ($0.048965 list value). These calls were absent from the main local JSONL transcript.
Corroborating observation across two independent cloud sessions:
An earlier preserved cloud session showed the same qualitative mechanism across another two WebSearch calls: 21,633 Haiku input tokens and 780 Haiku output tokens. Across the two observed sessions, all four WebSearch calls were accompanied by Claude Haiku 4.5 usage (claude-haiku-4-5-20251001). In addition, Claude Code counted additional post-turn Opus requests absent from the main transcript.
| Accounting Source (3 Turns) | List-Price Valuation (USD) | Observed Discrepancy | Primary Driver |
|---|---|---|---|
| Transcript-derived reconstruction | ~$1.987 | — | Model requests present in main JSONL |
| Claude Code model-usage total | ~$2.106 | +$0.118986 (+5.65%) | Haiku web-tool usage + post-turn Opus requests |
“In this measured session, a cost reconstructed only from model requests present in the local JSONL transcript came in 5.65% below Claude Code's own model-usage total. Claude Code counted additional model work that the main local transcript did not contain.”
WebSearch observation: “In two Claude Code cloud sessions we observed, all four WebSearch calls were accompanied by Claude Haiku 4.5 usage.”
What this evidence does NOT establish
- No universal side-model rule: Does not claim WebSearch always or permanently invokes Haiku 4.5 across all releases.
- Discrepancy variance: Does not claim 5.65% is a universal discrepancy; it reflects this specific 3-turn sequence.
- No fixed token fee: Does not establish a fixed per-search token cost.
- No quota connection: Does not establish any impact on 5-hour or 7-day subscription quota meters; this is strictly an accounting difference between session totals and on-disk transcripts.
- Neutrality toward third-party tools: Does not evaluate or make claims about third-party monitoring utilities.
What Claude Code statusline fields are actually computed from
Claude Code supports a configured statusLine that receives session JSON over standard input. By inspecting Claude Code 2.1.289 shipped code and comparing it with runtime telemetry across four measured turns in an Anthropic cloud session, we verified the underlying computation for each primary field and documented a negative execution result in headless cloud sessions.
Session conditions & verification method
Verification method: Combined runtime telemetry capture with direct analysis of shipped Claude Code 2.1.289 code and current Anthropic documentation.
Verified field sources and mechanics
Cost: cost.total_cost_usd
Uses Claude Code's own cumulative list-price ledger (the same ledger that prints turn-end costs). In our 4-turn session, Claude Code's ledger reached approximately $6.798175 vs. $6.531 reconstructed from model requests in the transcript—a 3.93% ($0.267163) difference from additional Opus model requests counted outside the transcript.
Context: context_window.used_percentage
Calculated from the latest response's context usage against the resolved context-window capacity. The context total includes uncached input, cache reads, and cache writes. In this session, Claude Code resolved a 1,000,000-token window; measured turn finals were ~158k (16%), ~194k (19%), ~238k (24%), and ~289k (29%).
Duration: cost.total_duration_ms
Represents wall-clock elapsed session time in milliseconds, including idle time between user turns. It does not measure active model generation time or tool execution latency.
Refresh Cadence & Debounce
Shipped code inspection and documentation confirm statusline execution refreshes as new assistant messages arrive, debounced by 300 ms, as well as on session state changes and when rate-limit resets_at timestamps pass.
A configured statusLine hook was left active across 29 model requests and one complete turn boundary inside the tested claude.ai/code cloud session. It executed zero times.
“In our claude.ai/code cloud session, a configured statusLine did not execute. This observation is consistent with Claude Code 2.1.289's shipped code placing statusline execution in the terminal UI path while this cloud session ran headlessly.”
“In Claude Code 2.1.289, the statusline cost field uses Claude Code's own cumulative list-price ledger. In our measured Opus 5.5 session, that ledger was approximately 3.9% higher than a reconstruction from model requests present in the main transcript because Claude Code counted additional model work outside that transcript.”
What this evidence does NOT establish
- No cloud generalization: Does not generalize the headless negative execution result to Desktop Code, IDE extensions, local terminal sessions, or other remote architectures.
- Context window sizing: Does not establish that every Opus 5.5 session receives a 1,000,000-token context window.
- Unestablished request purpose: Does not label the additional Opus requests counted outside the transcript as prompt suggestions because their precise internal purpose was not established.
- Version boundary: Validated specifically for Claude Code 2.1.289 and the measured session; does not promise identical payload structures across future releases.
What one Claude Code task cost on Opus, Sonnet, and a long context
We ran the same Next.js build task 22 times in Claude Code 2.1.292 and priced every request at Anthropic's list rates, reconciled to Claude Code's own ledger. In the cache-controlled stage, Sonnet 5.5 High's median task cost was $0.0925 against $0.4456 for Opus 5.5 High, about 0.21×. The same Opus task, run after about 205,000 tokens of cached context, had a median of $1.5157, about 3.4×, and unrelated Vim documentation of the same size did much the same.
All 22 builds passed a 22-check functional assessment, but they weren't identical: every Opus build started the app and tried to check it in a browser and no Sonnet build did, and the two models handled selected issues hidden by a search differently. The full study covers why the costs differed, both stages separately, the long-context control, run-level data and limitations.
Stage 1B task medians, plus the one-time cost of building the long context from scratch. API-equivalent dollars, not subscription quota.
How we run studies
Our research program is rooted in engineering measurement rather than academic peer review. We follow six practical rules to ensure findings are transparent, verifiable, and bounded:
1. Freezing test questions beforehand
We define the exact operational question before executing a session to prevent post-hoc data fitting or cherry-picking convenient outcomes.
2. Preserving exact runtime conditions
Every study records client version, model identifier, thinking effort, authentication type, duration, and feature flags. Observations belong strictly to documented conditions.
3. Distinguishing observation from interpretation
We explicitly separate what was directly captured in runtime telemetry (e.g. utilization fields remaining at 0) from supported technical inferences and stated non-claims.
4. Complete data sanitization
Public research manifests publish aggregate counts and sanitized findings. We never publish raw private transcripts, user credentials, environment identifiers, or proprietary minified code.
5. Recomputing ledgers independently
We independently reconcile transcript model requests against reported session ledgers to identify discrepancies rather than assuming any single logging layer is complete.
6. Honest scope & limitations beside findings
Every finding is published directly alongside an explicit “What this evidence does NOT establish” block to prevent misgeneralizing single-session observations into universal rules.
Evidence and downloadable data
To facilitate independent verification and tooling integration, we maintain a public, machine-readable JSON research manifest containing sanitized conditions, measurements, and findings for all studies:
Includes study metadata, client versions, observed checkpoints, quantitative deltas, and stated boundaries.
All 22 Claude Code cost-study runs: cost by token category, requests, cache measurements, seed costs and both graders' results. Raw transcripts and source diffs are not included.
How to cite this research
When citing ClaudeUsage.dev research in technical articles, documentation, or benchmarking reports, please cite the exact version tested and state the documented limitations beside any quoted figures.
Citation guidelines:
- Always attribute the specific Claude Code version (e.g. 2.1.288, 2.1.289 or 2.1.292) and the model and effort level tested.
- Do not present single-session observations (such as the 5.65% transcript discrepancy) as universal or permanent metrics.
- Link directly to the specific study anchor (
https://www.claudeusage.dev/research/#study-X...) so readers can review experimental conditions.