Input tokens are the unit of spend for most Claude workloads, and they are surprisingly hard to eyeball. A PDF costs both text and image tokens per page; tool definitions add overhead; and different model generations tokenize the same text differently. The token counting endpoint solves this: send it the exact request you are about to make — POST /v1/messages/count_tokens — and it returns a single number, {"input_tokens": N}, without running the model.
How it works
The endpoint accepts the same inputs as message creation: the messages array, system prompts, tool definitions, images, PDFs, and thinking configuration. It is free to use, with its own requests-per-minute limits that are separate and independent from your message-creation rate limits — 2,000 RPM on the Start tier, 4,000 on Build, 8,000 on Scale — so pre-flight checks never eat into production throughput. Requests are capped at the same 32 MB size as the Messages API.
from anthropic import AnthropicVertex
client = AnthropicVertex(project_id="my-project", region="global")
count = client.messages.count_tokens(
model="claude-opus-4-8",
system="You are a contract-review assistant.",
messages=[{"role": "user", "content": contract_text}],
)
if count.input_tokens > 200_000:
queue_for_batch(contract_text) # cheaper path for big jobs
else:
answer_interactively(contract_text)Treat the number as a close estimate rather than an invoice: actual input tokens on message creation may differ slightly, and system-added tokens can appear in counts without ever being billed. Two subtleties are worth knowing. The endpoint is stateless — to measure the incremental cost of a change, count both versions and subtract. And cache_control markers are accepted but ignored: counting never writes or reads the prompt cache, so the returned figure is the uncached size.
Counts are model-specific
Always count against the model you will actually call. Claude Opus 4.7 and later, Fable 5, and Sonnet 5 use a newer tokenizer that produces roughly 30% more tokens than earlier models for the same text — a prompt sized against Sonnet 4.6 will under-estimate on Sonnet 5. For the same reason, never use OpenAI's tiktoken library as a stand-in for Claude: it undercounts Claude tokens by roughly 15–20% on typical text, and more on code or non-English content.
What to build with it
Budget gates. Before an expensive call, check the count against a per-request ceiling and reject, truncate, or reroute anything over it. This catches runaway retrieval pipelines that quietly stuff 400k tokens of context into what was designed as a 20k-token prompt.
Cost-aware dispatch. Multiply the count by each candidate model's input price and route accordingly — small requests to a premium model, huge ones to a cheaper model or the 50%-discounted batch path. Because counting is free, the dispatch logic costs nothing but a round trip.
Surfacing surprises. Documents are the classic shock: a PDF page typically costs 1,500–3,000 text tokens plus image tokens. Counting a document before committing to process a thousand of them turns a budget overrun into a design discussion.
Overflow prevention. Input that exceeds the model's context window fails with a 400 error; a pre-flight count lets you trim or summarize first instead of burning a failed request.
Platform availability
Token counting is generally available on the Claude API, Claude Platform on AWS, Amazon Bedrock, and Google Vertex AI, and in beta on Microsoft Foundry. It is also one of the features documented as eligible for Zero Data Retention, which matters to teams with strict data-handling requirements — confirm specifics with your provider.
Where to go next
Pair counting with batch processing for the cheap high-volume path, and with prompt caching to shrink what you pay for repeated context. The feature matrix has the platform-by-platform view.