Tokens Aren't a Bill: Agent Cost Screens Must Separate Usage, Included Value, and Amount Due
Imagine a product review in which the usage page shows 2.3 million tokens. Engineering calls the number accurate. Finance asks what will be owed. The team administrator asks how much the subscription covered. The developer asks which model, task, or cache miss caused the spike.
The number can be accurate and still fail every decision in the room.
This is not a theoretical UX edge case. In July 2026, several users in one Cursor Forum discussion objected when a usage view replaced dollar figures with token counts. They wanted daily, per-user, and per-model cost visibility. Cursor staff explained the counterproblem: a list-price dollar equivalent for included usage could exceed the subscription price and be mistaken for a charge; the available detail also varied by plan and admin access. [1]
The product lesson is not that dollars beat tokens. It is that one field is being asked to represent three different data objects: a meter, an entitlement ledger, and a billing ledger.
The meter is for engineering truth
Input, output, and cache tokens describe resource consumption. They help an engineer find prompt growth, long trajectories, cache misses, and model-level efficiency problems. Removing them would destroy useful operational evidence.
But consumption does not determine payment on its own. The FinOps Foundation's FOCUS v1.3 specification separates Consumed Quantity from Pricing Quantity, then defines Billed, Contracted, Effective, and List Cost as distinct concepts. [2] The separation exists because a measured unit can pass through pricing units, contract terms, discounts, and billing adjustments before it becomes money owed.
An agent meter therefore needs enough provenance to answer four technical questions: what unit was counted, over what scope, under which model or router mode, and at what observation time. It should never label a raw token total as “amount paid.”
The entitlement ledger explains the gap
Most confusion sits between usage and payment. A subscription may include capacity; a team may pool it; a contract may discount it; only the excess may become on-demand spend. Two identical agent runs can therefore create different charges.
Cursor's current Teams page distinguishes included usage from on-demand usage. For users with team-admin access, the current Admin API exposes daily subscription-included and usage-based requests, member spend, and granular usage events. Those events can identify the model, token breakdown, and usage kind. The distinction inside the cost fields matters: totalCents represents model cost, while chargedCents is the event-level charge used to reconcile against spend totals. [3]
GitHub's official billing-reporting guidance provides an independent version of the same pattern. It uses quantity to describe consumption, netAmount for billed cost, and discountAmount for the monetary value covered by an allowance or discount. [4] An entitlement balance still needs its own unit—tokens, requests, credits, or contract currency—rather than being inferred from that discount amount.
The ledger should make five things explicit: opening allowance, consumed allowance, remaining allowance, allowance unit, and included or discounted value. Without it, a dollars-only page can make included value resemble a new charge, while a tokens-only page conceals the approach of an overage.
The billing ledger needs states, not one “cost” column
Even after usage and entitlements are known, money moves through stages:
estimated billable
→ posted or billed
→ invoiced amount due
→ adjusted or refundedA live estimate is not yet an invoice. A posted charge may still be corrected. Only an invoiced amount—or a vendor-defined equivalent final settlement state—should be presented as the amount finally due. Each state needs a currency, payer or billing entity, billing period, and update time.
OpenAI's organization APIs reinforce the object boundary: usage resources return such dimensions as tokens, requests, projects, and users, while a separate costs resource returns a monetary amount with currency and value. [5] That separation does not establish that every live API cost is already a final invoice figure.
Routing adds another moving part. Cursor documents Router for Teams and Enterprise as a changing model pool in which the user cannot select every routed model. Cost mode uses bundled Auto pricing; Balance and Intelligence are billed at the routed model's rate. According to Cursor's current estimate, those two modes cost about twice as much as Cost on average and may be roughly two to four times as expensive depending on the mode. [6] This is a vendor estimate about cost, not an independently measured multiplier for token usage.
That is why multiplying 2.3 million tokens by one public rate can produce a precise-looking but wrong answer. The actual route, entitlement, contract terms, and settlement state all intervene.
A screen should survive six user questions
A product team can review its cost experience without inventing a new FinOps framework. Put a real usage record on screen and ask:
- Can the user see whether the number represents input, output, cache, requests, or converted credits?
- Can the user see what the plan or contract absorbed and in which unit?
- Is estimated billable money visually distinct from a posted or billed charge?
- Does the interface reserve “amount due” for an invoice or equivalent final state?
- Can a team trace the number to a user, project, model, and agent task?
- Does a historical event retain the pricing and routing version that applied at the time?
If answering requires a CSV export plus a private conversion script, the product has exposed records but has not delivered cost control.
The minimum event contract
The sources above do not jointly prescribe one cross-vendor schema. The following is a Research Center synthesis designed to preserve the boundaries they reveal:
usage: input / output / cache quantity + unit
entitlement: unit + included / discounted quantity + included value + balance
billing: estimated billable + posted/billed + invoiced due + adjusted/refunded
money: currency + payer/payee + settlement status + updated time
pricing: model + router mode + pricing version
scope: user + project + work order + request/run id
time: usage time + charge period + billing periodThe contract is valuable because it lets an auditor reconstruct three different answers: what the agent consumed, what commercial terms absorbed, and how far a monetary amount has progressed toward an invoice.
Where this model stops
No live cost screen can promise exact invoice parity before settlement. Refunds, corrections, commitment amortization, negotiated discounts, taxes, and currency conversion may change the result. The responsible design is to display state and freshness, not more decimal places.
Tokens should remain prominent for diagnosis. Monetary estimates should remain prominent for spending decisions. Entitlements should explain the gap between them. The failure is not choosing the wrong one of those three numbers; it is forcing one number to impersonate all three.