Claude and the Anthropic SDK (TypeScript) · 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
  • TypeScript
  • In the all labs plan

The first 2 chapters of Claude and the Anthropic SDK (TypeScript) 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 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.ts: count it, then send it

    Count a request with client.messages.countTokens: model 'claude-opus-5-5', system: policyWording(), 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.ts: 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: policyWording(); 3. + tools: TOOLS; 4. + an image block with billPhoto(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.ts: a token budget

    Export sendWithinBudget(params, budget). Count params with client.messages.countTokens (without max_tokens: take it out first). If the count is over budget, throw an Error 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.ts

    "Farhan estimated the claims file with tiktoken, and the bill came in far higher. Why?" Count TEXT (given) with getEncoding('o200k_base').encode(TEXT).length from js-tiktoken, then with client.messages.countTokens (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

  • messages.countTokens: 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 (TypeScript) are free. This one comes with the all labs plan.