What API Value Actually Means

A local AI coding report can show a dollar number without knowing what the user paid.

That sentence is the accounting rule behind Agent Island's API value label. The app can read token records from Claude Code and Codex, identify the model, and apply a dated table of API rates. It cannot reconstruct a subscription invoice, credits, overage terms, taxes, enterprise discounts, or a provider's internal quota economics from those records.

Calling the result cost without qualification invites the wrong conclusion. Calling it savings is worse. The defensible number is a counterfactual: what the recorded token activity would be worth if each token category were priced at the table's API rates. This article covers the macOS implementation released in Agent Island v1.6.1.

The formula

Each normalized event keeps input tokens, output tokens, cache-creation tokens, and cache-read tokens. The estimate for one event is:

API value =
  input / 1,000,000 * input rate
  + output / 1,000,000 * output rate
  + cache creation / 1,000,000 * cache-creation rate
  + cache read / 1,000,000 * cache-read rate

The rates are tied to a named model after canonicalizing date-pinned model identifiers. The v1.6.1 embedded snapshot is dated 2026-07-13.

Suppose a hypothetical event has 2 million input tokens, 0.5 million output tokens, and 10 million cache-read tokens. At rates of $3, $15, and $0.30 per million, its API value is:

2 * $3 + 0.5 * $15 + 10 * $0.30 = $16.50

That is a pricing-table result. It does not say the user paid $16.50.

Cached input needs provider-specific handling

Claude Code records cache creation and cache reads as distinct usage fields. They can flow directly into the normalized event.

Codex's local record reports cached input as part of total input. Pricing the total input and then adding cached input again would charge the cached portion twice. The parser first computes:

non-cached input = total input - cached input

It then applies the normal input rate to the non-cached portion and the cache-read rate to the cached portion. A generic input * rate function does not have enough context at the file boundary.

API value and token volume answer different questions

The report keeps a wire-token total that includes input, output, cache creation, and cache reads. It also keeps an input/output total without cache activity. Neither is interchangeable with API value.

Ten million cache-read tokens can dominate volume while carrying a much lower dollar estimate than a smaller amount of output from an expensive model. Ranking model rows by token count and labeling the result as value would mix two measures. The weekly report ranks models by estimated API value while showing wire tokens as the activity headline.

Why the estimate can be incomplete

An embedded rate table always has a maintenance boundary. New named models can appear in logs before the table contains them. In v1.6.1, a named model without a price produces zero estimated value rather than inheriting a guessed rate. The aggregate records that the model was unpriced so the UI can warn the user.

Prices also change. The snapshot date must travel with the calculation, and old reports should be understood as estimates made with the rates available to that build. The current implementation also does not apply Anthropic's special long-context pricing tier, so a qualifying request can differ from the displayed estimate.

What API value is allowed to mean

API value can support narrow statements: the local logs contain token activity with an estimated API value under a named price snapshot; one model accounts for a larger share of that estimate than another; and the estimate uses separate rates for token categories where available.

It cannot support claims that the user spent, saved, or earned that amount. Actual spend comes from receipts, billing exports, credit balances, and contract terms. A local token ledger has none of those by default.

A useful number needs a visible definition

The UI label uses an approximation sign and the words API value. Product documentation and shared images need the same distinction.

The number still has a job. It makes cache-heavy usage visible, gives per-model activity a common unit, and lets a developer compare periods under one explicit rate snapshot. Its value comes from a stable definition, not from sounding like an invoice.

When an estimate can be mistaken for money paid, the explanation is part of the feature. Put it next to the number, date the rates, warn about unknown models, and keep the claim inside what the local records can prove.

Agent Island is an open-source status companion for Claude Code and Codex. Read the source or star the repository on GitHub.