cache-efficiency

1# Cache Efficiency
2 
3Diagnose whether prompt caching is actually saving money, and where it is not.
4 
5## Input
6 
7The user provides: **$ARGUMENTS**
8 
9This may be: empty (analyze the whole fleet), "today" / "this week" / a date range, a session ID to scope the analysis, or a target like "hit rate > 80%". When empty, analyze all data from `/api/analytics`.
10 
11## Data Sources
12 
13| Endpoint | Returns |
14|----------|---------|
15| `GET /api/analytics` | `tokens.total_input`, `tokens.total_output`, `tokens.total_cache_read`, `tokens.total_cache_write` (baselines pre-summed), plus `daily_sessions` |
16| `GET /api/sessions?limit=200` | Session list — each has model, cwd, started_at, ended_at, inline `cost`, metadata (JSON: usage_extras with cache token detail) |
17| `GET /api/sessions/{id}` | Full session detail with nested agents and events, for drill-down on a flagged session |
18| `GET /api/pricing/cost` | `{ total_cost, breakdown: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] }` — used to price cache read vs write spend |
19 
20### How cache economics work
21 
22```
23cache_hit_rate   = total_cache_read / (total_cache_read + total_input)
24cache_reuse      = total_cache_read / total_cache_write
25cache_read_cost  = (cache_read_tokens  / 1M) × cache_read_per_mtok
26cache_write_cost = (cache_write_tokens / 1M) × cache_write_per_mtok
27```
28…