Claude and the Anthropic SDK · Chapter 12 of 21

Counting tokens

By the end of this chapter you can ask the API how many tokens a request will cost before you send it, see what each part of a request adds (the system prompt, tools, photos, PDFs), explain why OpenAI's tokenizer gets Claude's numbers wrong, and refuse a request that would blow a budget without ever sending it. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Cost
  • 4 tasks
  • Python
  • In the all labs plan

The first 2 chapters of Claude and the Anthropic SDK are free. This one comes with the all labs plan.

Why you need this

Kamla has started forwarding whole files to Sahay: a discharge summary, two bill photos and a pharmacy slip in one message, with the policy wording as the system prompt and the three tools on top. Farhan sees the bill for one such question and asks a fair thing: "How big was that request? And can we stop a request like that before it goes out?"

Until now you learned the size of a request only afterwards, from usage on the reply, when the money is already spent. Guessing in advance with a tokenizer library such as tiktoken is what many of us did with the OpenAI-style API, and for Claude it gives the wrong number: Claude has its own tokenizer, and it is not published. What you need is the API's own count, before the request, for free.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    count_then_send.py: count it, then send it

    Count a request with client.messages.count_tokens: model "claude-opus-5-5", system=policy_wording(), and QUESTION (given) as the one user message. Then send the same request with client.messages.create and max_tokens 1024.

    Print counted: N (the count's input_tokens), then billed: M (the reply's usage.input_tokens), then match: yes (or match: no if they differ).

  2. Task 2

    what_counts.py: what counts?

    Count QUESTION five times with model "claude-opus-5-5", adding one thing each time: 1. the question alone (one user message); 2. + system=policy_wording(); 3. + tools=TOOLS; 4. + an image block with bill_photo(PHOTO) before the question's text block; 5. + a document block with pdf(PDF) after the image block. Send no messages.create.

    Print one line per count: question alone: N tokens, then policy wording: N tokens (+D), Sahay's tools: N tokens (+D), bill photo: N tokens (+D), discharge PDF: N tokens (+D), where D is what that step added to the count before.

  3. Task 3

    budget.py: a token budget

    Write send_within_budget(params, budget), where params is a dictionary of messages.create arguments. Count a copy of params without max_tokens with client.messages.count_tokens. If the count is over budget, raise a ValueError whose message is over budget: N tokens > BUDGET and send nothing. Otherwise send params with client.messages.create and return the reply.

    The check calls it with its own requests: one under its budget, one over.

  4. Task 4 · interview question

    Interview: tiktoken_is_wrong.py

    "Farhan estimated the claims file with tiktoken, and the bill came in far higher. Why?" Count TEXT (given) with len(tiktoken.get_encoding("o200k_base").encode(TEXT)), then with client.messages.count_tokens (model "claude-opus-5-5", TEXT as the one user message, nothing else).

    Print o200k: A, then claude-opus-5-5: B, then ratio: R where R is B / A with 2 decimals.

What you will learn

  • client.messages.count_tokens: the API's count of a request, without running it.
  • Why tiktoken is wrong for Claude: the same text, a different number.
  • What counts: system, messages, tools (and a hidden tool prompt), images, PDFs.
  • A budget check: count first, then send or refuse.

More in Cost

Build "Counting tokens" yourself

Parchi, a Jaipur startup, helps families claim health insurance. You build Sahay, a claims assistant that reads bills and policies with Claude, and measure what caching, models and effort cost. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Claude and the Anthropic SDK are free. This one comes with the all labs plan.