Skip to content

Commit c17c591

Browse files
feat(adapter): report 1h cache writes in JSON model breakdowns (ccusage#2059)
* feat(adapter): report 1h cache writes in JSON model breakdowns Claude logs split cache writes into `ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens`, and the cost calculation already prices the two tiers separately. Every report path, however, collapsed the split into one `cacheCreationTokens` count before it reached `ModelBreakdown`, so the TTL tier the server picked was invisible even though it changes the bill. `ModelBreakdown` now carries an optional `cache_creation_1h_tokens`, serialized as `cacheCreation1hTokens` only when at least one record reported the split. Records without a `cache_creation` object are billed at the 5-minute rate, so `cacheCreationTokens - cacheCreation1hTokens` is always the 5-minute part and no separate 5m field is needed. Other agents never report a split and keep their existing JSON shape. The field had to be threaded through five hand-written copies of the per-model accumulation (Claude daily, core summaries, monthly/weekly merges, and the two all-agents merges). Those copies now go through `ModelBreakdown::add_usage` and `ModelBreakdown::merge`, so a future field cannot be dropped by one path while the others carry it. Fixes ccusage#2015 Co-authored-by: XixianWasTaken <[email protected]> * test(ccusage): cover unified reports in the 1h cache split test Cubic pointed out that the unified weekly, monthly and session reports build their modelBreakdowns through their own merge paths, which the test did not exercise. Add them to the existing report loop. * test(ccusage): spread the 1h cache split fixture over two days CodeRabbit noted that every fixture record fell on one date, so weekly, monthly and session reports never merged two rows and a merge that dropped cacheCreation1hTokens would still pass. Add records on the next day, keep daily reports on the first day with --until, and assert the summed counts for the merged reports. * test(adapter): cover 1h cache split in cross-agent breakdown merge Per CodeRabbit, aggregates_model_breakdowns_across_agents now checks that a split merged with a breakdown lacking one keeps the sum, and that two breakdowns without a split stay without one. * docs: link the Claude guide from the cache write TTL section CodeRabbit asked for a cross-link from the new section; the Claude Code guide is the source the split comes from. * docs: describe the non-1h cache write remainder accurately CodeRabbit pointed out that cacheCreationTokens minus cacheCreation1hTokens also includes writes from records that reported no TTL split, not only 5-minute writes. Both are billed at the 5-minute rate, which is what the section now says. * docs: say unsplit cache writes are priced at the 5-minute rate CodeRabbit noted that the 5-minute rate for writes without a TTL split is an assumption ccusage makes when it calculates cost, not what the vendor bills; display mode and stored costs never apply it. * docs: list the optional modelBreakdowns keys in the JSON guarantees Programmatic Usage promised that every field is always present, which was already false for missingPricing and storedCost and is now false for cacheCreation1hTokens. Name those keys and the --no-cost exception. --------- Co-authored-by: XixianWasTaken <[email protected]>
1 parent 7e7ac1f commit c17c591

13 files changed

Lines changed: 205 additions & 60 deletions

File tree

‎docs/guide/json-output.md‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,22 @@ In `auto` [cost mode](/guide/cost-modes), an entry's `cost` can add together cos
302302
}
303303
```
304304

305+
## Cache Write TTL Split
306+
307+
[Claude Code](/guide/claude/) records whether each cache write used the 5-minute or the 1-hour cache TTL, and the two tiers are billed at different rates. Each `modelBreakdowns` entry where at least one record reported that split carries `cacheCreation1hTokens`, the part of `cacheCreationTokens` written with the 1-hour TTL; the rest of `cacheCreationTokens` is 5-minute writes plus writes from records that reported no split, which ccusage prices at the 5-minute rate when it calculates cost. Entries whose records never reported a split, including every other agent, omit the key.
308+
309+
```json
310+
{
311+
"modelName": "claude-sonnet-4-20250514",
312+
"inputTokens": 1500,
313+
"outputTokens": 100,
314+
"cacheCreationTokens": 400,
315+
"cacheCreation1hTokens": 300,
316+
"cacheReadTokens": 30,
317+
"cost": 0.008184
318+
}
319+
```
320+
305321
## JSON Structure
306322

307323
### Daily Reports (Standard)
@@ -700,7 +716,7 @@ if (projectData.projects) {
700716

701717
JSON output is designed for programmatic consumption:
702718

703-
- **Consistent structure**: All fields are always present (with 0 or empty values when not applicable)
719+
- **Consistent structure**: Token and cost fields are always present (with 0 or empty values when not applicable), except that `--no-cost` removes cost fields. A few `modelBreakdowns` keys appear only when they apply: [`missingPricing`](#unpriced-models), [`storedCost`](#stored-costs), and [`cacheCreation1hTokens`](#cache-write-ttl-split)
704720
- **Standard types**: Numbers for metrics, strings for identifiers, arrays for lists
705721
- **ISO timestamps**: Standardized date/time formats for reliable parsing
706722
- **Stable schema**: Field names and structures remain consistent across versions

‎rust/adapters/claude/src/daily.rs‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -687,10 +687,7 @@ impl DailyAccumulator {
687687
index
688688
};
689689
let breakdown = &mut self.breakdowns[index];
690-
breakdown.input_tokens += entry.usage.input_tokens;
691-
breakdown.output_tokens += entry.usage.output_tokens;
692-
breakdown.cache_creation_tokens += entry.usage.cache_creation_token_count();
693-
breakdown.cache_read_tokens += entry.usage.cache_read_input_tokens;
690+
breakdown.add_usage(&entry.usage);
694691
breakdown.cost += entry.cost;
695692
if entry.missing_pricing_model.is_some() {
696693
breakdown.missing_pricing = true;

‎rust/adapters/common/src/report.rs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,7 @@ mod tests {
321321
output_tokens: 30,
322322
cache_creation_tokens: 6,
323323
cache_read_tokens: 3,
324+
cache_creation_1h_tokens: None,
324325
extra_total_tokens: 4,
325326
cost: 0.15,
326327
missing_pricing: false,
@@ -332,6 +333,7 @@ mod tests {
332333
output_tokens: 20,
333334
cache_creation_tokens: 4,
334335
cache_read_tokens: 2,
336+
cache_creation_1h_tokens: None,
335337
extra_total_tokens: 3,
336338
cost: 0.10,
337339
missing_pricing: false,

‎rust/adapters/opencode/src/report.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,7 @@ mod tests {
173173
output_tokens: 50,
174174
cache_creation_tokens: 10,
175175
cache_read_tokens: 5,
176+
cache_creation_1h_tokens: None,
176177
extra_total_tokens: 7,
177178
cost: 0.25,
178179
missing_pricing: false,

‎rust/crates/ccusage-adapter-all/src/loader.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1168,6 +1168,7 @@ where
11681168
output_tokens: usage.output_tokens,
11691169
cache_creation_tokens: usage.cache_creation_tokens,
11701170
cache_read_tokens: usage.cached_input_tokens,
1171+
cache_creation_1h_tokens: None,
11711172
extra_total_tokens: 0,
11721173
cost: codex::calculate_codex_model_cost(model, usage, pricing, speed),
11731174
missing_pricing: mode != CostMode::Display

‎rust/crates/ccusage-adapter-all/src/tests.rs‎

Lines changed: 32 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,7 @@ fn all_report_totals_list_unpriced_models_only_when_present() {
379379
output_tokens: 10,
380380
cache_creation_tokens: 0,
381381
cache_read_tokens: 0,
382+
cache_creation_1h_tokens: None,
382383
extra_total_tokens: 0,
383384
cost: 0.0,
384385
missing_pricing: true,
@@ -390,6 +391,7 @@ fn all_report_totals_list_unpriced_models_only_when_present() {
390391
output_tokens: 10,
391392
cache_creation_tokens: 0,
392393
cache_read_tokens: 10,
394+
cache_creation_1h_tokens: None,
393395
extra_total_tokens: 0,
394396
cost: 0.01,
395397
missing_pricing: false,
@@ -2281,15 +2283,22 @@ fn aggregates_model_breakdowns_across_agents() {
22812283
metadata: None,
22822284
metadata_agents: Some(vec!["codex"]),
22832285
agent_breakdowns: None,
2284-
model_breakdowns: vec![ModelBreakdown {
2285-
model_name: "gpt-5".to_string(),
2286-
input_tokens: 10,
2287-
output_tokens: 5,
2288-
cache_creation_tokens: 0,
2289-
cache_read_tokens: 2,
2290-
cost: 0.03,
2291-
..ModelBreakdown::default()
2292-
}],
2286+
model_breakdowns: vec![
2287+
ModelBreakdown {
2288+
model_name: "gpt-5".to_string(),
2289+
input_tokens: 10,
2290+
output_tokens: 5,
2291+
cache_creation_tokens: 0,
2292+
cache_read_tokens: 2,
2293+
cost: 0.03,
2294+
..ModelBreakdown::default()
2295+
},
2296+
ModelBreakdown {
2297+
model_name: "gpt-5-mini".to_string(),
2298+
input_tokens: 1,
2299+
..ModelBreakdown::default()
2300+
},
2301+
],
22932302
},
22942303
AllRow {
22952304
period: "2026-01-02".to_string(),
@@ -2311,6 +2320,7 @@ fn aggregates_model_breakdowns_across_agents() {
23112320
output_tokens: 3,
23122321
cache_creation_tokens: 1,
23132322
cache_read_tokens: 2,
2323+
cache_creation_1h_tokens: Some(1),
23142324
cost: 0.01,
23152325
missing_pricing: true,
23162326
..ModelBreakdown::default()
@@ -2324,6 +2334,11 @@ fn aggregates_model_breakdowns_across_agents() {
23242334
cost: 0.06,
23252335
..ModelBreakdown::default()
23262336
},
2337+
ModelBreakdown {
2338+
model_name: "gpt-5-mini".to_string(),
2339+
input_tokens: 2,
2340+
..ModelBreakdown::default()
2341+
},
23272342
],
23282343
},
23292344
],
@@ -2332,7 +2347,7 @@ fn aggregates_model_breakdowns_across_agents() {
23322347
);
23332348

23342349
assert_eq!(rows.len(), 1);
2335-
assert_eq!(rows[0].model_breakdowns.len(), 2);
2350+
assert_eq!(rows[0].model_breakdowns.len(), 3);
23362351
assert_eq!(
23372352
rows[0].model_breakdowns[0].model_name,
23382353
"claude-sonnet-4-20250514"
@@ -2345,6 +2360,13 @@ fn aggregates_model_breakdowns_across_agents() {
23452360
assert_eq!(rows[0].model_breakdowns[1].cache_read_tokens, 4);
23462361
assert_eq!(rows[0].model_breakdowns[1].cost, 0.04);
23472362
assert!(rows[0].model_breakdowns[1].missing_pricing);
2363+
assert_eq!(
2364+
rows[0].model_breakdowns[1].cache_creation_1h_tokens,
2365+
Some(1)
2366+
);
2367+
assert_eq!(rows[0].model_breakdowns[2].model_name, "gpt-5-mini");
2368+
assert_eq!(rows[0].model_breakdowns[2].input_tokens, 3);
2369+
assert_eq!(rows[0].model_breakdowns[2].cache_creation_1h_tokens, None);
23482370
}
23492371

23502372
#[test]

‎rust/crates/ccusage-adapter-all/src/types.rs‎

Lines changed: 2 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -167,17 +167,7 @@ fn merge_model_breakdowns(
167167
});
168168
i
169169
});
170-
let b = &mut breakdowns[index];
171-
b.input_tokens = b.input_tokens.saturating_add(item.input_tokens);
172-
b.output_tokens = b.output_tokens.saturating_add(item.output_tokens);
173-
b.cache_creation_tokens = b
174-
.cache_creation_tokens
175-
.saturating_add(item.cache_creation_tokens);
176-
b.cache_read_tokens = b.cache_read_tokens.saturating_add(item.cache_read_tokens);
177-
b.extra_total_tokens = b.extra_total_tokens.saturating_add(item.extra_total_tokens);
178-
b.cost += item.cost;
179-
b.missing_pricing |= item.missing_pricing;
180-
b.add_stored_cost(item.stored_cost);
170+
breakdowns[index].merge(&item);
181171
}
182172
breakdowns.sort_by(|a, b| b.cost.total_cmp(&a.cost));
183173
breakdowns
@@ -196,17 +186,7 @@ fn aggregate_model_breakdowns(rows: &[AllRow]) -> Vec<ModelBreakdown> {
196186
});
197187
i
198188
});
199-
let b = &mut breakdowns[index];
200-
b.input_tokens = b.input_tokens.saturating_add(item.input_tokens);
201-
b.output_tokens = b.output_tokens.saturating_add(item.output_tokens);
202-
b.cache_creation_tokens = b
203-
.cache_creation_tokens
204-
.saturating_add(item.cache_creation_tokens);
205-
b.cache_read_tokens = b.cache_read_tokens.saturating_add(item.cache_read_tokens);
206-
b.extra_total_tokens = b.extra_total_tokens.saturating_add(item.extra_total_tokens);
207-
b.cost += item.cost;
208-
b.missing_pricing |= item.missing_pricing;
209-
b.add_stored_cost(item.stored_cost);
189+
breakdowns[index].merge(item);
210190
}
211191
}
212192
breakdowns

‎rust/crates/ccusage-core/src/output.rs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -667,6 +667,7 @@ mod tests {
667667
output_tokens: 50,
668668
cache_creation_tokens: 0,
669669
cache_read_tokens: 0,
670+
cache_creation_1h_tokens: None,
670671
extra_total_tokens: 0,
671672
cost: if missing_pricing { 0.0 } else { 0.25 },
672673
missing_pricing,
@@ -863,6 +864,7 @@ mod tests {
863864
output_tokens: 50,
864865
cache_creation_tokens: 10,
865866
cache_read_tokens: 5,
867+
cache_creation_1h_tokens: None,
866868
extra_total_tokens: 7,
867869
cost: 0.25,
868870
missing_pricing: false,
@@ -900,6 +902,7 @@ mod tests {
900902
output_tokens: 300,
901903
cache_creation_tokens: 50,
902904
cache_read_tokens: 10,
905+
cache_creation_1h_tokens: None,
903906
extra_total_tokens: 0,
904907
cost: 0.3,
905908
missing_pricing: false,
@@ -911,6 +914,7 @@ mod tests {
911914
output_tokens: 267,
912915
cache_creation_tokens: 39,
913916
cache_read_tokens: 0,
917+
cache_creation_1h_tokens: None,
914918
extra_total_tokens: 0,
915919
cost: 0.12,
916920
missing_pricing: false,

‎rust/crates/ccusage-core/src/summary.rs‎

Lines changed: 3 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -78,14 +78,7 @@ impl UsageAccumulator {
7878
index
7979
};
8080
let breakdown = &mut self.breakdowns[index];
81-
breakdown.input_tokens = breakdown.input_tokens.saturating_add(usage.input_tokens);
82-
breakdown.output_tokens = breakdown.output_tokens.saturating_add(usage.output_tokens);
83-
breakdown.cache_creation_tokens = breakdown
84-
.cache_creation_tokens
85-
.saturating_add(usage.cache_creation_token_count());
86-
breakdown.cache_read_tokens = breakdown
87-
.cache_read_tokens
88-
.saturating_add(usage.cache_read_input_tokens);
81+
breakdown.add_usage(&usage);
8982
breakdown.extra_total_tokens = breakdown
9083
.extra_total_tokens
9184
.saturating_add(entry.extra_total_tokens);
@@ -267,21 +260,7 @@ fn aggregate_summaries(rows: &[&UsageSummary]) -> UsageSummary {
267260
});
268261
index
269262
};
270-
let breakdown = &mut summary.model_breakdowns[index];
271-
breakdown.input_tokens = breakdown.input_tokens.saturating_add(item.input_tokens);
272-
breakdown.output_tokens = breakdown.output_tokens.saturating_add(item.output_tokens);
273-
breakdown.cache_creation_tokens = breakdown
274-
.cache_creation_tokens
275-
.saturating_add(item.cache_creation_tokens);
276-
breakdown.cache_read_tokens = breakdown
277-
.cache_read_tokens
278-
.saturating_add(item.cache_read_tokens);
279-
breakdown.extra_total_tokens = breakdown
280-
.extra_total_tokens
281-
.saturating_add(item.extra_total_tokens);
282-
breakdown.cost += item.cost;
283-
breakdown.missing_pricing |= item.missing_pricing;
284-
breakdown.add_stored_cost(item.stored_cost);
263+
summary.model_breakdowns[index].merge(item);
285264
}
286265
}
287266
summary
@@ -705,6 +684,7 @@ mod tests {
705684
output_tokens: 10,
706685
cache_creation_tokens: 1,
707686
cache_read_tokens: 2,
687+
cache_creation_1h_tokens: None,
708688
extra_total_tokens: 3,
709689
cost: fixture.cost,
710690
missing_pricing: false,

‎rust/crates/ccusage-core/src/types.rs‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,11 @@ impl TokenUsageRaw {
4747
self.cache_creation_input_tokens
4848
}
4949
}
50+
51+
/// `None` when the source did not report the cache-write TTL split.
52+
fn cache_creation_1h_token_count(&self) -> Option<u64> {
53+
self.cache_creation.map(|b| b.ephemeral_1h_input_tokens)
54+
}
5055
}
5156

5257
#[derive(Debug, Clone, Copy, Default, Deserialize)]
@@ -103,6 +108,11 @@ pub struct ModelBreakdown {
103108
pub output_tokens: u64,
104109
pub cache_creation_tokens: u64,
105110
pub cache_read_tokens: u64,
111+
/// Part of `cache_creation_tokens` written with the 1-hour cache TTL; the
112+
/// rest was billed at the 5-minute rate. Absent when no entry reported the
113+
/// split.
114+
#[serde(skip_serializing_if = "Option::is_none")]
115+
pub cache_creation_1h_tokens: Option<u64>,
106116
#[serde(skip_serializing)]
107117
pub extra_total_tokens: u64,
108118
pub cost: f64,
@@ -115,6 +125,44 @@ pub struct ModelBreakdown {
115125
}
116126

117127
impl ModelBreakdown {
128+
pub fn add_usage(&mut self, usage: &TokenUsageRaw) {
129+
self.input_tokens = self.input_tokens.saturating_add(usage.input_tokens);
130+
self.output_tokens = self.output_tokens.saturating_add(usage.output_tokens);
131+
self.cache_creation_tokens = self
132+
.cache_creation_tokens
133+
.saturating_add(usage.cache_creation_token_count());
134+
self.cache_read_tokens = self
135+
.cache_read_tokens
136+
.saturating_add(usage.cache_read_input_tokens);
137+
self.add_cache_creation_1h_tokens(usage.cache_creation_1h_token_count());
138+
}
139+
140+
/// Folds another breakdown of the same model into this one.
141+
pub fn merge(&mut self, other: &Self) {
142+
self.input_tokens = self.input_tokens.saturating_add(other.input_tokens);
143+
self.output_tokens = self.output_tokens.saturating_add(other.output_tokens);
144+
self.cache_creation_tokens = self
145+
.cache_creation_tokens
146+
.saturating_add(other.cache_creation_tokens);
147+
self.cache_read_tokens = self
148+
.cache_read_tokens
149+
.saturating_add(other.cache_read_tokens);
150+
self.add_cache_creation_1h_tokens(other.cache_creation_1h_tokens);
151+
self.extra_total_tokens = self
152+
.extra_total_tokens
153+
.saturating_add(other.extra_total_tokens);
154+
self.cost += other.cost;
155+
self.missing_pricing |= other.missing_pricing;
156+
self.add_stored_cost(other.stored_cost);
157+
}
158+
159+
fn add_cache_creation_1h_tokens(&mut self, tokens: Option<u64>) {
160+
if let Some(tokens) = tokens {
161+
let total = self.cache_creation_1h_tokens.get_or_insert(0);
162+
*total = total.saturating_add(tokens);
163+
}
164+
}
165+
118166
pub fn add_stored_cost(&mut self, stored_cost: Option<f64>) {
119167
if let Some(stored_cost) = stored_cost {
120168
*self.stored_cost.get_or_insert(0.0) += stored_cost;

0 commit comments

Comments
 (0)