skip to content

Usage, Cost & Caching

Plan limits vs API billing, /usage, automatic prompt caching and the actions that bust it, and OpenTelemetry for teams. Asked because long sessions, model switches and subagents multiply tokens.

part ofClaude Coderead it →
on this pageshow

explore

questions

5

In Claude Code, what does /usage (alias /cost) report, and what does its dollar figure mean on a Pro plan versus an API key?

level: juniorimportance: must knowfreq 22%

answer

  1. two kinds of payer
  2. Session block vs plan bars
  3. computed locally at list price
  4. Console Usage page is authoritative
  5. usage credits past the limit

basics

~20 s

Claude Code's /usage shows session token counts, a locally estimated dollar cost and, on Pro, Max, Team or Enterprise, plan usage bars. API-key users pay per token; subscribers draw on plan limits, so that dollar figure is not their bill.

solid answer

~50 s

`/usage` (aliases `/cost` and `/stats`) opens with a Session block: total cost, durations, lines changed and tokens per model split into input, output, cache read and cache write. Claude Code computes that cost locally at list price — or at contracted rates when an admin sets `modelPricing` in managed settings — so it is an estimate; the Claude Console's Usage page is authoritative. On an API key or a cloud provider the figure tracks real per-token spend. On Pro and Max, usage is included in the plan, so the figure is not relevant for billing; what matters are the plan usage bars and the breakdown attributing recent usage to skills, subagents, plugins and MCP servers. Past the plan limit you wait for the reset or turn on usage credits with `/usage-credits`, which are billed, and `/usage` then shows a usage-credits row.

go deeper

for a junior

Recall that /usage, /cost and /stats open the same screen, that the Session block shows tokens and an estimated cost, and that a subscriber's plan bars matter more than the dollar figure.

for a middle

Explain how the cost is computed: local token counts priced at list price unless managed modelPricing applies, split into input, output, cache read and cache write, reset by /clear.

for a senior

Show you can triage a limit complaint: session and weekly limits are model-agnostic, family limits are not, usage credits are billed, and the breakdown only sees this machine.

for a principal

Frame the number for the payer: per-token billing makes the figure a budget signal, a subscription makes the allowance the constraint, and usage credits turn a flat plan back into metered spend.

## What `/usage` is `/usage` is Claude Code's built-in command for **what a session has consumed and how much of your plan is left**. `/cost` and `/stats` are aliases for it (`/stats` opens on the Stats tab). The screen has two halves that answer different questions: - the **Session block** — tokens and an estimated dollar cost for the current session; - the **plan section** — on a Pro, Max, Team or Enterprise plan, usage bars against your plan limits, activity stats and a breakdown of what used them. Which half matters to you depends entirely on **how your Claude Code access is paid for**. ## The Session block: tokens and an estimated cost The Session block lists total cost, API duration, wall-clock duration, lines added and removed, and usage per model split into **input, output, cache read and cache write** tokens: ``` Total cost: $0.55 Total duration (API): 6m 20s Total duration (wall): 6h 33m 10s Usage by model: claude-sonnet-4-6: 1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55) ``` Three facts about that dollar figure: 1. **It is computed locally** from token counts at **list price**. Claude Code does not fetch it from your bill. 2. An administrator can make it use **contracted rates** with the `modelPricing` key in managed settings; the `Total cost` line then carries the note `at your organization's configured rates`. It is still an estimate. 3. The authoritative record for API billing is the **Usage page in the Claude Console**, not `/usage`. `/clear` starts a new session, and the Session block's totals start again from zero. ## Two ways of paying, two meanings of the number | How you are signed in | What you pay for | What the `/usage` dollar figure means | | - | - | - | | Claude Console account or API key | Every token, billed to the organization | A close estimate of real spend | | Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry | Every token, billed to your cloud account | An estimate; the cloud billing console is authoritative | | Pro or Max subscription | A flat plan with included usage | Not your bill — the plan bars are what matter | | Team or Enterprise seat | A per-seat allowance | Not your bill unless usage credits are drawn | The docs say this directly: the Session block is intended for API users, and for Pro and Max subscribers the session cost figure "isn't relevant for billing purposes". A subscriber who panics at `Total cost: $40` has misread the screen. ## Plan limits and usage credits Subscription plans include a **rolling usage allowance** with a session window and a weekly window, and usage counts against both at once. On Team and Enterprise the allowance is per seat, resets on a rolling five-hour window and a weekly window, and is shared with Claude chat and Cowork. When an allowance runs out, Claude Code blocks requests until the reset time in the message: - `You've hit your session limit` and `You've hit your weekly limit` are **shared across all models**, so `/model` does not restore access. - `You've hit your Opus limit` or `You've hit your Sonnet limit` apply to one model family, so switching outside that family with `/model` keeps you working. **Usage credits** let you keep working past the plan limit, and that usage **is billed**. `/usage-credits` manages them after signing in with a claude.ai subscription; it is not available with API key authentication. For Pro and Max it opens the claude.ai usage settings; a Team or Enterprise member without billing access sends a request to the admins instead. While usage credits are on, `/usage` shows a usage-credits row with this month's spend against any spend limit. ## The plan usage breakdown On Pro, Max, Team and Enterprise, `/usage` also explains where the allowance went: - **Attribution** — recent usage attributed to skills, subagents, plugins and individual MCP servers, as percentages; - **Behavior flags** — long context or cache misses, flagged when one accounts for 10% or more of recent usage, each with a tip; - **Loops** — the heaviest `/loop` and other scheduled tasks, with run counts and tokens per run. Press `d` or `w` to switch between the last 24 hours and the last 7 days. These figures are **approximate and computed from local session history on this machine**, so usage from other devices or claude.ai is not included. ## Common misreadings - Treating the Session block's dollar total as a subscriber's invoice. - Expecting the figure to equal the Console bill to the cent; it is a list-price estimate. - Switching models to escape a session or weekly limit. - Reading the breakdown as account-wide when it only sees this machine.

  • Why does switching to Sonnet rescue a subscriber after one limit message but not after another?
    `You've hit your session limit` and `You've hit your weekly limit` are shared across all models, so `/model` changes nothing until the reset. `You've hit your Opus limit` or `You've hit your Sonnet limit` cover one model family, so switching outside that family with `/model` keeps the developer working — at the price of one uncached turn, because each model has its own prompt cache.
  • An organization pays contracted rates and `/usage` disagrees with the invoice. What do you change?
    Set the `modelPricing` key in managed settings with the contract's per-model rates or a multiplier. Claude Code then computes `/usage`, the status line and OpenTelemetry cost figures at those rates and marks the `Total cost` line `at your organization's configured rates`. It changes what Claude Code reports, not what Anthropic charges, and it is ignored in user, project and local settings.
  • How far can you trust the plan usage breakdown in `/usage`?
    As a local, approximate picture. It attributes recent usage to skills, subagents, plugins and MCP servers, flags behaviours over 10% of usage and lists heavy loops, over 24 hours or 7 days (`d`/`w`). It is computed from session history on this machine, so work on another laptop or on claude.ai is not in it.

  • The /usage dollar total is what a Pro or Max subscriber gets charged.
  • The /usage cost comes from the Claude Console, so it matches the invoice exactly.
  • Switching models with /model gets you past a session or weekly plan limit.
  • The /usage breakdown includes usage from claude.ai and your other machines.
  • /usage-credits works the same with an API key as with a subscription.
open as a page

What does the 'Prompt cache (main)' line in Claude Code's /usage report, and how do you act on its misses?

level: middleimportance: should knowfreq 8%

basics

~20 s

Claude Code's /usage adds a Prompt cache (main) line from v2.1.251: requests, the share of input tokens served from cache, misses with tokens re-cached, expected rebuilds from compaction, and whether the cache is warm. It covers the main conversation only.

open as a page

After running /model mid-session, a Claude Code turn is slow and costly; which mid-session actions invalidate its prompt cache, and which do not?

level: seniorimportance: should knowfreq 14%

basics

~20 s

Each model has its own cache, so /model makes the next request reprocess the whole history. Turning on fast mode, compaction and changed tool definitions also invalidate it; editing files or CLAUDE.md, switching permission mode, invoking skills and spawning subagents keep it.

open as a page

Which prompt-cache TTL does Claude Code use by default on a subscription versus an API key, and when would you set promptCacheTtl to 1h?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Claude Code requests a one-hour TTL for the main conversation only on a subscription within plan usage; on usage credits, an API key or a cloud provider it is five minutes, as are subagents. promptCacheTtl "1h" (v2.1.242+) buys the hour for idle-prone sessions.

open as a page

A team lead finds one developer's Claude Code spend tripled in a week; how would you set up per-user cost visibility and caps for the whole team?

level: principalimportance: nice to knowfreq 7%

basics

~20 s

Match caps to how the team pays: seat allowances plus usage-credit spend limits on Teams or Enterprise, workspace spend limits on the Console, cloud budgets on Bedrock, Agent Platform or Foundry. For per-user visibility everywhere, push OpenTelemetry export through managed settings.

open as a page