Count tokens before you send: pre-flight budget checks for LLM calls

Count tokens before sending expensive requests, compare the result to a per request budget, and refuse, trim, or reroute when it is over. The Claude token counting endpoint is free, accepts the same structure as a message request, and returns an estimate, so treat it as a forecast to reconcile against real usage.

What the endpoint does

The docs describe it as a way to determine the number of tokens in a message before you send it, to manage rate limits and costs, make model routing decisions, and fit prompts to a target length. It accepts system prompts, tools, images, and PDFs, and returns total input tokens.

It is free to use but has its own requests per minute limit by tier, separate from message creation limits. Using one does not count against the other.

What it does not cover

The docs list inputs it rejects with an error: server tools such as web search and code execution (the advisor tool is an exception), the MCP connector, and image or document blocks that use a URL or file source. Send images and PDFs as base64 to count them. For those excluded cases, read the usage object in the real response.

It also does not use caching. You may include cache control blocks, but caching only happens on actual message creation. So a count tells you total input, not what you will pay after cache hits.

It is an estimate

The docs say actual input tokens can differ by a small amount, and that counts may include tokens added by the provider for system optimizations, which you are not billed for. Reconcile: log the estimate and the billed usage for each call, and watch the gap.

Building a budget gate

1. Define a maximum input size per feature, in tokens.
2. Count tokens for the assembled request.
3. If it is under budget, send.
4. If it is over, apply a policy: trim old history, drop optional documents, route to a model with enough room, or reject with a clear message.
5. Log the decision.

Do this only on requests that could be large. Counting every small request spends rate limit for little benefit.

Output is not included

A pre-flight count covers input only. Cap output with max_tokens and an effort setting, and for reasoning models remember that thinking counts toward max_tokens.

Recount after a model change

The docs say newer models use a different tokenizer that produces about 30 percent more tokens for the same text in one comparison, and that you should count against the model you plan to use. A budget set in tokens needs recalibrating when you move.

Compare models cheaply

Count the same request against two candidate models and compare the two totals. That is a fast way to size a migration before you run an evaluation.

Quick check

Sources

• Token counting, Claude docs

Last reviewed: 19 October 2026.