Add observed cache TTL metrics and dashboard coverage

docs/metrics.md

@@ -53,6 +53,41 @@ for backward compatibility. The new `persistent_savings` block is durable local
 proxy compression history stored by default at `~/.headroom/proxy_savings.json`.
 Use `HEADROOM_SAVINGS_PATH` to override the file location.
 
+For Anthropic-style providers that return cache-write TTL buckets, `/stats`
+also surfaces observed cache TTL usage under `prefix_cache`:
+
+```json
+{
+  "prefix_cache": {
+    "by_provider": {
+      "anthropic": {
+        "observed_ttl_buckets": {
+          "5m": {"tokens": 20000, "requests": 8},
+          "1h": {"tokens": 50000, "requests": 12}
+        },
+        "observed_ttl_mix": {
+          "5m_pct": 28.6,
+          "1h_pct": 71.4,
+          "active_buckets": ["5m", "1h"]
+        }
+      }
+    },
+    "totals": {
+      "observed_ttl_buckets": {
+        "5m": {"tokens": 20000, "requests": 8},
+        "1h": {"tokens": 50000, "requests": 12}
+      }
+    }
+  }
+}
+```
+
+These fields are observational only:
+
+- they reflect provider-reported cache write buckets
+- they do not configure TTL
+- they do not represent remaining expiration time
+
 ### Historical Savings Endpoint
 
 ```bash

docs/proxy.md

@@ -133,6 +133,16 @@ curl http://localhost:8787/stats
 small recent preview. The existing `savings_history` field is still present and
 remains session-scoped for backward compatibility.
 
+For providers that return cache-write TTL bucket usage, `/stats` also includes
+observed TTL breakdowns under `prefix_cache`:
+
+- `observed_ttl_buckets.5m.tokens`
+- `observed_ttl_buckets.1h.tokens`
+- `observed_ttl_mix`
+
+These are provider-reported observations, not configured TTL and not remaining
+expiration time.
+
 ### Historical Savings
 
 ```bash

headroom/dashboard/templates/dashboard.html

@@ -208,6 +208,60 @@
                         <span class="flex items-center gap-1"><span class="w-2 h-2 rounded-full bg-border inline-block"></span> Uncached</span>
                     </div>
                 </div>
+                <template x-if="hasObservedTtlBuckets">
+                    <div class="mt-5 border-t border-border pt-4">
+                        <div class="flex items-center justify-between mb-3">
+                            <div>
+                                <div class="text-xs text-gray-500 uppercase tracking-[0.22em]">Observed TTL Buckets</div>
+                                <div class="text-sm text-gray-300 mt-1">Provider-reported cache write mix</div>
+                            </div>
+                            <div class="text-xs text-gray-500 font-mono" x-text="observedTtlWindowLabel"></div>
+                        </div>
+                        <div class="grid grid-cols-1 xl:grid-cols-[1.3fr_0.9fr] gap-4">
+                            <div class="rounded-2xl border border-cyan-500/20 bg-[linear-gradient(180deg,rgba(34,211,238,0.10),rgba(12,16,22,0.88))] p-4 shadow-[inset_0_1px_0_rgba(255,255,255,0.03)]">
+                        <div class="flex items-start justify-between gap-3">
+                            <div>
+                                <div class="text-[11px] uppercase tracking-[0.22em] text-cyan-300/75">Bucket Mix</div>
+                                <div class="mt-1 text-2xl font-light text-cyan-50">
+                                    <span data-testid="ttl-bucket-mix-1h-total" x-text="formatNumber(stats.prefix_cache?.totals?.cache_write_1h_tokens || 0)"></span>
+                                    <span class="text-sm text-cyan-300/70">1h</span>
+                                    <span class="mx-2 text-cyan-500/60">/</span>
+                                    <span data-testid="ttl-bucket-mix-5m-total" x-text="formatNumber(stats.prefix_cache?.totals?.cache_write_5m_tokens || 0)"></span>
+                                    <span class="text-sm text-cyan-300/70">5m</span>
+                                </div>
+                            </div>
+                            <div data-testid="ttl-bucket-headline" class="rounded-full border border-cyan-400/20 bg-black/20 px-3 py-1 text-[11px] uppercase tracking-[0.18em] text-cyan-200/80" x-text="observedTtlHeadline"></div>
+                                </div>
+                                <div class="mt-4">
+                                    <div class="flex justify-between text-xs text-gray-500 mb-1">
+                                        <span>Observed write-token split</span>
+                                        <span x-text="(stats.prefix_cache?.totals?.observed_ttl_mix?.active_buckets || []).join(' + ')"></span>
+                                    </div>
+                                    <div class="h-3 overflow-hidden rounded-full bg-black/30 ring-1 ring-white/5 flex">
+                                        <div class="h-full bg-cyan-400 transition-all duration-500" :style="'width:' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['1h_pct'] || 0) + '%'"></div>
+                                        <div class="h-full bg-violet-400 transition-all duration-500" :style="'width:' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['5m_pct'] || 0) + '%'"></div>
+                                    </div>
+                                    <div class="mt-2 flex flex-wrap gap-3 text-xs text-gray-400">
+                                        <span class="inline-flex items-center gap-1.5"><span class="inline-block h-2 w-2 rounded-full bg-cyan-400"></span><span data-testid="ttl-bucket-mix-1h-pct" x-text="'1h ' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['1h_pct'] || 0).toFixed(1) + '%'"></span></span>
+                                        <span class="inline-flex items-center gap-1.5"><span class="inline-block h-2 w-2 rounded-full bg-violet-400"></span><span data-testid="ttl-bucket-mix-5m-pct" x-text="'5m ' + (stats.prefix_cache?.totals?.observed_ttl_mix?.['5m_pct'] || 0).toFixed(1) + '%'"></span></span>
+                                    </div>
+                                </div>
+                            </div>
+                            <div class="grid grid-cols-1 sm:grid-cols-2 xl:grid-cols-1 gap-3">
+                                <div class="rounded-2xl border border-white/8 bg-black/20 p-4">
+                                    <div class="text-[11px] uppercase tracking-[0.18em] text-cyan-300/75">1h Cache Writes</div>
+                                    <div data-testid="ttl-bucket-1h-value" class="mt-2 text-3xl font-light text-cyan-50" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['1h']?.tokens || 0)"></div>
+                                    <div class="mt-1 text-xs text-gray-500" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['1h']?.requests || 0) + ' requests observed'"></div>
+                                </div>
+                                <div class="rounded-2xl border border-white/8 bg-black/20 p-4">
+                                    <div class="text-[11px] uppercase tracking-[0.18em] text-violet-300/75">5m Cache Writes</div>
+                                    <div data-testid="ttl-bucket-5m-value" class="mt-2 text-3xl font-light text-violet-50" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['5m']?.tokens || 0)"></div>
+                                    <div class="mt-1 text-xs text-gray-500" x-text="formatNumber(stats.prefix_cache?.totals?.observed_ttl_buckets?.['5m']?.requests || 0) + ' requests observed'"></div>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </template>
                 <!-- Per-provider breakdown -->
                 <template x-if="Object.keys(stats.prefix_cache?.by_provider || {}).length > 0">
                     <div class="mt-4 border-t border-border pt-3">
@@ -219,11 +273,14 @@
                                         <span class="px-2 py-0.5 bg-border rounded text-xs font-mono" x-text="prov"></span>
                                         <span class="text-xs text-gray-500" x-text="pc.label"></span>
                                     </div>
-                                    <div class="flex items-center gap-4 text-xs font-mono">
+                                    <div class="flex flex-wrap items-center justify-end gap-4 text-xs font-mono">
                                         <span class="text-emerald-400" x-text="formatNumber(pc.cache_read_tokens) + ' reads (' + pc.read_discount + ' off)'"></span>
                                         <template x-if="pc.write_premium !== 'none'">
                                             <span class="text-amber-400" x-text="formatNumber(pc.cache_write_tokens) + ' writes (+' + pc.write_premium + ')'"></span>
                                         </template>
+                                        <template x-if="pc.observed_ttl_mix">
+                                            <span class="text-cyan-300" x-text="'TTL 1h ' + (pc.observed_ttl_mix['1h_pct'] || 0).toFixed(1) + '% / 5m ' + (pc.observed_ttl_mix['5m_pct'] || 0).toFixed(1) + '%'"></span>
+                                        </template>
                                         <span :class="pc.bust_count > 0 ? 'text-red-400' : 'text-gray-500'" x-text="pc.bust_count + ' busts'"></span>
                                         <span class="text-emerald-400" x-text="'$' + formatCurrency(pc.net_savings_usd)"></span>
                                     </div>
@@ -1054,6 +1111,26 @@
                     return Math.round((t.cache_write_tokens || 0) / total * 100);
                 },
 
+                get hasObservedTtlBuckets() {
+                    const buckets = this.stats.prefix_cache?.totals?.observed_ttl_buckets || {};
+                    return ((buckets['5m']?.tokens || 0) + (buckets['1h']?.tokens || 0)) > 0;
+                },
+
+                get observedTtlHeadline() {
+                    const mix = this.stats.prefix_cache?.totals?.observed_ttl_mix || {};
+                    const oneHour = mix['1h_pct'] || 0;
+                    const fiveMinute = mix['5m_pct'] || 0;
+                    if (oneHour === fiveMinute) return 'Balanced';
+                    return oneHour > fiveMinute ? '1h leaning' : '5m leaning';
+                },
+
+                get observedTtlWindowLabel() {
+                    const mix = this.stats.prefix_cache?.totals?.observed_ttl_mix || {};
+                    const active = mix.active_buckets || [];
+                    if (!active.length) return 'No TTL bucket data';
+                    return active.length === 1 ? active[0] + ' only' : active.join(' / ');
+                },
+
                 // --- Waste Signals ---
 
                 wasteSignalLabel(signal) {

headroom/proxy/cost.py

@@ -78,6 +78,10 @@ def build_prefix_cache_stats(
     totals = {
         "cache_read_tokens": 0,
         "cache_write_tokens": 0,
+        "cache_write_5m_tokens": 0,
+        "cache_write_1h_tokens": 0,
+        "cache_write_5m_requests": 0,
+        "cache_write_1h_requests": 0,
         "requests": 0,
         "hit_requests": 0,
         "bust_count": 0,
@@ -119,6 +123,10 @@ def build_prefix_cache_stats(
         # for observability but don't penalise our savings number.
         read_tokens: int = pc["cache_read_tokens"]  # type: ignore[assignment]
         write_tokens: int = pc["cache_write_tokens"]  # type: ignore[assignment]
+        write_5m_tokens: int = pc["cache_write_5m_tokens"]  # type: ignore[assignment]
+        write_1h_tokens: int = pc["cache_write_1h_tokens"]  # type: ignore[assignment]
+        write_5m_requests: int = pc["cache_write_5m_requests"]  # type: ignore[assignment]
+        write_1h_requests: int = pc["cache_write_1h_requests"]  # type: ignore[assignment]
         savings_usd = 0.0
         write_premium_usd = 0.0
 
@@ -134,6 +142,10 @@ def build_prefix_cache_stats(
         provider_stats = {
             "cache_read_tokens": read_tokens,
             "cache_write_tokens": write_tokens,
+            "cache_write_5m_tokens": write_5m_tokens,
+            "cache_write_1h_tokens": write_1h_tokens,
+            "cache_write_5m_requests": write_5m_requests,
+            "cache_write_1h_requests": write_1h_requests,
             "requests": pc["requests"],
             "hit_requests": pc["hit_requests"],
             "hit_rate": hit_rate,
@@ -145,12 +157,37 @@ def build_prefix_cache_stats(
             "write_premium_usd": round(write_premium_usd, 4),
             "net_savings_usd": round(savings_usd, 4),
             "label": str(econ["label"]),
+            "observed_ttl_buckets": {
+                "5m": {
+                    "tokens": write_5m_tokens,
+                    "requests": write_5m_requests,
+                },
+                "1h": {
+                    "tokens": write_1h_tokens,
+                    "requests": write_1h_requests,
+                },
+            },
         }
+        total_observed_ttl_tokens = write_5m_tokens + write_1h_tokens
+        if total_observed_ttl_tokens > 0:
+            provider_stats["observed_ttl_mix"] = {
+                "5m_pct": round(write_5m_tokens / total_observed_ttl_tokens * 100, 1),
+                "1h_pct": round(write_1h_tokens / total_observed_ttl_tokens * 100, 1),
+                "active_buckets": [
+                    bucket
+                    for bucket, tokens in (("5m", write_5m_tokens), ("1h", write_1h_tokens))
+                    if tokens > 0
+                ],
+            }
         by_provider[provider] = provider_stats
 
         # Accumulate totals
         totals["cache_read_tokens"] += read_tokens
         totals["cache_write_tokens"] += write_tokens
+        totals["cache_write_5m_tokens"] += write_5m_tokens
+        totals["cache_write_1h_tokens"] += write_1h_tokens
+        totals["cache_write_5m_requests"] += write_5m_requests
+        totals["cache_write_1h_requests"] += write_1h_requests
         totals["requests"] += pc["requests"]
         totals["hit_requests"] += pc["hit_requests"]
         totals["bust_count"] += pc["bust_count"]
@@ -164,6 +201,33 @@ def build_prefix_cache_stats(
     totals["hit_rate"] = (
         round(totals["hit_requests"] / totals["requests"] * 100, 1) if totals["requests"] > 0 else 0
     )
+    total_observed_ttl_tokens = totals["cache_write_5m_tokens"] + totals["cache_write_1h_tokens"]
+    totals["observed_ttl_buckets"] = {
+        "5m": {
+            "tokens": totals["cache_write_5m_tokens"],
+            "requests": totals["cache_write_5m_requests"],
+        },
+        "1h": {
+            "tokens": totals["cache_write_1h_tokens"],
+            "requests": totals["cache_write_1h_requests"],
+        },
+    }
+    totals["observed_ttl_mix"] = {
+        "5m_pct": round(totals["cache_write_5m_tokens"] / total_observed_ttl_tokens * 100, 1)
+        if total_observed_ttl_tokens > 0
+        else 0.0,
+        "1h_pct": round(totals["cache_write_1h_tokens"] / total_observed_ttl_tokens * 100, 1)
+        if total_observed_ttl_tokens > 0
+        else 0.0,
+        "active_buckets": [
+            bucket
+            for bucket, tokens in (
+                ("5m", totals["cache_write_5m_tokens"]),
+                ("1h", totals["cache_write_1h_tokens"]),
+            )
+            if tokens > 0
+        ],
+    }
 
     return {
         "by_provider": by_provider,
@@ -180,7 +244,9 @@ def build_prefix_cache_stats(
             "Prefix caching is performed by the LLM provider (Anthropic, OpenAI). "
             "Headroom reports cache stats as observed from API responses. "
             "CacheAligner and prefix freeze improve cache hit rates by stabilizing "
-            "the message prefix, but baseline caching happens without Headroom."
+            "the message prefix, but baseline caching happens without Headroom. "
+            "Observed TTL bucket metrics reflect provider-reported cache write usage "
+            "(for example Anthropic 5m vs 1h), not configured or remaining TTL."
         ),
     }
 
@@ -356,6 +422,8 @@ class CostTracker:
         # API-reported cache breakdown per model (for accurate cost calculation)
         self._api_cache_read_by_model: dict[str, int] = {}
         self._api_cache_write_by_model: dict[str, int] = {}
+        self._api_cache_write_5m_by_model: dict[str, int] = {}
+        self._api_cache_write_1h_by_model: dict[str, int] = {}
         self._api_uncached_by_model: dict[str, int] = {}
 
     # Cache resolved model names to avoid repeated litellm lookups.
@@ -480,6 +548,8 @@ class CostTracker:
         tokens_sent: int,
         cache_read_tokens: int = 0,
         cache_write_tokens: int = 0,
+        cache_write_5m_tokens: int = 0,
+        cache_write_1h_tokens: int = 0,
         uncached_tokens: int = 0,
     ):
         """Record token counts per model.
@@ -503,6 +573,12 @@ class CostTracker:
         self._api_cache_write_by_model[model] = (
             self._api_cache_write_by_model.get(model, 0) + cache_write_tokens
         )
+        self._api_cache_write_5m_by_model[model] = (
+            self._api_cache_write_5m_by_model.get(model, 0) + cache_write_5m_tokens
+        )
+        self._api_cache_write_1h_by_model[model] = (
+            self._api_cache_write_1h_by_model.get(model, 0) + cache_write_1h_tokens
+        )
         self._api_uncached_by_model[model] = (
             self._api_uncached_by_model.get(model, 0) + uncached_tokens
         )
@@ -574,6 +650,8 @@ class CostTracker:
                 "requests": reqs,
                 "tokens_saved": saved,
                 "tokens_sent": sent,
+                "cache_write_5m_tokens": self._api_cache_write_5m_by_model.get(model, 0),
+                "cache_write_1h_tokens": self._api_cache_write_1h_by_model.get(model, 0),
                 "reduction_pct": round(saved / (saved + sent) * 100, 1)
                 if (saved + sent) > 0
                 else 0,
@@ -625,6 +703,8 @@ class CostTracker:
             "total_tokens_saved": total_saved,
             "total_input_tokens": total_input_tokens,
             "total_input_cost_usd": round(cost_with_headroom, 4),
+            "cache_write_5m_tokens": sum(self._api_cache_write_5m_by_model.values()),
+            "cache_write_1h_tokens": sum(self._api_cache_write_1h_by_model.values()),
             "per_model": per_model,
             "cost_with_headroom_usd": round(cost_with_headroom, 4),
             "savings_usd": round(savings_usd, 4),

headroom/proxy/handlers/anthropic.py

@@ -40,6 +40,24 @@ class AnthropicHandlerMixin:
             canonical = str(tool)
         return (name, canonical)
 
+    @staticmethod
+    def _extract_anthropic_cache_ttl_metrics(usage: dict[str, Any] | None) -> tuple[int, int]:
+        """Extract observed Anthropic cache-write TTL bucket usage.
+
+        Returns (cache_write_5m_tokens, cache_write_1h_tokens) from provider usage.
+        These are observational metrics only; they do not imply configured or
+        remaining TTL.
+        """
+        if not isinstance(usage, dict):
+            return (0, 0)
+        cache_creation = usage.get("cache_creation")
+        if not isinstance(cache_creation, dict):
+            return (0, 0)
+        return (
+            int(cache_creation.get("ephemeral_5m_input_tokens", 0) or 0),
+            int(cache_creation.get("ephemeral_1h_input_tokens", 0) or 0),
+        )
+
     @classmethod
     def _sort_tools_deterministically(
         cls, tools: list[dict[str, Any]] | None
@@ -1196,12 +1214,15 @@ class AnthropicHandlerMixin:
                 output_tokens = 0
                 cr_tokens = 0
                 cw_tokens = 0
+                cw_5m_tokens = 0
+                cw_1h_tokens = 0
                 uncached_input_tokens = 0
                 if resp_json:
                     usage = resp_json.get("usage", {})
                     output_tokens = usage.get("output_tokens", 0)
                     cr_tokens = usage.get("cache_read_input_tokens", 0)
                     cw_tokens = usage.get("cache_creation_input_tokens", 0)
+                    cw_5m_tokens, cw_1h_tokens = self._extract_anthropic_cache_ttl_metrics(usage)
                     uncached_input_tokens = usage.get("input_tokens", 0)
 
                 # Update prefix cache tracker for next turn
@@ -1225,6 +1246,8 @@ class AnthropicHandlerMixin:
                         optimized_tokens,
                         cache_read_tokens=cr_tokens,
                         cache_write_tokens=cw_tokens,
+                        cache_write_5m_tokens=cw_5m_tokens,
+                        cache_write_1h_tokens=cw_1h_tokens,
                         uncached_tokens=uncached_input_tokens,
                     )
 
@@ -1252,6 +1275,8 @@ class AnthropicHandlerMixin:
                     waste_signals=waste_signals_dict,
                     cache_read_tokens=cr_tokens,
                     cache_write_tokens=cw_tokens,
+                    cache_write_5m_tokens=cw_5m_tokens,
+                    cache_write_1h_tokens=cw_1h_tokens,
                     uncached_input_tokens=uncached_input_tokens,
                 )
 

headroom/proxy/handlers/streaming.py

@@ -24,6 +24,19 @@ logger = logging.getLogger("headroom.proxy")
 class StreamingMixin:
     """Mixin providing streaming response methods for HeadroomProxy."""
 
+    @staticmethod
+    def _extract_anthropic_cache_ttl_metrics(usage: dict[str, Any] | None) -> tuple[int, int]:
+        """Extract observed Anthropic cache-write TTL bucket usage."""
+        if not isinstance(usage, dict):
+            return (0, 0)
+        cache_creation = usage.get("cache_creation")
+        if not isinstance(cache_creation, dict):
+            return (0, 0)
+        return (
+            int(cache_creation.get("ephemeral_5m_input_tokens", 0) or 0),
+            int(cache_creation.get("ephemeral_1h_input_tokens", 0) or 0),
+        )
+
     def _parse_sse_usage(self, chunk: bytes, provider: str) -> dict[str, int] | None:
         """Parse usage information from SSE chunk.
 
@@ -31,7 +44,9 @@ class StreamingMixin:
         For OpenAI: Looks for final chunk with usage object (requires stream_options.include_usage=true)
         For Gemini: Looks for usageMetadata in each chunk
 
-        Returns dict with keys: input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens
+        Returns dict with keys: input_tokens, output_tokens, cache_read_input_tokens,
+        cache_creation_input_tokens, cache_creation_ephemeral_5m_input_tokens,
+        cache_creation_ephemeral_1h_input_tokens
         Returns None if no usage found in this chunk.
         """
         try:
@@ -67,6 +82,11 @@ class StreamingMixin:
                             usage["cache_creation_input_tokens"] = msg_usage.get(
                                 "cache_creation_input_tokens", 0
                             )
+                            cache_write_5m, cache_write_1h = (
+                                self._extract_anthropic_cache_ttl_metrics(msg_usage)
+                            )
+                            usage["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m
+                            usage["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1h
 
                     elif event_type == "message_delta":
                         delta_usage = data.get("usage", {})
@@ -148,6 +168,11 @@ class StreamingMixin:
                             usage_found["cache_creation_input_tokens"] = msg_usage.get(
                                 "cache_creation_input_tokens", 0
                             )
+                            cache_write_5m, cache_write_1h = (
+                                self._extract_anthropic_cache_ttl_metrics(msg_usage)
+                            )
+                            usage_found["cache_creation_ephemeral_5m_input_tokens"] = cache_write_5m
+                            usage_found["cache_creation_ephemeral_1h_input_tokens"] = cache_write_1h
                             # INFO logging for cache token tracking (temporary for debugging)
                             logger.info(
                                 f"[CACHE] Anthropic usage: input={usage_found.get('input_tokens')}, "
@@ -450,6 +475,8 @@ class StreamingMixin:
             "output_tokens": None,
             "cache_read_input_tokens": 0,
             "cache_creation_input_tokens": 0,
+            "cache_creation_ephemeral_5m_input_tokens": 0,
+            "cache_creation_ephemeral_1h_input_tokens": 0,
             "total_bytes": 0,
             "sse_buffer": "",  # Buffer for incomplete SSE events
             "ttfb_ms": None,  # Time to first byte from upstream
@@ -550,6 +577,14 @@ class StreamingMixin:
                                 stream_state["cache_creation_input_tokens"] = usage[
                                     "cache_creation_input_tokens"
                                 ]
+                            if "cache_creation_ephemeral_5m_input_tokens" in usage:
+                                stream_state["cache_creation_ephemeral_5m_input_tokens"] = usage[
+                                    "cache_creation_ephemeral_5m_input_tokens"
+                                ]
+                            if "cache_creation_ephemeral_1h_input_tokens" in usage:
+                                stream_state["cache_creation_ephemeral_1h_input_tokens"] = usage[
+                                    "cache_creation_ephemeral_1h_input_tokens"
+                                ]
 
                 # Memory tool handling after stream completes
                 # Chunks were already yielded in real-time above, so we only
@@ -637,6 +672,8 @@ class StreamingMixin:
                 # misleading for aggregation (often just 1 with prompt caching).
                 cache_read_tokens = stream_state["cache_read_input_tokens"]
                 cache_write_tokens = stream_state["cache_creation_input_tokens"]
+                cache_write_5m_tokens = stream_state["cache_creation_ephemeral_5m_input_tokens"]
+                cache_write_1h_tokens = stream_state["cache_creation_ephemeral_1h_input_tokens"]
                 uncached_input_tokens = stream_state.get("input_tokens") or 0
 
                 # Structured perf log line for `headroom perf` analysis
@@ -672,6 +709,8 @@ class StreamingMixin:
                         optimized_tokens,
                         cache_read_tokens=cache_read_tokens,
                         cache_write_tokens=cache_write_tokens,
+                        cache_write_5m_tokens=cache_write_5m_tokens,
+                        cache_write_1h_tokens=cache_write_1h_tokens,
                         uncached_tokens=uncached_input_tokens,
                     )
 
@@ -687,6 +726,8 @@ class StreamingMixin:
                     pipeline_timing=pipeline_timing,
                     cache_read_tokens=cache_read_tokens,
                     cache_write_tokens=cache_write_tokens,
+                    cache_write_5m_tokens=cache_write_5m_tokens,
+                    cache_write_1h_tokens=cache_write_1h_tokens,
                     uncached_input_tokens=uncached_input_tokens,
                 )
 

headroom/proxy/prometheus_metrics.py

@@ -77,6 +77,10 @@ class PrometheusMetrics:
             lambda: {
                 "cache_read_tokens": 0,
                 "cache_write_tokens": 0,
+                "cache_write_5m_tokens": 0,
+                "cache_write_1h_tokens": 0,
+                "cache_write_5m_requests": 0,
+                "cache_write_1h_requests": 0,
                 "requests": 0,
                 "hit_requests": 0,  # requests with cache_read > 0
                 "bust_count": 0,
@@ -158,6 +162,8 @@ class PrometheusMetrics:
         waste_signals: dict[str, int] | None = None,
         cache_read_tokens: int = 0,
         cache_write_tokens: int = 0,
+        cache_write_5m_tokens: int = 0,
+        cache_write_1h_tokens: int = 0,
         uncached_input_tokens: int = 0,
     ):
         """Record metrics for a request."""
@@ -178,6 +184,12 @@ class PrometheusMetrics:
                 pc = self.cache_by_provider[provider]
                 pc["cache_read_tokens"] += cache_read_tokens
                 pc["cache_write_tokens"] += cache_write_tokens
+                pc["cache_write_5m_tokens"] += cache_write_5m_tokens
+                pc["cache_write_1h_tokens"] += cache_write_1h_tokens
+                if cache_write_5m_tokens > 0:
+                    pc["cache_write_5m_requests"] += 1
+                if cache_write_1h_tokens > 0:
+                    pc["cache_write_1h_requests"] += 1
                 pc["requests"] += 1
                 if cache_read_tokens > 0:
                     pc["hit_requests"] += 1

tests/test_dashboard_cache_ttl_playwright.py

@@ -0,0 +1,211 @@
+"""Behavior-driven Playwright validation for dashboard TTL cache metrics."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from headroom.dashboard import get_dashboard_html
+
+playwright = pytest.importorskip("playwright.sync_api")
+Page = playwright.Page
+expect = playwright.expect
+sync_playwright = playwright.sync_playwright
+
+
+def _sample_stats() -> dict:
+    return {
+        "cost": {
+            "savings_usd": 12.34,
+            "compression_savings_usd": 12.34,
+            "cache_savings_usd": 5.67,
+            "cli_tokens_avoided": 0,
+        },
+        "requests": {
+            "total": 128,
+            "cached": 96,
+            "rate_limited": 0,
+            "failed": 0,
+            "by_provider": {"anthropic": 128},
+            "by_model": {"claude-opus-4-6": 128},
+        },
+        "tokens": {
+            "input": 245_000,
+            "output": 88_000,
+            "saved": 143_000,
+            "cli_tokens_avoided": 0,
+            "total_before_compression": 388_000,
+            "savings_percent": 36.86,
+        },
+        "overhead": {"average_ms": 14.2, "min_ms": 4.5, "max_ms": 42.7},
+        "ttfb": {"average_ms": 1320.0, "min_ms": 420.0, "max_ms": 2900.0},
+        "latency": {"average_ms": 1510.0, "min_ms": 520.0, "max_ms": 3300.0},
+        "waste_signals": {"json_bloat": 95_000, "repetition": 48_000},
+        "savings_history": [
+            ["2026-04-01T00:00:00Z", 12_000],
+            ["2026-04-02T00:00:00Z", 38_000],
+            ["2026-04-03T00:00:00Z", 57_000],
+            ["2026-04-04T00:00:00Z", 102_000],
+            ["2026-04-05T00:00:00Z", 143_000],
+        ],
+        "persistent_savings": {
+            "display_session": {},
+            "lifetime": {"tokens_saved": 143_000, "compression_savings_usd": 12.34},
+        },
+        "pipeline_timing": {},
+        "compression_cache": {"mode": "cache"},
+        "prefix_cache": {
+            "by_provider": {
+                "anthropic": {
+                    "cache_read_tokens": 9_800_000,
+                    "cache_write_tokens": 420_000,
+                    "cache_write_5m_tokens": 185_000,
+                    "cache_write_1h_tokens": 235_000,
+                    "cache_write_5m_requests": 18,
+                    "cache_write_1h_requests": 24,
+                    "requests": 128,
+                    "hit_requests": 96,
+                    "hit_rate": 75.0,
+                    "bust_count": 0,
+                    "bust_write_tokens": 0,
+                    "read_discount": "90%",
+                    "write_premium": "25%",
+                    "savings_usd": 5.67,
+                    "write_premium_usd": 0.42,
+                    "net_savings_usd": 5.67,
+                    "label": "Explicit breakpoints, 5-min TTL",
+                    "observed_ttl_buckets": {
+                        "5m": {"tokens": 185_000, "requests": 18},
+                        "1h": {"tokens": 235_000, "requests": 24},
+                    },
+                    "observed_ttl_mix": {
+                        "5m_pct": 44.0,
+                        "1h_pct": 56.0,
+                        "active_buckets": ["5m", "1h"],
+                    },
+                }
+            },
+            "totals": {
+                "cache_read_tokens": 9_800_000,
+                "cache_write_tokens": 420_000,
+                "cache_write_5m_tokens": 185_000,
+                "cache_write_1h_tokens": 235_000,
+                "cache_write_5m_requests": 18,
+                "cache_write_1h_requests": 24,
+                "requests": 128,
+                "hit_requests": 96,
+                "bust_count": 0,
+                "bust_write_tokens": 0,
+                "savings_usd": 5.67,
+                "write_premium_usd": 0.42,
+                "net_savings_usd": 5.67,
+                "hit_rate": 75.0,
+                "observed_ttl_buckets": {
+                    "5m": {"tokens": 185_000, "requests": 18},
+                    "1h": {"tokens": 235_000, "requests": 24},
+                },
+                "observed_ttl_mix": {
+                    "5m_pct": 44.0,
+                    "1h_pct": 56.0,
+                    "active_buckets": ["5m", "1h"],
+                },
+            },
+            "prefix_freeze": {
+                "busts_avoided": 0,
+                "tokens_preserved": 0,
+                "compression_foregone_tokens": 0,
+                "net_benefit_tokens": 0,
+            },
+            "attribution": "Observed provider TTL buckets.",
+        },
+    }
+
+
+def _sample_history() -> dict:
+    return {
+        "history": [
+            {
+                "timestamp": "2026-04-01T00:00:00Z",
+                "total_tokens_saved": 12_000,
+                "compression_savings_usd": 0.6,
+            },
+            {
+                "timestamp": "2026-04-05T00:00:00Z",
+                "total_tokens_saved": 143_000,
+                "compression_savings_usd": 12.34,
+            },
+        ],
+        "series": {
+            "daily": [
+                {
+                    "timestamp": "2026-04-05T00:00:00Z",
+                    "tokens_saved": 20_000,
+                    "total_tokens_saved": 143_000,
+                    "compression_savings_usd_delta": 1.7,
+                }
+            ],
+            "weekly": [],
+            "monthly": [],
+        },
+        "lifetime": {"tokens_saved": 143_000, "compression_savings_usd": 12.34},
+    }
+
+
+def _install_dashboard_routes(page: Page) -> None:
+    stats = _sample_stats()
+    history = _sample_history()
+    health = {"status": "healthy", "version": "0.3.0"}
+    dashboard_html = get_dashboard_html()
+
+    def handler(route) -> None:  # type: ignore[no-untyped-def]
+        url = route.request.url
+        if url.endswith("/dashboard") or url == "http://headroom.local/":
+            route.fulfill(status=200, content_type="text/html", body=dashboard_html)
+            return
+        if url.endswith("/stats"):
+            route.fulfill(status=200, content_type="application/json", body=json.dumps(stats))
+            return
+        if "/stats-history" in url:
+            route.fulfill(
+                status=200,
+                content_type="application/json",
+                body=json.dumps(history),
+            )
+            return
+        if url.endswith("/health"):
+            route.fulfill(status=200, content_type="application/json", body=json.dumps(health))
+            return
+        route.continue_()
+
+    page.route("**/*", handler)
+
+
+def test_dashboard_renders_observed_ttl_metrics_and_can_capture_screenshot() -> None:
+    artifact_dir = os.environ.get("HEADROOM_PLAYWRIGHT_ARTIFACT_DIR")
+
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch()
+        page = browser.new_page(viewport={"width": 1720, "height": 1400}, color_scheme="dark")
+        _install_dashboard_routes(page)
+        page.goto("http://headroom.local/dashboard", wait_until="load")
+
+        expect(page.get_by_text("Observed TTL Buckets")).to_be_visible()
+        expect(page.get_by_text("Provider-reported cache write mix")).to_be_visible()
+        expect(page.get_by_test_id("ttl-bucket-headline")).to_have_text("1h leaning")
+        expect(page.get_by_test_id("ttl-bucket-mix-1h-pct")).to_have_text("1h 56.0%")
+        expect(page.get_by_test_id("ttl-bucket-mix-5m-pct")).to_have_text("5m 44.0%")
+        expect(page.get_by_test_id("ttl-bucket-1h-value")).to_have_text("235.0k")
+        expect(page.get_by_test_id("ttl-bucket-5m-value")).to_have_text("185.0k")
+        expect(page.get_by_text("TTL 1h 56.0% / 5m 44.0%")).to_be_visible()
+
+        screenshot_path = (
+            Path(artifact_dir) / "dashboard-cache-ttl-main.png"
+            if artifact_dir
+            else Path.cwd() / "dashboard-cache-ttl-main.png"
+        )
+        screenshot_path.parent.mkdir(parents=True, exist_ok=True)
+        page.screenshot(path=str(screenshot_path), full_page=True)
+        browser.close()

tests/test_proxy_cache_ttl_metrics.py

@@ -0,0 +1,147 @@
+"""Tests for observed Anthropic cache TTL bucket metrics."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from headroom.proxy.cost import CostTracker, build_prefix_cache_stats
+from headroom.proxy.prometheus_metrics import PrometheusMetrics
+
+
+def test_prometheus_metrics_tracks_observed_ttl_buckets() -> None:
+    metrics = PrometheusMetrics()
+
+    asyncio.run(
+        metrics.record_request(
+            provider="anthropic",
+            model="claude-opus-4-6",
+            input_tokens=100,
+            output_tokens=20,
+            tokens_saved=5,
+            latency_ms=10.0,
+            cache_read_tokens=40,
+            cache_write_tokens=60,
+            cache_write_5m_tokens=10,
+            cache_write_1h_tokens=50,
+        )
+    )
+
+    stats = metrics.cache_by_provider["anthropic"]
+    assert stats["cache_write_5m_tokens"] == 10
+    assert stats["cache_write_1h_tokens"] == 50
+    assert stats["cache_write_5m_requests"] == 1
+    assert stats["cache_write_1h_requests"] == 1
+
+
+def test_cost_tracker_exposes_observed_ttl_buckets_per_model() -> None:
+    tracker = CostTracker()
+    tracker.record_tokens(
+        "claude-opus-4-6",
+        tokens_saved=10,
+        tokens_sent=90,
+        cache_read_tokens=40,
+        cache_write_tokens=60,
+        cache_write_5m_tokens=10,
+        cache_write_1h_tokens=50,
+        uncached_tokens=20,
+    )
+
+    stats = tracker.stats()
+    assert stats["cache_write_5m_tokens"] == 10
+    assert stats["cache_write_1h_tokens"] == 50
+    assert stats["per_model"]["claude-opus-4-6"]["cache_write_5m_tokens"] == 10
+    assert stats["per_model"]["claude-opus-4-6"]["cache_write_1h_tokens"] == 50
+
+
+def test_prefix_cache_stats_include_observed_ttl_mix() -> None:
+    metrics = PrometheusMetrics()
+    provider_stats = metrics.cache_by_provider["anthropic"]
+    provider_stats["requests"] = 2
+    provider_stats["hit_requests"] = 1
+    provider_stats["cache_read_tokens"] = 40
+    provider_stats["cache_write_tokens"] = 60
+    provider_stats["cache_write_5m_tokens"] = 15
+    provider_stats["cache_write_1h_tokens"] = 45
+    provider_stats["cache_write_5m_requests"] = 1
+    provider_stats["cache_write_1h_requests"] = 1
+
+    stats = build_prefix_cache_stats(metrics, None)
+    anthropic = stats["by_provider"]["anthropic"]
+
+    assert anthropic["observed_ttl_buckets"]["5m"]["tokens"] == 15
+    assert anthropic["observed_ttl_buckets"]["1h"]["tokens"] == 45
+    assert anthropic["observed_ttl_mix"]["5m_pct"] == 25.0
+    assert anthropic["observed_ttl_mix"]["1h_pct"] == 75.0
+    assert stats["totals"]["observed_ttl_buckets"]["5m"]["tokens"] == 15
+    assert stats["totals"]["observed_ttl_buckets"]["1h"]["tokens"] == 45
+
+
+def test_streaming_parser_extracts_anthropic_ttl_bucket_usage() -> None:
+    from headroom.proxy.server import HeadroomProxy, ProxyConfig
+
+    proxy = HeadroomProxy(
+        ProxyConfig(
+            optimize=False,
+            cache_enabled=False,
+            rate_limit_enabled=False,
+            cost_tracking_enabled=False,
+            log_requests=False,
+            ccr_inject_tool=False,
+            ccr_handle_responses=False,
+            ccr_context_tracking=False,
+        )
+    )
+
+    chunk = (
+        b'data: {"type":"message_start","message":{"usage":{"input_tokens":12,'
+        b'"cache_read_input_tokens":3,"cache_creation_input_tokens":9,'
+        b'"cache_creation":{"ephemeral_5m_input_tokens":4,"ephemeral_1h_input_tokens":5}}}}\n\n'
+    )
+    usage = proxy._parse_sse_usage(chunk, "anthropic")
+
+    assert usage is not None
+    assert usage["cache_creation_ephemeral_5m_input_tokens"] == 4
+    assert usage["cache_creation_ephemeral_1h_input_tokens"] == 5
+
+
+def test_stats_endpoint_reports_observed_ttl_buckets() -> None:
+    pytest.importorskip("fastapi")
+    from fastapi.testclient import TestClient
+
+    from headroom.proxy.server import ProxyConfig, create_app
+
+    app = create_app(
+        ProxyConfig(
+            optimize=False,
+            cache_enabled=False,
+            rate_limit_enabled=False,
+            cost_tracking_enabled=False,
+            log_requests=False,
+            ccr_inject_tool=False,
+            ccr_handle_responses=False,
+            ccr_context_tracking=False,
+        )
+    )
+
+    proxy = app.state.proxy
+    provider_stats = proxy.metrics.cache_by_provider["anthropic"]
+    provider_stats["requests"] = 1
+    provider_stats["hit_requests"] = 1
+    provider_stats["cache_read_tokens"] = 30
+    provider_stats["cache_write_tokens"] = 70
+    provider_stats["cache_write_5m_tokens"] = 20
+    provider_stats["cache_write_1h_tokens"] = 50
+    provider_stats["cache_write_5m_requests"] = 1
+    provider_stats["cache_write_1h_requests"] = 1
+
+    with TestClient(app) as client:
+        response = client.get("/stats")
+
+    assert response.status_code == 200
+    prefix_cache = response.json()["prefix_cache"]
+    anthropic = prefix_cache["by_provider"]["anthropic"]
+    assert anthropic["observed_ttl_buckets"]["5m"]["tokens"] == 20
+    assert anthropic["observed_ttl_buckets"]["1h"]["tokens"] == 50
+    assert prefix_cache["totals"]["observed_ttl_mix"]["active_buckets"] == ["5m", "1h"]