Docs/Concepts/Metrics and definitions
Metrics and definitions
Every number in Bill-y has a definition, and the definitions ship with the product (the console's methodology page states the same rules). This page is the canonical public copy.
Tokens: fresh versus cache
Token counts are split into four streams: fresh input, output, cache reads, and cache writes.
- Fresh input and output are the expensive tokens: new context in, new work out.
- Cache reads are cheap re-use of context the provider already holds.
- Cache writes are priced by their retention window, and Bill-y tracks the split so pricing stays exact.
A consistently high fresh share of paid input usually means long sessions are being restarted cold instead of continued. That single signal often pays for the deployment.
Dollars are estimates, and say so
- Every dollar figure is computed at read time from your organization's own price table: effective-dated rates per model pattern, editable in the console.
- A price change is versioned. Back-dating a rate deliberately reprices history and forecasts together, so the numbers stay consistent rather than freezing an error in place.
- Usage on models with no configured rate is priced by a blended fallback rate, and every figure reports its
blended_share: the fraction priced by fallback. A high blended share is a prompt to complete the price table, not a hidden inaccuracy.
Note
Bill-y never presents a dollar figure as an invoice. The estimate basis, the price table version and the blended share are part of the number.
The forecast ladder
Month-end spend forecasts always disclose their method. The ladder, from strongest to weakest:
| Method | How it works | Band |
|---|---|---|
weekday | Each remaining day is projected from that weekday's median over the trailing 56 days. | P10 to P90 |
runrate | Linear projection from month-to-date. Used when history is thin. | plus or minus 40 percent, low confidence |
none | Under 3 days of history: no number is invented. | none |
closed | Past months report actuals. | collapsed |
Today's contribution is floored at what today has already spent, so a forecast can never dip below reality.
Budgets read the band, not the point
Budget status compares the target against the forecast band:
exceeding: even the low end of the band clears the target.at_risk: the band straddles the target.ok: even the high end stays under.
Budgets are soft by design. They are observed and reported, never enforced as a cutoff, because a hard stop on spend mid-incident is worse than an overage.
Engagement bands
People-level engagement is measured in distinct active days over the last 28, not in volume: 0 none, 1 to 5 light, 6 to 14 moderate, 15 and up heavy. Days rather than tokens, because volume rewards waste.
Deterministic insights
The insight cards in the management overview are produced by deterministic rules with fixed thresholds (spend spikes, fresh-share warnings, phase shifts, idle licensed seats, high abstain share, missing review floor). No model decides what is anomalous, every insight is reproducible from the data, and at most seven are shown so the surface stays readable.