Get API key

Count tokens

View as Markdown

Count the input tokens of a request before you send it, for cost and context-window checks. On both APIs.

POST /v1/chat/count_tokens tells you how many input tokens a chat request would use, without running the model. Use it to estimate cost, check that a request fits the context window, or validate a request before you queue it.

The count matches the prompt_tokens you'd be billed for if you sent the same request to /v1/chat/completions. It includes the system prompt, every message, tool definitions, the model's chat template and the thinking-mode tokens that reasoning_effort adds.

curl -s "https://api.privatemind.com/v1/chat/count_tokens" \
  -H "Authorization: Bearer $PMIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fast",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user",   "content": "Hello, how are you today?"}
    ]
  }'
# => { "input_tokens": 23, "context_window": 131072 }
import httpx

resp = httpx.post(
    "https://api.privatemind.com/v1/chat/count_tokens",
    headers={"Authorization": f"Bearer {PMIND_KEY}"},
    json={
        "model": "fast",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user",   "content": "Hello, how are you today?"},
        ],
    },
)
print(resp.json()["input_tokens"])
const resp = await fetch('https://api.privatemind.com/v1/chat/count_tokens', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${PMIND_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'fast',
    messages: [
      { role: 'system', content: 'You are a helpful assistant.' },
      { role: 'user', content: 'Hello, how are you today?' },
    ],
  }),
});
const { input_tokens } = await resp.json();
console.log(input_tokens);

Parameters

The request takes the chat completion fields that affect the token count. Sampling parameters (temperature, max_tokens, stream and so on) are accepted and ignored, because they don't change the count.

  • model (required): id or alias of a chat model, resolved exactly as /v1/chat/completions resolves it. Unknown models return model_not_found.
  • messages (required): the conversation, same shape as chat completions.
  • tools: tool definitions. Counted for models whose chat template renders tools into the prompt.
  • reasoning_effort: off, low, medium, high or max. On a thinking model this changes the template, and so the count.

Response

JSON
{
  "input_tokens": 23,
  "context_window": 131072
}
  • input_tokens: the input tokens the request would use.
  • context_window: the model's maximum context length, in tokens.

Counting is free: a count_tokens call is never billed and writes no usage.

Cost and context checks

A count has two common uses:

  • Cost estimate. Multiply input_tokens by the model's input rate, listed in Usage, to estimate the cost before you send.
  • Context-window guard. Compare input_tokens, plus the completion you expect to generate, with context_window. If they come close, trim or summarise the conversation before you call /v1/chat/completions, so the model doesn't reject an over-long prompt.
Note

The count reflects the exact request you pass. If you send reasoning_effort or tools to the completion, send the same values here too. Otherwise the count can differ from the completion's prompt_tokens on models whose template changes with those fields.

Messages API

POST /v1/messages/count_tokens counts a Messages API request the same way. It takes the same body as /v1/messages, without max_tokens, and counts the system prompt, messages, tools, images, documents and the thinking setting.

Python
import anthropic

client = anthropic.Anthropic(base_url="https://api.privatemind.com", api_key="PMIND...:...")

count = client.messages.count_tokens(
    model="fast",
    system="You are a helpful assistant.",
    messages=[{"role": "user", "content": "Hello, how are you today?"}],
)
print(count.input_tokens)
JSON
{ "input_tokens": 23, "context_window": 131072 }

input_tokens is the whole prompt. On the matching message the same total is split between input_tokens and cache_read_input_tokens, because the Messages API reports the cached part separately. context_window is a PrivateMind addition that the Anthropic SDKs ignore. Counting is free on this endpoint too.

Where next