Estimate input size before sending a Messages request with POST /v1/messages/count_tokens. The endpoint makes no model call and spends no inference credits. It returns a conservative estimate, rather than a tokenizer-exact count or a guaranteed final bill.
Count a request
Use the same model, system prompt, messages, and client tool definitions you intend to generate with. A valid API key with access to the selected model is required. max_tokens can be omitted for counting.
curl 'https://redrouter.org/v1/messages/count_tokens' \
-H "x-api-key: $REDROUTER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "red-cyber-1",
"system": "Summarize security observations in plain language.",
"messages": [{"role": "user", "content": "Explain network segmentation."}],
"tools": [{
"name": "lookup_asset",
"description": "Read one entry from the local inventory.",
"input_schema": {
"type": "object",
"properties": {"name": {"type": "string"}},
"required": ["name"]
}
}]
}'
The response has one field, input_tokens, containing the estimate. This endpoint accepts Messages request shapes and validation rules; it is not a Chat Completions or Responses tokenizer endpoint. See Messages and the token-counting schema.
What the estimate includes
The estimate uses normalized input, UTF-8 text bytes, and fixed chat-template overhead. It accounts for replayed call/result data and normalized client-tool definitions. Text with non-ASCII characters can therefore produce a substantially larger bound than its eventual model-token count.
Supported images use a dimension-based bound of 1100 + floor(width × height × 1100 / 1,000,000) per image. Unsupported images are counted as their omission notice after normalization. This is an admission estimate, not a model-specific vision tokenizer. See Images.
The count is capped at the selected model's context limit. A returned value equal to that limit can hide an estimate larger than the limit; it does not prove that the request fits. Count results also do not reserve output space. Leave room for the intended output budget and any model-specific formatting overhead.
Limits of preflight counting
Counting is useful for identifying unusually large histories and deciding when to summarize. It cannot establish that a generation will be accepted or finish successfully:
- It is not tokenizer-exact and can substantially overestimate actual text usage.
- It does not include generation output or guarantee a model's context handling.
- It is not identical to the credit-reservation estimate. Admission also accounts for serialized generation/schema parameters when tools or response formats are present.
- It does not check available credit, reserve concurrency, or guarantee future capacity.
- A JSON schema used only as a structured-output control is not a separately itemized tokenizer measurement.
The same 12000000-byte body limit applies, including base64 image data. Unknown Messages fields still return 400. Counting uses no model generation, but normal authentication and model access checks apply.
Choose output and credit headroom
Input context and output limits are different constraints. Current models have an 8,192-token output cap, even when their context windows are much larger. Check both the context and default output limits in Models.
Generation reserves credits from a conservative input bound plus the authorized output maximum. The final charge uses reported actual usage when available; missing usage follows the failed-request policy. A high preflight estimate is therefore not a prediction that the final charge will use that many tokens. See Billing, Model selection, and Production.