Skip to content

Count tokens (Anthropic)

POST /v1/messages/count_tokens tells you how many input tokens a message will use before you send it, to stay under a context window or a budget. Through the gateway it works whatever model the name points to: Anthropic counts for Claude, and the gateway counts for everything else, without calling or billing a provider.

What it is

Anthropic's token-counting endpoint. It takes the same body as Messages (model, messages, and optionally system, tools, thinking) and answers {"input_tokens": N}. It costs nothing at Anthropic, and the gateway's own count costs nothing at all.

Model behind the name Who counts
Claude on Anthropic Anthropic, as it always does
Any other provider's model (OpenAI, Azure, Gemini on Google AI Studio or Vertex AI) The gateway itself, with no call to the provider
Claude on Amazon Bedrock or Vertex AI The gateway itself, with no call to the provider: an estimate, marked x-vidai-token-count: estimated

The two settings

The same as for Messages: ANTHROPIC_BASE_URL (base_url, baseURL) set to https://<your-gateway>, and ANTHROPIC_API_KEY (api_key, apiKey) set to your Vidai key.

A minimal call

import anthropic

client = anthropic.Anthropic()
count = client.messages.count_tokens(
    model="claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Summarise our travel policy in three lines."}],
)
print(count.input_tokens)
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const count = await client.messages.countTokens({
  model: "claude-sonnet-4.5",
  messages: [{ role: "user", content: "Summarise our travel policy in three lines." }],
});
console.log(count.input_tokens);
curl https://<your-gateway>/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4.5",
       "messages":[{"role":"user","content":"Summarise our travel policy in three lines."}]}'

Reading what the gateway did

When the gateway answered the count itself, the response carries x-vidai-token-count:

Value Meaning
tokenizer-match Counted with the tokenizer of the model's own family: close to what the provider will charge
estimated Counted with a near tokenizer: treat it as an estimate and leave some headroom

No header means the provider counted. Read it with client.messages.with_raw_response.count_tokens(...) in Python, or .withResponse() in TypeScript, as on Messages. x-vidai-request-id is there either way.

Errors

In Anthropic's shape, as on Messages: model_not_found, model_not_allowed and the key codes apply here too. Match on x-vidai-error-code.

Model names

Any name your key may call, as listed under Models in the Control room.

Check it works in a minute

Run the curl above with a model of another provider (for example gpt-4.1) and add -i: a 200 with {"input_tokens": …} and an x-vidai-token-count header means the gateway counted it.

Good to know

  • A gateway count is for planning, not billing: what you're charged is what the provider reports on the real call, which you find in Request logs.
  • Images, documents and tools add tokens that a near tokenizer may count differently; keep a margin when the header says estimated.