Claude Code usage: limits, monitoring, and quota management

Subscription or API key: what meters your Claude Code usage

Claude Code works the same either way. What changes is what you pay, which limits apply, and whether your chats on claude.ai feel it.

If both are set up, the API key wins once you approve it. The first time an interactive session finds ANTHROPIC_API_KEY in your environment, Claude Code asks whether to use it and remembers your answer; the “Use custom API key” toggle in /config changes it later. Run /status to see which credential a session is using, and unset ANTHROPIC_API_KEY before starting Claude Code to go back to your subscription.

Checking usage in the terminal: /usage, /cost, and /stats

Run /usage in any Claude Code session. /cost and /stats open the same screen, and it runs straight away even while Claude is in the middle of a response. On a Pro plan it looks roughly like this:

The screen has up to four parts:

• Session. Tokens by model (input, output, cache reads, cache writes), time, lines changed, and a dollar figure Claude Code works out locally at API list prices. On a subscription that figure isn't a charge; it's what the same tokens would cost on the API.
• Plan usage. Your 5-hour session and weekly limits as percentages, with reset times. These are account-wide, so they include what you've used in Claude on the web and desktop.
• Usage breakdown (Pro, Max, Team, and Enterprise). Recent usage split across skills, subagents, plugins, and individual MCP servers; flags for behaviors such as long context or cache misses once one accounts for 10% of recent usage; and rows for your heaviest /loop and scheduled tasks. Press d or w to switch between the last 24 hours and the last 7 days. It's built from session history on this machine, so other devices and claude.ai aren't in it.
• Usage credits, when they're on: this month's spend against your limit.

The breakdown is the closest Claude Code comes to telling you what's eating your allowance. If one MCP server or a scheduled loop has a large share, start there. Settings › Usage, the statusline, and the desktop app show the same limits elsewhere, and how to check your Claude usage compares all of them.

Plan usage, context, and session cost are different numbers

Claude Code puts three numbers in front of you, and they move for different reasons. It's easy to take one for another: to expect /clear to give allowance back, or to read the dollar figure in /usage as a bill.

Context and plan usage are separate meters, but they're linked. A full context window doesn't mean you're out of allowance; what it does is set the size of every request. Claude Code sends the whole conversation each time, so a conversation at 80% of a 200,000-token window carries about 160,000 tokens into every request, most of them read from the prompt cache. Keep context small and the plan meter climbs more slowly.

On an API key, the session cost is a fair guide to what you'll be billed, though the Anthropic Console's usage page is the authoritative figure.

Claude Code usage limits by plan

Every paid plan includes Claude Code. What changes is how big the allowance is and who it belongs to: you alone on Pro and Max, each member's seat on Team and seat-based Enterprise. The usage limits reference has every plan's figures and sources; this is the Claude Code view.

The session limit runs on a rolling five-hour window, and the 5-hour limit guide explains how that window works and why coding sessions reach it sooner than chat.

Keeping an eye on usage while you work

/usage answers the question when you ask it. These keep the answer in view, or keep a record of it.

Why Claude Code drains limits faster (and how to slow it down)

A chat message is usually one request to the model. A Claude Code task is a loop: Claude reads a file, runs a command, reads the output, edits, runs the tests, and each step is another request. Every one of those requests carries the whole conversation so far, including every file and command output Claude has already read. On turn 10, Claude re-processes the files loaded during turns 1 through 9.

Prompt caching keeps that from being as bad as it sounds, because most of the repeated history is read from cache at a fraction of the fresh-input price. But cached isn't free. Anthropic's cost guide makes the same point: a short question late in an all-day session is still charged for the whole conversation behind it.

Other things that add up

• Subagents. Each subagent starts with its own context window and sends its own requests, which count against the same limits as your main conversation. By default up to 20 can run at once, nested up to three layers below the main conversation, and the /usage breakdown shows their share. They can also protect your main context: a subagent that runs the test suite keeps the output and hands back a summary.
• Command output. Commands like npm test, cargo build, or a large git diff can produce thousands of lines. Whatever Claude reads becomes part of the conversation and rides along with every later request.
• Model choice. Opus costs more per token than Sonnet. In our test, the same task cost about 0.21 times as much on Sonnet 5.5 as on Opus 5.5, both at high effort, in API-equivalent dollars. Anthropic doesn't publish how model choice weighs on the 5-hour and weekly meters, though some accounts also have a separate Opus or Sonnet limit. The Opus 5.5 and Sonnet 5.5 pages cover each model's limits and effort settings.
• Coming back after a break. On a subscription the prompt cache lasts an hour, or five minutes once you're drawing on usage credits. The first message after a longer break reprocesses the whole conversation without the cache discount.
• Work that runs while you're idle. Scheduled tasks and /loop jobs send your full context every time they fire, whether or not you're typing.

To see how fast your own allowance is going before you change anything, the burn rate calculator projects whether you'll hit the 5-hour or weekly limit before it resets.

What to do when you hit a Claude Code limit

Claude Code tells you which limit stopped it and when it resets, with a message such as You've hit your session limit · resets 3:45pm. Work through these in order:

1. 1
   Find out which limit you hit

   The message, or /usage, tells you whether it's the 5-hour session limit, the weekly limit, or a model-specific Opus or Sonnet limit. Session and weekly limits cover every model, so switching models won't help. A model-specific limit covers only that family: run /model, pick a model outside it, and keep working, though the next request rereads the conversation without a warm cache. A session limit clears within five hours; a weekly limit waits for your account's reset day. Both are covered in when Claude usage resets.
2. 2
   Let Claude Code wait for the reset

   On a claude.ai subscription, Claude Code 2.1.234 and later can wait in an interactive session and continue the task after a usage limit resets. It starts waiting automatically when that setting is enabled and the reset is within 24 hours. If a weekly reset is farther away, run /rate-limit-options and choose “Wait here, then continue automatically” to start waiting yourself. Keep the session open; press Esc to cancel. Automatic waiting is not available in API-key or non-interactive sessions. The options menu also offers usage credits and plan upgrades.
3. 3
   Check whether /limit-reset is available

   If a session limit stopped you, try typing /limit-reset. It isn't in Anthropic's public command reference, it may not appear in the command menu, and nothing guarantees your account has a reset to use. When it works, your 5-hour session unblocks immediately. In every public report so far it has cleared only the 5-hour limit, and its output says your weekly limit still applies. The /limit-reset guide covers what's been observed.
4. 4
   Continue with usage credits

   If your plan allows it, run /usage-credits. Pro and Max subscribers are taken to Settings › Usage; Team and Enterprise members with billing access are taken to organization usage settings; members without billing access can send a request to their admins from the CLI. Once credits are on, Claude Code keeps working past the included allowance at standard API rates while the plan window counts down to its reset. The command isn't available when you're signed in with an API key. The usage credits guide covers pricing and spend limits.
5. 5
   Switch to an Anthropic Console API key

   Exit Claude Code, set the key, and start it again. A session that's already running won't pick up a variable you export afterwards.export ANTHROPIC_API_KEY="sk-ant-..." claudeApprove the key when Claude Code asks. From then on every token is billed to your Console balance at API rates, with no 5-hour or weekly cap. For scale, the median cost of one build task in our test ran from $0.0925 on Sonnet in a fresh session to $1.5157 on Opus with a long context. Unset the variable and restart to go back to your plan.
6. 6
   Upgrade if it keeps happening

   If you regularly run out of Pro limits during a normal working day, Max 5× or Max 20× raises your 5-hour session allowance by that multiple. Max has its own weekly limits too, but Anthropic doesn't publish them as the same multiples, so check the limits by plan before you decide.

The same situation in Claude on the web and desktop, including where to find your exact reset time, is covered in what to do when you hit a Claude usage limit.

Frequently asked questions