Token Counting

Token counts decide what a request costs, whether it fits a model's context window and how much of your plan it uses. Tokens gives you two ways to know them: a counting endpoint that tells you the input size before you send, and a usage object in every response that tells you what was billed. This page covers both, and how to estimate when you have neither.

Count tokens with POST /v1/messages/count_tokens#

POST https://tokens.bd/v1/messages/count_tokens takes the same body as /v1/messages and returns the number of input tokens. It never runs the model and generates no text. It speaks the Anthropic format, so Anthropic SDKs use the bare host https://tokens.bd as their base URL.

curl -i https://tokens.bd/v1/messages/count_tokens \
  -H "x-api-key: $TOKENS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash",
    "system": "You are a concise senior engineer.",
    "messages": [
      {"role": "user", "content": "Explain idempotency keys in two sentences."}
    ]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://tokens.bd",
    api_key=os.environ["TOKENS_API_KEY"],
)

count = client.messages.count_tokens(
    model="deepseek/deepseek-v4.1-flash",
    system="You are a concise senior engineer.",
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
)
print(count.input_tokens)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://tokens.bd",
  apiKey: process.env.TOKENS_API_KEY,
});

const count = await client.messages.countTokens({
  model: "deepseek/deepseek-v4.1-flash",
  system: "You are a concise senior engineer.",
  messages: [{ role: "user", content: "Explain idempotency keys in two sentences." }],
});
console.log(count.input_tokens);

The response is one field:

{ "input_tokens": 31 }

The number is illustrative. model is required, as on every Tokens endpoint, and max_tokens is not needed. You can send system, messages with text and images, and tools; the count includes all of them. Authentication is the same as on /v1/messages: x-api-key or Authorization: Bearer. As elsewhere, send content-type: application/json.

Exact count or estimate#

The model decides how tokens are counted, so Tokens answers in one of two ways:

A model served only through an OpenAI-format provider has no native counting, so it always gets the estimate. Check the header (curl -i prints it) before you trust a number to the token.

The local estimate is rough by design. It counts the text in system, messages and tools at about four characters per token, adds a flat 1,600 tokens for each image or document block and a few tokens for each message, and returns at least 1. Those constants can change. It is fine for "will this fit" and "about how big is this", and it is not an exact count. Code, JSON and non-English text such as Bengali are the cases where four characters per token is least accurate, because they usually need more tokens per character than English prose. Measure your own data (see below) before you size a budget.

Counting follows Anthropic's own endpoint when a provider forwards it. Based on Anthropic's token counting documentation, checked October 2026: the count is itself an estimate that can differ from the billed number by a small amount, it counts system prompts, tools, images and PDFs, and server tools, the MCP connector and url or file image and document sources are rejected (send images and PDFs as base64). Counts also depend on the model's tokenizer, so count against the model id you will send.

What counting costs and what it counts toward#

• Not billed. A count never settles a charge, uses no plan credits and writes no usage record.
• Still checked like a request. Counting goes through the same admission step as inference, so it needs a valid key, a model your key and plan can call, and an account with a plan or wallet balance. It counts toward your per-minute request limit and holds a concurrency slot while it runs. A used-up usage window (429 window_exhausted) or a key restricted to other models blocks it too. Unlike GET /v1/models and GET /v1/tokens/usage, it is not free of rate limits. See rate limits.
• Same size limit. The body can be up to 10 MB, images included.
• Needs the Messages endpoint. If the gateway has turned off the Anthropic Messages endpoint, counting returns 404 anthropic_protocol_disabled and you should use the methods below.

Errors on this endpoint use Anthropic's error shape, with the Tokens code inside, as described in Messages. Codes are in errors.

Count tokens for other endpoints#

There is no counting endpoint for chat completions, completions, responses or embeddings. Use these instead.

Read the usage that comes back#

Every successful inference response tells you what the provider counted, and that is what Tokens bills:

For streams, chat completions only include usage when you set stream_options: {"include_usage": true}; Anthropic-format streams carry it in the message_start and message_delta events. Details are in streaming. Per-request costs appear in the usage analytics, and remaining plan windows and wallet balance are in GET /v1/tokens/usage (models and usage).

Measure with a one-token request#

To learn the exact prompt size for a chat model before running a long generation, send the real prompt with max_tokens set to 1 and read usage.prompt_tokens:

curl https://tokens.bd/v1/chat/completions \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4.1-flash",
    "messages": [{"role": "user", "content": "Explain idempotency keys in two sentences."}],
    "max_tokens": 1
  }'

This is billed: you pay for the input tokens and at most one output token. It also counts as a request. Some models reject or ignore very small max_tokens values, so raise it slightly if you get a 400. For a cheaper check on the Messages format, use the counting endpoint above.

Estimate with a rule of thumb#

For a quick budget, divide the number of characters by four for English prose. The gateway does the same for its own pre-flight check: before forwarding, it reserves the worst-case cost using the request body size divided by four for input, and max_tokens (8,192 if you leave it out) for output. That reservation is a safety margin and not a bill: you are charged for the usage the provider reports. It does mean a large max_tokens can make a request fail on funds or a spend cap even when the real answer would be short, so set max_tokens close to what you need. See chat completions.

A local tokenizer library gives exact counts only for the family of models it was built for. For other models it is another estimate, so use it for sizing, and use the usage object for truth.

Check that a prompt fits before sending#

A request fits when the prompt tokens plus max_tokens stay inside the model's context window, which is on the model's page in the catalog. This Python helper counts first and then sets max_tokens from the space left:

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://tokens.bd",
    api_key=os.environ["TOKENS_API_KEY"],
)

CONTEXT_WINDOW = 128_000  # read this from the model's catalog page
messages = [{"role": "user", "content": open("big-file.txt").read()}]

used = client.messages.count_tokens(model="deepseek/deepseek-v4.1-flash", messages=messages).input_tokens
room = CONTEXT_WINDOW - used
if room < 1_000:
    raise SystemExit(f"Prompt is {used} tokens; too close to the context window.")

reply = client.messages.create(
    model="deepseek/deepseek-v4.1-flash",
    max_tokens=min(4_000, room),
    messages=messages,
)
print(reply.usage)

Replace CONTEXT_WINDOW with the real value for your model. When the count is an estimate, leave extra room, for example 10 percent.

Related#

• Messages for the endpoint whose body counting takes.
• Chat completions, Embeddings and Legacy completions for the usage object on each.
• Plans and wallet for how tokens turn into credits and cost.