Claude Code cost and usage: /cost, /usage, rate limits and what actually saves money

Claude Code Published:

How Claude Code billing works on a subscription versus API usage, checking consumption with /cost and /usage, how the rate limits behave, and the habits that cut token spend.

Verified on Sep 7, 2026 These tools change quickly. Please also check the latest official documentation. How articles are researched and verified
Contents
  1. The two ways to pay
  2. Checking your usage
    1. /cost (for API billing)
    2. /usage (for subscriptions)
    3. The Console dashboard (API)
  3. How the rate limits behave
  4. What actually saves money
    1. 1. Match the model to the task
    2. 2. Keep the context short
    3. 3. Narrow what gets read
    4. 4. Cap non-interactive runs
    5. 5. Work with the prompt cache
  5. Managing cost across a team
  6. Summary

What Claude Code costs depends on which of two paths you're on. A subscription is a fixed amount with usage limits; the API has no ceiling but bills what you use. Either way, the habits that reduce waste are the same.

This article covers the two models, the commands for checking consumption, how the rate limits behave, and the savings that actually move the number. Prices and limits get revised, so treat the official pricing page as current.

KEY POINT

What you will learn

  • Subscription versus API billing, and how to pick
  • /cost, /usage, and the Console's usage view
  • Savings from model choice, context hygiene and non-interactive limits

The two ways to pay

ModelWho it's forBillingLimits
SubscriptionPro / Max for individuals, Team / Enterprise for organizationsFixed monthlyA limit per multi-hour window and a weekly limit
API usageAn Anthropic Console API keyPer input and output tokenNo ceiling; budget alerts available in the Console

Claude Code works out which one applies from how you signed in. /status tells you which is active.

Choosing between them:

  • Several hours a day favors a subscription, Max in particular: hitting the limit never produces an extra bill
  • A few short sessions a week is usually within Pro
  • CI, automation, or wanting per-team usage visibility favors the API

用語解説

Max tiers: Max comes in tiers with several times Pro's limits. If you lean on Opus-class models all day, the lower tiers reach their limit quickly.

Checking your usage

/cost (for API billing)

Shows what the current session has spent in USD, the input and output token counts, and elapsed time. On a subscription the dollar figure is indicative only.

/cost

/usage (for subscriptions)

Shows how much of your current limit you've consumed and how long until it resets. This is the one for "how much have I got left".

/usage

The Console dashboard (API)

The Usage view in the Anthropic Console breaks consumption down by day, by model and by API key. For team use, separate keys per purpose make the breakdown meaningful. Budget caps and alerts are configured there too.

How the rate limits behave

A subscription has a limit for concentrated use within a multi-hour window, plus a weekly limit. Reach it and Claude Code is unavailable until the reset.

What burns through a limit fastest:

  • Running an Opus-class model for everything
  • Re-reading huge files or logs repeatedly
  • Long sessions never cleared, since the history is resent every turn
  • Many subagents or parallel sessions at once

API billing has its own per-minute request and token limits. If you run things in parallel in CI, check your tier's limits in the Console first.

What actually saves money

1. Match the model to the task

/model switches mid-session. Routine fixes, adding tests and documentation updates are usually fine on a Sonnet-class model; reserving Opus-class for design decisions and hard debugging cuts consumption substantially.

/model claude-sonnet-5

Subagents can pin their own model in their definition file — see Claude Code subagents.

2. Keep the context short

Conversation history is resent on every request. Using /clear at task boundaries and /compact when a session gets long reduces the tokens per request on its own — see Managing context in Claude Code. A bloated CLAUDE.md costs you for the same reason.

3. Narrow what gets read

Ask for "20 lines either side of the error" rather than "read the log". Writing an instruction in CLAUDE.md to exclude generated trees such as node_modules and dist from searches helps too.

4. Cap non-interactive runs

For automation, limit the loop with --max-turns and record total_cost_usd from --output-format json — see Running Claude Code in CI.

5. Work with the prompt cache

Claude Code uses prompt caching internally so the repeated parts of a request, such as the system prompt and CLAUDE.md, cost less. Rewriting CLAUDE.md constantly undercuts that, so batch its edits rather than tweaking it mid-session.

Managing cost across a team

  • Separate API keys by purpose and read the breakdown in the Console
  • Set budget alerts so an unexpected climb surfaces early
  • Set a Sonnet-class default model in .claude/settings.json and let individuals switch with /model
  • Compare monthly: per-seat subscriptions often come out cheaper than API usage for the same work

Summary

  • Two models: a subscription with limits and no overage, or API billing with no ceiling
  • /cost for money, /usage for how much of the limit is left, the Console for day and key breakdowns
  • The basics of saving are model choice, /clear and /compact, and narrowing what gets read
  • In automation, --max-turns plus the JSON cost field stops a run from getting away from you

FAQ

What do I need to use Claude Code?
Either a subscription such as Claude Pro or Max, or an API key from the Anthropic Console billed per token. The free plan doesn't include it.
Why does a subscription stop working mid-session?
Subscriptions have usage limits per window and per week. They reset after a period; /usage shows how much is left and when.
On API billing, what does one session cost?
It varies widely by task and model. /cost shows the figure for the current session, so work from your own numbers rather than an estimate.

Questions & answers

Q. The output feels needlessly long and I suspect tokens are being wasted. How do I see what is actually consuming them, and can I rein the output in?

Answer by the editorsSource: GitHub anthropics/claude-code Issue #103616

Start by measuring rather than guessing. /usage gives you the breakdown.

The Session block at the top shows token statistics for the current session. The dollar figure is computed locally from token counts at list price, unless your organization has a modelPricing table in effect, in which case the Total cost line carries the note at your organization's configured rates. For authoritative billing, use the Usage page in the Claude Console.

On a Pro, Max, Team or Enterprise plan, the same screen also breaks down what counts against your plan limits.

SectionWhat it shows
AttributionRecent usage attributed to skills, subagents, plugins and individual MCP servers, each as a percentage
Behavior flagsBehaviours such as long context or cache misses, flagged when one accounts for 10% or more of recent usage
LoopsThe heaviest /loop or other session-scoped scheduled tasks that ran recently, ordered by total tokens

If long output is the complaint, check first whether Behavior flags shows long context, and whether Attribution puts one MCP server or subagent far ahead of the rest. An MCP server's tool definitions consume context simply by being connected, so a large share there is common.

No documented setting caps comment volume

As of 2026-10-21 there is no settings key in the reference for "write fewer comments" or "be less verbose". The place to put that instruction is CLAUDE.md, and it works better as a concrete standard — "comment only where the intent is not obvious from the code" — than as a bare "be concise".

CLAUDE.md is reloaded from disk at session start and after compaction. An overlong file dilutes its own instructions; see How long should CLAUDE.md be for the sizing guidance.

For the levers that actually reduce spend, and how the plan limits behave, see Claude Code cost and usage with /cost and /usage.

Q. A single code review consumed about 5% of my weekly usage allowance. Is one task really supposed to cost that much?

Answer by the editorsSource: GitHub anthropics/claude-code Issue #101620

The documentation has a section called "Why usage climbs in a long session", and a code review hits most of the conditions in it.

The dominant one is context length: "Claude Code sends your full conversation with every request, and each time Claude uses tools it sends another request carrying that batch of tool results." A review reads file after file, so each tool call is another request — and that request carries the whole conversation, including every file read so far. Consumption therefore grows faster than linearly in the number of files reviewed.

Next is cache misses. The prompt cache lifetime is one hour on a subscription, dropping to five minutes once you are drawing on usage credits. Your first message after a longer break reprocesses the full context.

If subagents were involved, each sends its own requests on top of the main conversation. Agent teams are heavier still: teams whose teammates run in plan mode use approximately 7x the tokens of a standard session.

To see which of these actually applied, run /usage. On Pro, Max, Team and Enterprise it flags behaviors that account for 10% or more of recent usage — long context and cache misses among them — and d / w switch between the last 24 hours and the last 7 days.

What the documentation suggests for next time:

  1. /clear when switching to unrelated work. /compact reads the conversation it summarizes, so it is itself a large request
  2. Delegate verbose operations to subagents, so the output stays in their context and only a summary returns
  3. Lower the effort level with /effort or in /model — thinking tokens are billed as output tokens
  4. Match the model to the job: Sonnet handles most coding work and costs less than Opus

注意

Whether that 5% is correct for your plan is not something the documentation can settle, since per-plan limit figures are not published there. For an account-specific billing question, the documented route is to sign in at claude.ai, click your initials in the lower left, and select Get help.

More detail: Check Claude Code usage and cost.

Q. I am on Max and used Fable 5.1 at high effort, and after about 24 hours it said I had exhausted my weekly limit. Is that correct, and which model and effort should I use to keep working?

Answer by the editorsSource: GitHub anthropics/claude-code Issue #100094

The "weekly limit" message is a plan-side usage window that is shared across models. The official documentation describes it as "a seat-based usage window on a subscription plan, shared across all models, so the developer can't restore access by switching models with /model." Only the model-specific messages — "You've hit your Opus limit" or "You've hit your Sonnet limit" — can be worked around by switching to a model outside that family.

Whether the window you got is the right size for your plan is not something the documentation can settle. Per-plan limit figures are not published in the docs; they point to the pricing page and the Help Center instead. For an account-specific billing question, the documented route is to sign in at claude.ai, click your initials in the lower left, and select Get help.

What the docs do explain is why usage climbs faster than your activity suggests. Claude Code sends your full conversation with every request, so a one-line question in a session that has been open all day still draws usage for the whole conversation. The prompt cache lifetime is one hour on a subscription, and your first message after a longer break misses the cache and reprocesses the full context.

The documented ways to stretch the allowance:

  1. Run /usage. On Pro, Max, Team and Enterprise it flags behavior flags — behaviors such as long context or cache misses that account for 10% or more of recent usage. Press d or w to switch between 24 hours and 7 days.
  2. Lower the effort level with /effort or in /model. Thinking tokens are billed as output tokens. Note that you cannot turn thinking off on Opus 5.5, Sonnet 5.5, Haiku 5.5 or the Fable models.
  3. Match the model to the job. Sonnet handles most coding tasks and costs less than Opus; reserve Opus for complex architectural decisions and multi-step reasoning.
  4. Run /clear when switching to unrelated work. /compact reads the conversation it summarizes, so it is itself a large request.
  5. If you use agent teams, use fewer teammates. Teams whose teammates run in plan mode use approximately 7x the tokens of a standard session.

Once you are at the limit, /usage-credits requests usage beyond the allowance (it isn't available with API key authentication). On Claude Code v2.1.234 or later you can also wait for the reset and have the interrupted task continue automatically, selectable from /rate-limit-options.

More detail: Check Claude Code usage and cost.

Q. Token usage is still high on Sonnet 5.5 even with reasoning set to low. Why?

Answer by the editorsSource: GitHub anthropics/claude-code Issue #99496

Two reasons.

1. Extended thinking cannot be turned off on Sonnet 5.5. The model configuration documentation says so directly:

You can't turn thinking off on Opus 5.5, Sonnet 5.5, or the Fable models.

The same passage adds that on these models the session toggle and the /config row read Thinking can't be turned off, and that a saved alwaysThinkingEnabled: false or MAX_THINKING_TOKENS=0 has no effect there. Sonnet 5.5 always uses adaptive reasoning, where the effort level is the primary control over how much thinking happens.

ModelEffort levels
Opus 5.5, Sonnet 5.5, Opus 5, Sonnet 5, Opus 4.8, Opus 4.7low, medium, high, xhigh, max
Opus 4.6, Sonnet 4.6low, medium, high, max

Run /effort with no arguments for a slider, /effort low to set it directly, or /effort auto to clear the level saved for the active model.

2. In a long session the cost driver is context, not thinking. Claude Code sends the whole conversation with every request, and each time it uses tools it sends another request carrying those results. The documentation's "Why usage climbs in a long session" names long context, cache misses, scheduled tasks, subagents and compaction as the causes:

a one-line question in a session that has been open all day still draws usage for the whole conversation

Lowering effort does nothing about that part. What does:

ActionEffect
/clear between tasksDrops the conversation history from later requests
/compact when a session runs longSummarizes history, cutting tokens per request
Narrow what gets readAsk for "20 lines either side of the error", not "the log"
Match the model to the taskSend routine work to a lighter model

On Pro, Max, Team and Enterprise plans, /usage flags any behavior accounting for 10% or more of your recent usage, such as long context or cache misses. That is the fastest way to see which one is actually costing you. The full picture is in Claude Code cost and usage.

Q. Why can't I use my credit in Claude Code?

Answer by the editorsSource: GitHub anthropics/claude-code Issue #99337

The thing to establish first is that Claude Code has two billing paths, and credit means something different on each. /status tells you which one your session is on.

PathBillingWhat credit applies
A claude.ai subscription (Pro / Max / Team / Enterprise)Monthly, with a per-seat allowance"Usage credits", which let you keep working past the allowance
A Claude Console API keyPer tokenYour Console account balance

Usage credits are the subscription-side mechanism. Per the documentation, you manage them by signing in to your claude.ai subscription with /login and then running /usage-credits. The important line:

the command isn't available with API key authentication

So a session running on an API key cannot reach the usage-credits screen at all, and a session signed in with a subscription does not draw down a Console balance. When credit appears to exist but is never used, the usual cause is that the credit sits on one path while the session authenticates on the other.

What /usage-credits opens depends on your role:

Your roleWhat it does
Pro or MaxOpens Settings > Usage on claude.ai, where you turn usage credits on or off and see your balance, this month's spend, and your monthly spend limit
Team or Enterprise with billing accessOpens Organization settings > Usage
Team or Enterprise without billing accessAsks you to confirm, then sends a request to your organization's admins

One caveat: the term "promotional credit" could not be found in the official documentation. Where a promotional balance can be spent depends on the terms it was granted under. For billing questions about a specific account, the docs point to support: on a subscription, sign in at claude.ai, click your initials in the lower left and choose Get help; for Console billing, do the same at platform.claude.com.

For the two billing models and how to read your usage, see Claude Code cost and usage.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.