Home / The Claude API for builders

Counting before sending: the context window

A dedicated counting endpoint returns the number of tokens in a request before it is sent, and the context window to compare against this figure is no longer one shared value across a whole model range, it now varies sharply from one family to another.

A request sent to the Messages API is rejected if it exceeds the context window of the model called, the sum of input tokens, output tokens and any cached content. A dedicated counting endpoint makes it possible to know this size before even sending the full request.

The dedicated counting endpoint

The API exposes an entry point distinct from the Messages API itself, POST /v1/messages/count_tokens, which accepts the same request structure, the same messages array, the same declared tools, and returns only the number of tokens that request would consume, without generating a response. Comparing this figure to the target model's context window before sending detects an overrun without waiting for a server error, and estimates the cost of the request in advance.

A window that now varies sharply from one model to another

The context window is no longer one value shared across a whole model range: it depends on the exact family called, and a more recent model does not necessarily carry the widest window in its own catalogue. The figure in this lesson gives the exact detail by model, with its source and its verification date, since a technical limit of this kind becomes outdated as soon as a new generation of models ships.

Not confusing the API with the chat application

The same model name can carry a different context window depending on whether it is called from the Messages API or from the chat application, where a paid plan applies its own display limit independent of the protocol. The figure in this lesson only documents the value that applies to a request sent through the API, the only one relevant to code you write yourself. The support article that details the tiers by paid plan only documents the chat application, never the Messages API: the figure in this lesson only carries the value that applies on the API side. The same stable prefix that fills cached memory counts in full toward this total, marking a block as reusable does not remove it from the window calculation.

import anthropic

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Resume ce texte : " + "phrase de test. " * 200}]

compte = client.messages.count_tokens(
    model="claude-sonnet-5",
    messages=messages,
)

fenetre_du_modele = 1_000_000  # confirmed for this model in the figure of this lesson
max_tokens_prevus = 1024  # output tokens the response can produce at most
if compte.input_tokens + max_tokens_prevus > fenetre_du_modele:
    print("depassement de la fenetre de contexte")
else:
    print("jetons dans la requete :", compte.input_tokens)

The script counts the tokens of a request built on the spot, without reading any project file, then compares this total to the target model's window before sending anything. The same structure works to check a longer batch of messages, or a request that includes declared tools.