Reading the Usage Object from a Codex Request

Every estimate on this site — every calculator, every planning tool — is a prediction. The usage object a real API response returns is the one number that isn't: it's what the request actually cost, reported by the system that billed it, and it's worth learning to read closely rather than skimming past on the way to the response content you actually asked for.

What's actually in it

Token counts, broken down by kind — input tokens sent, output tokens generated, and where caching is in play, cached_tokens for a read that hit a warm prefix and cache_write_tokens for a prefix newly written into the cache on this request. Those last two are the detail most people skip past, and they're exactly the numbers that tell you whether your caching strategy is actually working the way you designed it to, rather than just assuming it is because you set a prompt_cache_key.

Why this is the real check on every estimate

A calculator on this site — the token-cost estimator, the caching savings calculator — is only as accurate as the assumptions you fed it: an estimated token count, an assumed cache-hit pattern. The usage object closes that loop with ground truth. If a request's actual cached_tokens count is consistently lower than what you assumed when estimating, that's not a bug in the estimator — it's a sign your prefix isn't matching as reliably as you expected, and it's worth investigating why before trusting future estimates built on the same assumption.

Reading the rate-limit headers alongside it

The usage object tells you what one request cost; the response headers alongside it tell you how much room you have left before the next one gets throttled — remaining requests, remaining tokens, and when each resets. For anything running close to a rate-limit ceiling, checking these headers periodically is a more direct signal than waiting for an actual 429 to find out you were close.

Logging usage over time, not just per request

A single request's usage object is a snapshot; the pattern across many requests over time is what actually tells you whether a workload's real cost matches what you planned for. This site's usage tracker exists specifically for that — copying real usage figures into a running local log, rather than re-estimating from memory, turns the usage object from a one-off check into an ongoing budget signal.

What it won't tell you

The usage object reports what happened, not why — it won't tell you that a request crossed the long-context repricing threshold, only the token counts that determine whether it did. Cross-referencing a request's actual input token count against a model's published threshold, using the context-window planner, is a separate step the usage object alone doesn't do for you, even though it's the object that gives you the real number to check.

A habit worth building early

Checking the usage object on a handful of real requests early in building any new workflow — rather than only checking it after a bill looks surprising — is the cheapest way to catch a mismatch between what you assumed a request would cost and what it actually did, while the workflow is still small enough that fixing a wrong assumption is easy. Waiting until a monthly invoice surfaces the gap means diagnosing the mismatch across however much volume accumulated in the meantime, which is a much harder problem to work backward from.

Different fields for different tiers

Not every field in a usage object is populated the same way across every service tier — a Batch request's usage reporting and a Standard synchronous request's usage reporting don't necessarily carry identical fields, since the two have genuinely different delivery mechanics. Checking the current API reference for the specific endpoint and tier you're calling, rather than assuming a Standard request's usage shape applies everywhere, is worth doing once per integration rather than assuming.

Building a lightweight internal log from it

For any workload calling the API programmatically rather than through the interactive CLI, logging the usage object alongside a timestamp and whatever identifies the call — which endpoint, which internal feature, which user or project — is a small addition that pays for itself the first time someone asks "why did the bill jump last month." Without that log, answering that question means reconstructing usage after the fact from an invoice that has far less granularity than the usage objects you already had and discarded in real time.

Usage objects and multi-step agentic sessions

An agentic session that makes several requests to answer one overall task produces several usage objects, not one — and the sum of those, not any single request's figure, is the real cost of that task. It's easy to glance at one request's token count mid-session and assume that's representative of the whole task's cost, when a long agentic loop might make many more calls than that single glance suggests. Summing the usage objects across an entire session, not sampling one, is the only way to get an honest total.

Why this page exists separately from the estimator tools

Every calculator on this site prices a hypothetical request before you send it. This page is about the one thing none of them can do: tell you what a request actually cost after the fact, from the system that actually billed it. Both matter, at different points in a workflow — plan with the calculators, verify with the usage object, and treat a persistent gap between the two as a signal worth investigating rather than dismissing.