CONCEPT Measure a prompt before it hits the window
You can find out exactly how many input tokens a request will cost before sending it, using the
token counting endpoint: POST /v1/messages/count_tokens. It accepts the
same structured inputs as message creation — system, messages,
tools, images, and PDFs — and returns the total input tokens as a single field:
{ "input_tokens": 14 }
Use it to proactively manage rate limits and cost, make model-routing decisions, and fit a prompt to a target length — and, most relevant here, to budget against the context window so a request doesn't overflow (1.5).
CONCEPT Model-specific, free, and separately rate-limited
Token counts are model-specific — pass the same model you'll use for inference.
This matters: Opus 4.7+, Fable 5, Mythos 5, and Sonnet 5 use a newer tokenizer that produces
roughly 30% more tokens for the same text than earlier models. Never reuse a count measured
against an older model to estimate context-window fit — recount against the target model.
| Property | Value |
|---|---|
| Endpoint | POST /v1/messages/count_tokens |
| Python / TS SDK | client.messages.count_tokens(...) / client.messages.countTokens(...) |
| Counts | system, messages, tools, images, PDFs |
| Supported models | All active models (incl. Sonnet 5) |
| Price | Free |
| Rate limits | RPM by tier — Start 2,000 / Build 4,000 / Scale 8,000; separate & independent from message-creation limits |
tiktoken — that's OpenAI's
tokenizer and it undercounts Claude tokens (worse on code and non-English). The count endpoint is the only
accurate source.DIAGRAM Count → decide → send
fit the window?"} Q -->|"yes"| SEND["🟢 messages.create()"] Q -->|"no"| TRIM["🟠 Trim / summarize
history first (1.4, 1.5)"] TRIM --> C classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class SEND ok; class TRIM gate;
CODE Budget-check before creating the message
# Free, and doesn't touch your message-creation rate limit. count = client.messages.count_tokens( model="claude-opus-4-8", # same model you'll infer with — tokenizer differs! system="You are a scientist", tools=tools, # tool defs count too messages=history, ) input_tokens = count.input_tokens # e.g. 403 WINDOW, MAX_OUT = 1_000_000, 4096 if input_tokens + MAX_OUT > WINDOW: history = summarize_oldest(history) # make room BEFORE sending (1.5) resp = client.messages.create( model="claude-opus-4-8", max_tokens=MAX_OUT, messages=history, )
TRADE-OFFS Pre-count vs. send-and-see
✅ Count first
- Catch overflow before spending a create call
- Free; own rate-limit pool
- Drives model routing & cost estimates
⚠️ Costs / caveats
- An extra round trip & its own RPM limit
- Only an estimate — small drift vs. actual
- Doesn't use caching logic (no cache benefit)
EXAM TRAPS
tiktoken / a fixed chars-per-token ratio." → Wrong tokenizer,
wrong numbers. Use POST /v1/messages/count_tokens against the target model.PRACTICE
Q1 · What endpoint estimates a prompt's size, and what does it return?
POST /v1/messages/count_tokens (SDK: messages.count_tokens). It takes the
same inputs as message creation and returns { "input_tokens": N } — an estimate of total input
tokens including system, messages, tools, images, and PDFs.
Q2 · Why must you pass the exact model you'll infer with?
Token counts are model-specific. Opus 4.7+, Fable 5, Mythos 5, and Sonnet 5 use a newer tokenizer that produces ~30% more tokens for the same text — a count from an older model would under-estimate context-window fit and cost.
Q3 · Is counting free, and does it consume your message rate limit?
Counting is free, and it has separate, independent RPM limits (Start 2,000 / Build 4,000 / Scale 8,000) that don't count against message creation.