[Feature]: add provider/model estimated cost and cache metrics to Usage

[str0203]

Area

Web Dashboard → Usage

Relationship to existing work

This is a focused follow-up to #1058.

Issue #1058 tracks calendar-day/custom-range filtering and daily model breakdown. This issue tracks the provider/model usage accounting that should be displayed for the selected timeframe. It should reuse the existing usage-summary/data path and pricing infrastructure rather than introduce a separate analytics system.

Goal

Give operators a practical local estimate of where tokens and estimated spend are going, and how effectively prompt caching is being used.

This is intentionally about local estimated usage cost, not official provider billing, account balances, invoices, or quota tracking.

Required breakdown

For the selected calendar day or date range, show provider-level and model-level rows containing, where available:

• provider
• model
• request count
• input tokens
• output tokens
• total tokens
• cache-read input tokens
• cache-creation input tokens
• estimated cost in USD
• usage/price coverage or an equivalent indication of data quality

Model rows must remain attributable to their provider. The provider view should support expanding into, or filtering by, its models.

Cache metrics

Where the upstream/provider reports sufficient counters, expose:

• cache-read tokens
• cache-creation tokens
• cache hit rate
• optionally, cache participation rate if that is more meaningful for a provider

The cache-hit-rate formula must be deterministic and documented. A reasonable default is:

cacheReadInputTokens / inputTokens

or, when uncached input is available:

cacheReadInputTokens / (cacheReadInputTokens + uncachedInputTokens)

If the necessary counters are unavailable, show unavailable/unknown, not 0%.

Estimated cost

• Reuse the existing model/provider pricing and cost-estimation fields where possible.
• Include cache-read and cache-creation pricing when configured and supported.
• If a provider/model has no matching price, show the row as unpriced/unavailable instead of silently treating it as $0.
• Keep the result clearly labeled as an estimate.

Daily drill-down

When a date range contains multiple days, users should be able to inspect the same provider/model/token/cache/cost breakdown for one individual calendar day, either by selecting a day in the existing Usage chart or through a daily detail table.

The implementation should compose with #1058's date filters and daily model view, but does not need to duplicate that UI.

Data-path requirements

• Aggregate in the authoritative usage-summary/API layer.
• Do not parse usage.jsonl directly in the frontend.
• Do not reconstruct provider/model totals from chart pixels or unrelated UI state.
• Preserve existing 7d/30d/available-history behavior and the date semantics defined by [Feature]: add single-day/custom date filtering and daily model metrics to Usage #1058.
• Add deterministic tests for provider/model attribution, cache counters, cache-rate calculation, estimated pricing, and unavailable-data behavior.

Suggested delivery

This can be delivered in small independently testable slices:

1. Normalize and expose provider/model cache and pricing fields in the usage-summary/API result.
2. Add aggregation and regression tests.
3. Add provider/model tables and estimated-cost columns.
4. Add cache metrics and daily drill-down integration.

Acceptance criteria

• A selected day or date range shows provider-level and model-level request/token totals.
• Cache-read and cache-creation tokens are shown separately when available.
• Cache hit rate is shown only when its inputs are available, using a documented formula.
• Missing cache data is shown as unavailable/unknown, not as zero.
• Estimated cost is shown per provider/model when price data is available.
• Cache pricing is included when supported by the configured price data.
• Unmatched prices are visibly unpriced/unavailable, not silently counted as $0.
• A user can inspect the provider/model breakdown for an individual day within a multi-day selection.
• Existing Usage ranges and [Feature]: add single-day/custom date filtering and daily model metrics to Usage #1058's date-boundary/API separation requirements remain intact.
• Backend/API and frontend regression tests cover the new behavior.

Out of scope

• Official provider invoices or billing APIs
• Provider account balances or quota/reset tracking
• A separate analytics database
• Replacing the existing Usage workspace

[coderabbitai]

🔗 Related PRs

#501 - fix(usage): keep large dashboard logs responsive [merged]
#1010 - feat(usage): user-configurable per-model cost overlay (providers..modelCosts) [merged]
#1079 - feat(usage): add date filters and daily model breakdown in dashboard (#1058) [open]
#1083 - feat(usage): add account usage filter and indicators in provider workspace (#1063) [open]
#1638 - fix(usage): align 7d and 30d range windows to start-of-day calendar boundaries (#1580) [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[Ingwannu]

This is useful, but current dev already implements a substantial part of the requested backend contract, so it should be treated as a focused completion issue rather than a new analytics subsystem.

Already present in src/usage/summary.ts and the Usage/provider surfaces:

• provider/model request and token attribution;
• top-level cache-read and cache-creation token totals;
• coverage ratio;
• per-request, per-model, and per-provider estimated cost;
• explicit unpriced/unmetered request counts;
• calendar-day buckets with model attribution.

The remaining concrete gap is narrower:

1. carry cache-read/cache-creation counters into each provider/model row, not only the top-level totals;
2. expose per-row priced/unpriced or coverage state instead of omitting estimatedCostUsd without an explicit reason;
3. define one cache-hit formula and return null/unknown when its inputs were not reported;
4. enrich daily rows with the same token/cache/cost fields so a day drill-down does not reconstruct them in the frontend;
5. then add the provider/model/day UI using only that API result.

Please keep #1058 as the date-range interaction dependency. I would accept this in backend-first slices with deterministic summary tests; parsing usage.jsonl or recomputing accounting in React would be a blocker.