Calculation Backend decision 8

Ephemeral cache tokens: store the undifferentiated remainder as its own value; bill it at the 1h rate

Claude usage reports carry both a flat cache_creation_input_tokens total and, optionally, a split into ephemeral_5m_input_tokens / ephemeral_1h_input_tokens. Sometimes the sum falls short of the total.

We store this shortfall as its own “generic” value in the database, rather than folding it silently into the 5m or 1h count. For pricing/CO2 purposes it is billed at the 1h rate (in code, not via a dedicated price column). Adjust this (for price calculation as well as the /prices/claude-API) if another value fits your system better.

Why:

  • We want the dashboard to stay simple: one price per token type, no “unknown” bucket exposed to users. This is a deliberate simplification, not an attempt to be maximally accurate.
  • We do not know which TTL the generic tokens actually belong to, and the ratio of 5m to 1h usage is provider/setup-specific (e.g. it depends on how a given CLI sets cache_control.ttl). A hard 1h default that fits our own usage pattern may not fit other setups.
  • Storing the generic amount separately (instead of just adding it into the 1h count) keeps this assumption visible and correctable later, without losing historical data.
  • Billing it in code (rather than via a separate cache_write_cent_per_million price column for “generic”) avoids implying that a dedicated, meaningfully different price exists for this case.
  • By using the 1h value for the /api/prices/claude API, we keep the plugin free of logic. If your system uses a different price, change it here too, so the plugin’s status line shows your price.