1# Token Counting
2 
3Use the `count_tokens` endpoint (`POST /v1/messages/count_tokens`) for accurate
4token counts against Claude models. Token counts are **model-specific** — pass
5the same model ID you'll use for inference.
6 
7**Do not use `tiktoken`.** It's OpenAI's tokenizer. It undercounts Claude
8tokens by ~15–20% on typical text, and by much more on code or non-English
9input. Any estimate from `tiktoken`, `gpt-tokenizer`, or similar is wrong for
10Claude.
11 
12## Count a file or string
13 
14```python
15from anthropic import Anthropic
16 
17client = Anthropic()
18resp = client.messages.count_tokens(
19    model="claude-opus-4-8",
20    messages=[{"role": "user", "content": open("CLAUDE.md").read()}],
21)
22print(resp.input_tokens)
23```
24 
25TypeScript: `await client.messages.countTokens({model, messages})` →
26`.input_tokens`. See `{lang}/claude-api/README.md` for other SDKs.
27 
28## CLI
29 
30```sh
31ant messages count-tokens --model claude-opus-4-8 \
32  --message '{role: user, content: "@./CLAUDE.md"}' \
33  --transform input_tokens -r
34```
35 
36## Diffing a file across two versions
37 
38The endpoint is stateless — count each version separately and subtract:
39 
40```python
41from anthropic import Anthropic
42import subprocess
43 
44client = Anthropic()
45def count(text: str) -> int:
46    return client.messages.count_tokens(
47        model="claude-opus-4-8",
48        messages=[{"role": "user", "content": text}],
49    ).input_tokens
50 
51before = subprocess.check_output(["git", "show", "HEAD:CLAUDE.md"], text=True)
52after = open("CLAUDE.md").read()
53print(count(after) - count(before))
54```
55 
56Full docs: see the Token Counting entry in `shared/live-sources.md`.
57