What a Claude Code agent costs: a step-by-step session with cache

"What does a Claude Code agent cost" has no single-number answer: the bill depends on session length, context size and how much input comes from cache. But you can estimate it in advance and check it against actual spend. Below: a step-by-step session calculation on Claude Opus 5.5 and Claude Sonnet 5, where to see real spend, and how to cap it with a key limit.

What an agent's bill is made of

On every step Claude Code sends the model the whole accumulated context: system prompt, tool definitions, conversation history, contents of files it read, and command output. A step is one model request; one request of yours can turn into dozens of steps.

If all that context were billed as new input every time, a long session would be expensive. So Claude Code uses prompt caching: the start of the context that has already been sent is read from cache at a low price, and the new part is written to cache. The model response shows this in four usage counters:

• input_tokens — fresh input, not from cache;
• cache_read_input_tokens — read from cache;
• cache_creation_input_tokens — written to cache;
• output_tokens — model output.

The cost formula for one step and for the whole session:

Zukko prices as of October 6, 2026, $ per 1M tokens:

The current list and prices are at GET https://api.zukko.pro/v1/models or on the "Models" page in your dashboard.

Important: for Claude the cache discount applies only in the Anthropic format (/v1/messages). Claude Code uses exactly that, so the calculation below applies. If you call Claude through the OpenAI format (/v1/chat/completions), all input is billed at the input price.

What a Claude Code agent costs: step by step

Step 1. Define the session profile

A typical working session:

• 30 steps (model requests);
• 20,000 tokens of context on step one: system prompt, tools, CLAUDE.md, your request;
• the context grows by 5,000 tokens per step: the model's reply plus files read and command output;
• each step has 300 tokens of fresh input and 1,500 tokens of output.

Context at step k: 20,000 + 5,000 × (k − 1). By step 30 it reaches 165,000 tokens.

Step 2. Work out the volumes

• Cache write. On step one the whole context, 20,000, is written to cache. On each later step only the new part, 5,000. Total: 20,000 + 29 × 5,000 = 165,000.
• Cache read. At step k the context of step k − 1 is read. Sum over steps 2…30 = 29 × 20,000 + 5,000 × (0 + 1 + … + 28) = 580,000 + 5,000 × 406 = 2,610,000.
• Fresh input: 30 × 300 = 9,000.
• Output: 30 × 1,500 = 45,000.

Note the ratio: 290 times more tokens are read from cache than arrive as fresh input. So the cache read price matters more here than the input price.

Step 3. Multiply by prices

Volumes in millions of tokens, prices per 1M.

One such session costs about 26 cents on Opus 5.5 and about 15 cents on Sonnet 5. Twenty sessions in a working day come to roughly $5.26 and $3.08 (20 × 0.262905 = 5.2581; 20 × 0.153885 = 3.0777).

Step 4. Account for pauses

The cache has a limited lifetime. According to the Claude Code docs, with an API key the default cache lifetime is five minutes. If you go to lunch and come back, the first request misses the cache and the whole context is written again.

Example: a pause before step 30, when the previous step's context is 160,000 tokens. Instead of a cache read you get a cache write:

• Opus 5.5: 0.16 × $0.425 = $0.068 instead of 0.16 × $0.038 = $0.00608, i.e. $0.06192 more;
• Sonnet 5: 0.16 × $0.25 = $0.04 instead of 0.16 × $0.025 = $0.004, i.e. $0.036 more.

One miss costs almost a quarter of the whole Opus 5.5 session. If you leave a task for a long time, starting a new session with a short summary is cheaper than resuming a huge context.

For comparison: without cache

Without caching, all input — 9,000 + 2,610,000 + 165,000 = 2,784,000 tokens — would be billed at the input price:

• Opus 5.5: 2.784 × $0.4 + 0.045 × $2 = $1.1136 + $0.09 = $1.2036;
• Sonnet 5: 2.784 × $0.2 + 0.045 × $1.013 = $0.5568 + $0.045585 = $0.602385.

That is $0.26 vs $1.20 on Opus 5.5 for the same work.

Calculate your own profile

Plug your numbers into a small calculator:

PRICES = {  # $ per 1M: input, output, cache read, cache write
    "claude-opus-5-5": (0.4, 2, 0.038, 0.425),
    "claude-sonnet-5": (0.2, 1.013, 0.025, 0.25),
}

def session_cost(model, steps, start_ctx, growth, fresh_per_step, out_per_step):
    ctx = [start_ctx + growth * k for k in range(steps)]
    read = sum(ctx[:-1])                      # step k reads the context of step k - 1
    write = start_ctx + growth * (steps - 1)  # first context + growth on steps 2..N
    fresh = fresh_per_step * steps
    out = out_per_step * steps
    p_in, p_out, p_read, p_write = PRICES[model]
    return (fresh * p_in + read * p_read + write * p_write + out * p_out) / 1_000_000

for m in PRICES:
    print(m, round(session_cost(m, 30, 20_000, 5_000, 300, 1_500), 6))

The script prints 0.262905 for Opus 5.5 and 0.153885 for Sonnet 5, the same as the table.

Real sessions differ from the model: Claude Code compacts history, subagents keep their own contexts, and some background requests may go to the model in the Haiku slot. So the estimate is a guide; the charges are the truth.

Connecting Claude Code to Zukko

The minimal block in ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zukko.pro",
    "ANTHROPIC_AUTH_TOKEN": "fetch_...",
    "ANTHROPIC_MODEL": "claude-sonnet-5"
  }
}

The base URL goes without /v1; Claude Code adds the path itself. The key goes in ANTHROPIC_AUTH_TOKEN. Full setup with model slots is in the Claude Code docs↗.

How to see actual spend

1. Dashboard, "Usage" page. Open the dashboard and go to "Usage": it lists charges per request with model and cost. That is your real bill.
2. Spending history API. GET https://api.zukko.pro/v1/usage returns the same records: model, tokens, and cost_cents — cost in cents with a fractional part (0.0546 means $0.000546). It includes all charges on the account, not only one key. Details are in the docs↗.

curl -G https://api.zukko.pro/v1/usage \
  -H "Authorization: Bearer fetch_..." \
  --data-urlencode "limit=50"

1. The /usage command in Claude Code. It shows the session's token counters, including cache reads and writes. Claude Code computes the dollar figure itself from Anthropic's list prices, so with Zukko it won't match your charges. Take the token counts from there and plug them into the formula; check the amount against the dashboard.

How to cap spend with a key limit

Create a separate key for Claude Code in the dashboard↗ and set:

• a daily dollar limit — say $6, if your estimated day on Opus 5.5 is about $5.26: normal work gets through, while an unusually expensive day hits the ceiling;
• a monthly limit — an overall ceiling for the month;
• an allowed-models list — for example only claude-sonnet-5 and claude-opus-5-5, so the agent can't drift onto a pricier model.

How it works, per the limits documentation↗:

• when the daily limit is used up, requests get 429 with code key_daily_limit_reached; for the monthly one, 429 with key_monthly_limit_reached;
• daily spend resets at 00:00 UTC, monthly at the start of the month UTC;
• limits are soft: the check compares spend so far before the request, so the last request let through can slightly exceed the ceiling;
• the limit applies to the key; other keys on the account keep working;
• a request to a model not on the list gets 403 model_not_allowed_for_key.

FAQ

Why does Claude Code show one amount and the dashboard another?

Claude Code computes dollars locally from Anthropic's list prices. You are charged at Zukko prices, and the correct amount is in the dashboard under "Usage".

Does caching work when Claude Code is connected to Zukko?

Yes. Claude Code uses the Anthropic format, so the gateway sees cache reads and writes; they are billed at their own prices from the table.

Which is cheaper for an agent: Opus 5.5 or Sonnet 5?

On price, Sonnet 5: $0.153885 vs $0.262905 in our session. Whether it is good enough for your work, check by running a few real tasks on both models. Other options for Claude Code are compared in the article on choosing a model for Claude Code by price↗.

What happens when the agent hits the daily limit?

Requests with that key start getting 429 key_daily_limit_reached until 00:00 UTC. You can raise the limit in the dashboard or wait.