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.
- 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).
- 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.
- 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.
- 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.