D5 · Context & Reliability › Cluster 1 · Context Windows & Token Budgeting

1.2 · Token Counting & the Count Endpoint

Measure before you send

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

🔑 The count is an estimate — the actual number used when creating the message may differ by a small amount. Anthropic may also add tokens for system optimizations, but you are not billed for system-added tokens — billing reflects only your content.

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.

PropertyValue
EndpointPOST /v1/messages/count_tokens
Python / TS SDKclient.messages.count_tokens(...) / client.messages.countTokens(...)
Countssystem, messages, tools, images, PDFs
Supported modelsAll active models (incl. Sonnet 5)
PriceFree
Rate limitsRPM by tier — Start 2,000 / Build 4,000 / Scale 8,000; separate & independent from message-creation limits
⚠️ Do not estimate Claude tokens with 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

flowchart TD A["Assemble system + messages + tools"] --> C["count_tokens → input_tokens"] C --> Q{"input_tokens + max_tokens
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,
)
To size a diff, the endpoint is stateless: count each version separately and subtract. Server-tool token counts apply only to the first sampling call.

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

Trap: "Use tiktoken / a fixed chars-per-token ratio." → Wrong tokenizer, wrong numbers. Use POST /v1/messages/count_tokens against the target model.
Trap: "A count from Sonnet 4.5 is fine for Opus 4.8." → The newer tokenizer (Opus 4.7+, Fable 5, Sonnet 5) yields ~30% more tokens for the same text. Recount per model.
Trap: "Counting eats my message rate limit." → No — token counting has separate, independent rate limits, and the endpoint is free.
Trap: "The count is exact." → It's an estimate; actual may differ by a small amount. Anthropic's system-added tokens aren't billed.

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.