how it's built

how the token
chart is built

the ledger turns a raw session log into a stack of bars — one bar per API call. this page walks the exact path it takes: split each call into four token buckets, follow how this turn's reply becomes next turn's cheap history, then watch the numbers line up. the chart is just… drawing them.

1
the one rule

The API has no memory

Each call resends the whole conversation: the system prompt, your tools and skills, then every turn so far — and every prior turn carries both your inputand the model's output. Call 3 ships input1+output1, input2+output2, and the fresh input3 — not just input3. Nothing is remembered server-side; the transcript is the memory, and you pay to ship it every time.

request = [ system + tools + skills ]
          + [ input1 ]
Call 1 ships 1 message. The newest (highlighted) is the only fresh INPUT; the rest is cached history.
2
one call = one bar

Anatomy of a single call

Resending the whole transcript every call would be brutal at full price — so providers let you mark the stable prefix as cacheable. The first time the provider sees a chunk, they store it (a small one-time surcharge: a CACHE WRITE). Every later call that resends the same prefix gets billed at a fraction of the normal rate (a CACHE READ). The full transcript still gets shipped every time — it's just billed at different rates depending on whether the provider has already seen it. So every call splits into four token buckets:

Cache read
settled history the provider already has on file — cheapest lane
Cache write
material being stored for the first time — usually the previous turn, now stable
in
genuinely new tokens this call — your latest message, full input price
output
thinking + reply — the most expensive lane per token

Widths ≈ token volume. The cache breakpoint slides forward each turn, promoting yesterday's WRITE into today's READ — so most of every resend rides in the cheap READ lane while only your new message pays full input price. Stack these four on top of each other and you have one bar in the chart.

3
the chain

This turn's WRITE = next turn's READ

Turn 1
Cache read: cold
Cache write: turn 1
Turn 2
Cache read: turn 1
Cache write: turn 2
Turn 3
Cache read: turns 1–2
Cache write: turn 3

History keeps accruing in the cheap READ lane — each turn just hands its WRITE down to the next.

4
walk it through

A real session, step by step

Turn 1cold start
what this one API call carries
readnothing cached yet — cold start
writesystem prompt + tool defs + skill listcached now
inputHi!

Your message is queued as fresh INPUT, on top of the cached READ and WRITE — nothing’s generated yet. Hit run to add the OUTPUT.

session transcript
Hi!
▍ generating reply…
you = input reply = output
the chart, building — one stacked bar per call, growing as you step
input cache read cache write output
5
fine print

Gotchas worth remembering

  • Attachments (files, tool results) land in CACHE WRITEdirectly, not INPUT— they're the big spikes.
  • Thinking blocks are carried forward into later turns and cached too, not just the output text.
  • One API response = several transcript lines sharing one message.id and one usage record. Dedup by message.id before summing, or you double-count.
  • A new session does not mean a cold cache — caching is keyed on the content prefix, not the session.