Normal Claude Code use on a Claude Pro or Max plan does not require an API key; if ANTHROPIC_API_KEY is set, Claude Code can prioritize that key and move the session onto API billing. That is the real split behind Claude Code API key versus subscription billing: the key is not the upgrade, the active route is.
Before you change plans or buy credits, run /status. Use subscription login for interactive coding covered by your Claude plan, use an API key for SDKs, CI, headless automation, or deliberate pay-as-you-go API work, and treat API credits as a separate Claude Console balance rather than subscription allocation.
| Your situation | Route to use | What bills it | First check |
|---|---|---|---|
| You are coding interactively in Claude Code with Pro or Max | Subscription login | Included Claude plan usage, subject to plan limits | /status should show a subscription/account login route |
You set ANTHROPIC_API_KEY or run Claude Code in automation | API key route | Claude API usage billed from Console | Check the environment variable and Console Usage |
| You bought or auto-reload API credits | API credit route | Prepaid Console balance for API, Workbench, and Claude Code API-route use | Check Console Billing and Usage |
| You see unexpected API spend | Diagnose before buying another plan | The API key may be overriding subscription behavior | echo $ANTHROPIC_API_KEY, then /status |
Start With The Active Route
The right answer depends on what Claude Code is actually using at runtime. Anthropic's Claude Code support docs separate two common routes: connecting Claude Code with your Claude Pro or Max credentials, and setting API-key environment variables for API-route use. Those two routes can coexist on the same machine, but they do not share the same billing owner.
For a normal developer working in the terminal, the clean default is subscription login. That keeps Claude Code tied to your Claude account and the plan limits described for Pro or Max. It is the path to choose when the job is interactive coding, code review, refactoring, or repo exploration and you do not need a backend service account.
The API key route is different. If you set ANTHROPIC_API_KEY, Anthropic's support page says Claude Code can use that key, and the API account is responsible for billing. That is useful when you intentionally need programmatic access, a CI job, a headless agent, a service account style setup, or a workflow that should be controlled from Claude Console rather than a personal subscription session.
API credits are a third contract. Claude Console credits fund API usage, Workbench, and Claude Code when it is operating through the API route. They are not a hidden bucket inside Claude Pro or Max. If your question is "why did Claude Code use API billing when I already subscribe?", this is usually the missing distinction.
Check The Route Before You Read Any Meter
The fastest safe sequence is short:
bashclaude /status echo "$ANTHROPIC_API_KEY"
Start with /status because it tells you which account and route Claude Code is currently using. If the status points to your subscription login, interpret plan limits and usage through the subscription lens. If the status points to an API route, the Console account and its usage ledger become the billing source of truth.
Then check the environment. A shell variable can be easy to forget because it may come from .zshrc, .bashrc, .env, a terminal profile, a CI secret, a devcontainer, or a launcher script. If echo "$ANTHROPIC_API_KEY" prints a value, do not paste it anywhere and do not share screenshots. The important fact is simply that a key is present.
Use these commands when you want to switch back to subscription behavior in the current shell:
bashunset ANTHROPIC_API_KEY claude logout claude login claude /status
That sequence does not delete keys from Claude Console. It only removes the current shell override, resets the local Claude Code session, and lets you verify that the next session is using the intended login path. If the key keeps coming back, search your shell startup files and project environment files rather than buying another subscription tier.
Why API Billing Appears On A Subscribed Account
A Claude subscription and Claude API billing are separate products. Claude Pro or Max can let you use Claude Code through Claude credentials, but that does not mean the plan includes general API calls. Anthropic's Pro/Max Claude Code support article explicitly treats API credits as separate from subscription use.
The confusing part is that Claude Code can sit at the intersection. The same local tool can be used interactively with a subscription login, or it can be pointed at an API key for API-account usage. When those paths are mixed on the same machine, the route in effect matters more than the plan you assume you are using.
Here is the practical cause map:
| Cause | What happened | What to do |
|---|---|---|
ANTHROPIC_API_KEY is set | Claude Code can prioritize the API key over subscription auth | Unset it and verify /status |
| A CI or automation job runs Claude Code | The job cannot rely on a human subscription session | Use an API key deliberately and budget it in Console |
| API credits or auto-reload were enabled | Console has a funded balance for API-route work | Monitor Console Billing and Usage |
/cost shows a token estimate | The command is estimating API-style token cost | Do not treat it as the bill for subscription sessions |
| Subscription limits are still hit | Plan usage and API billing are separate questions | Read plan-limit troubleshooting, not API-key setup |
The main mistake is trying to solve every surprise charge by upgrading Claude Pro to Max, or trying to solve every plan-limit message by buying API credits. Those are different knobs. If /status says subscription, look at subscription limits. If /status says API, look at environment variables and Console usage.
For broader plan-limit behavior, use the sibling guide on Claude Code usage limit issues. Keep the billing-route diagnosis separate from plan-limit troubleshooting so you do not change the wrong contract.
Which Meter Should You Trust?
Claude Code has several useful meters, but they do not all answer the same question.
/status is the route check. Use it first because it tells you whether the session is tied to a subscription/account login path or an API route. If you skip this step, every other number is easier to misread.
/stats is useful for subscribers who want to understand usage patterns inside Claude Code. It can help you see whether a coding habit is burning through your plan faster than expected, but it is not the same thing as a Console invoice.
/cost is mainly useful for API-style cost estimation. Claude Code's cost docs caution that subscribers should not read /cost as the authoritative billing truth for Pro or Max plan usage. For API-route work, the Console Usage page is the better place to confirm spend.
Claude Console Billing and Usage are authoritative for API credits, prepaid balances, auto-reload, and API spend. If a team asks "which project paid for this?", the answer should come from Console, not from a screenshot of a local Claude Code session.
When An API Key Is The Right Route
An API key is correct when the work is actually API work. That includes SDK calls, server-side agents, scheduled jobs, CI tasks, non-interactive Claude Code runs, shared team automation, evaluation harnesses, and any workflow where a Console project, spend limit, and usage ledger are more appropriate than a personal subscription login.
The API route is also the right choice when you need to make usage auditable. A subscription login may be convenient for a single human developer, but it is a weak fit for a production job that needs project-level tracking, budget controls, and repeatable deployment.
Use an API key deliberately when these are true:
- the run should continue without a human browser login
- the owner should be a Console project rather than a personal plan
- spend should show up in Console Usage
- the workflow is SDK, backend, CI, agent, or batch oriented
- you are comfortable paying standard Claude API rates for the model used
Do not use an API key as a workaround for a plan-limit message until you understand the route change. It can be a valid escape hatch, but it changes the billing contract. A reader who only wants fewer interruptions in interactive Claude Code should compare plans first, using a page like Claude Code Pro vs Max.
How API Credits And Prices Fit In
Claude Console uses prepaid credits for API usage. Anthropic's billing help says those credits can fund API access, Workbench, and Claude Code when Claude Code uses the API route. Auto-reload is also managed in Console, so a local Claude Code session is not where you should diagnose the payment instrument.
As of April 20, 2026, Anthropic's public pricing page lists current model prices by input and output tokens. For example, the page lists Claude Sonnet 4.6 at $3 per million input tokens and $15 per million output tokens, while Claude Opus 4.7 is listed at $5 per million input tokens and $25 per million output tokens. Treat those as date-bound examples, not as a permanent article spine, because model names and rates can change.
The decision is not "API is cheaper" or "subscription is cheaper" in isolation. The decision is workload shape:
| Workload | Better default | Why |
|---|---|---|
| A human developer working in a repo for a few hours | Subscription login | Predictable plan route and fewer billing surprises |
| Heavy interactive Claude Code usage with recurring limit friction | Compare Pro vs Max first | The problem is likely plan capacity, not API key setup |
| CI job that must run without a human login | API key route | Console project ownership and auditable usage |
| Backend app or SDK integration | API key route | The app is making API calls, not using Claude Code as a personal tool |
| Exploring whether Claude API has free credits | Separate API free-tier question | Use the Claude API key free tier guide |
If you only need the latest pricing rows, go directly to Anthropic's pricing page. If you need the broader plan and usage tradeoff, use the Claude Code pricing guide. The narrower route question is which account is billing Claude Code right now.
How To Switch Back To Subscription Use
If you expected subscription use but see API billing, do not start by deleting keys in Console. First prove whether the local environment is steering Claude Code to API mode.
Use this checklist:
- Run
/statusinside Claude Code and record whether the active route looks like subscription login or API usage. - In the same terminal, run
echo "$ANTHROPIC_API_KEY"and check whether any value is set. - If a key is set and you want subscription behavior, run
unset ANTHROPIC_API_KEY. - Run
claude logout, thenclaude login, and authenticate with the Claude account that has Pro or Max. - Run
/statusagain before starting real work. - If the key returns after opening a new terminal, remove it from shell startup files, project env files, launch agents, CI secrets, or container configuration.
This is a small workflow, but it prevents a common double-pay pattern: the reader keeps a subscription for interactive work, sets an API key for one test, forgets the variable, and later assumes Claude Code is still using the plan.
If your team intentionally wants both routes, write it down. A simple convention is enough: subscription login for local interactive coding, API key for automation, and Console Usage for API spend review.
What Not To Mix Up
Do not say "Claude Code is free" just because you can log in with a paid plan. The plan has limits, and API usage has separate billing.
Do not say "Pro includes API calls." Pro or Max can cover Claude Code usage through Claude credentials, but general API access is a Console billing contract.
Do not treat /cost as the final word for subscription billing. It is useful context, especially for API-style work, but /status, /stats, and Console Usage each answer different questions.
Do not paste a real API key into tickets, chat, screenshots, or troubleshooting prompts. If a support path needs proof, show whether the variable exists and which route /status reports, not the secret value.
Do not use community answers as billing authority. Forums are useful for seeing which confusion is common, but the current billing contract should come from Claude and Anthropic docs.
Sources And Verification Path
These route and billing facts are based on the current official Claude and Anthropic documentation checked on April 20, 2026:
- Claude Help on managing
ANTHROPIC_API_KEYand other API-key environment variables in Claude Code. - Claude Help on using Claude Code with Pro or Max plan credentials.
- Claude Help on prepaid API credits and Claude API billing.
- Claude Code docs for cost tracking and the difference between
/cost,/stats, and Console Usage. - Anthropic pricing docs for date-bound API price examples.
For your own account, use the same order: /status first, environment variable second, Console Usage third. That order gives you a route answer before you make a plan or payment decision.
FAQ
Do I need an API key to use Claude Code?
Not for normal interactive use with Claude Pro or Max. Claude Code can connect through your Claude credentials. You need an API key when the workflow should run through the Claude API route, such as SDK work, CI, automation, or a Console-owned project.
Why is Claude Code billing my API account when I have Pro or Max?
The most likely reason is that Claude Code is using the API route. Check /status, then check whether ANTHROPIC_API_KEY is set in the shell or runtime that launched Claude Code. If that variable is present, the API account can become the billing owner.
Are Claude API credits the same as subscription usage?
No. API credits live in Claude Console and fund API-route usage, Workbench, and Claude Code when it uses the API route. Subscription usage belongs to the Claude plan route and has its own limits.
Should I use API billing instead of upgrading to Claude Max?
Only if your work is really API-shaped. For local interactive coding, compare Pro and Max first. For CI, SDKs, backend agents, or auditable team automation, API billing is often the cleaner contract.
Is /cost showing my Pro or Max bill?
No. Treat /cost as an API-style token cost estimate. Use /status to identify the active route, /stats to understand subscription usage patterns, and Console Usage for API billing.
How do I stop Claude Code from using my API key?
Unset ANTHROPIC_API_KEY, log out of Claude Code, log in with your Claude account, and run /status again. If the key returns in a new terminal, remove it from shell startup files, project env files, CI secrets, or container configuration.