Count tokens API: measure a prompt before you send it

POST /v1/messages/count_tokens follows the Anthropic token counting format. You send model, messages and, if you use them, system and tools. The API tokenises everything exactly as it would for a real request, using the tokenizer of the model you name, and returns {"input_tokens": N}.

Nothing is generated and no output tokens are produced, so the call is fast and you do not need max_tokens. The count includes the system prompt, every message, tool definitions and the formatting the model's chat template adds around them, which is why it is more accurate than counting words or running a generic tokenizer yourself.

Different open models split text into tokens in different ways. The same contract can be noticeably more tokens for one model than another, especially for German, French and other non-English text, code, or tables. Context windows and token-based billing are both counted in the tokens of the specific model.

That is why the model field is required and why you should count with the model you will actually call. If you switch models, recount. A rough rule of thumb from one tokenizer can be wrong by enough to push a long prompt over the limit, and the API will then reject the request with a 400 error.

Before sending a long document, count the tokens of your system prompt, the document and the question together. If the total plus the answer you expect fits within the model's context window, send it as one request. If not, split the document into chunks that each fit, summarise or extract from each chunk, and combine the results in a final call.

The same check is useful for batch jobs. Count a sample of inputs, multiply by the number of rows, and you have a realistic estimate of input volume before you submit the batch, instead of finding out from the invoice.

Errors use the Anthropic format. An unknown model returns not_found_error (404); malformed messages, for example two user turns in a row where the model's template does not allow it, return invalid_request_error (400). A bad key returns 401.

The count covers input only. Output tokens, including reasoning on thinking models, are added when the model generates, so leave room for them. Images in content blocks are counted according to the vision model's own rules, which depend on resolution. Counts reflect the current tokenizer and template for each model, so do not cache them across model versions.