Claude API Token Counting Best Practices

Token counting determines what you pay, whether your request fits inside a model's context window, and how predictable your application's costs are at scale. Getting it right means counting tokens before you send a request, not after, and understanding that tokens are not the same as characters or words — Claude's tokenizer splits text into subword units that vary by language, formatting, and whitespace.

This guide covers the practical techniques for counting tokens accurately with the Claude API: using the dedicated token-counting endpoint, estimating costs before generation, handling streaming responses, and avoiding the common mistakes that cause budget overruns or unexpected context-window errors.

Why Token Counting Matters

Every Claude API call bills you for input tokens (your prompt, system message, conversation history, and tool definitions) and output tokens (the model's response). If you don't know your token count ahead of time, you can't:

• Predict cost per request or per user
• Stay under a model's context window limit
• Set accurate budgets for rate limiting or usage caps
• Compare the cost-efficiency of different prompt strategies

A rough character-based estimate (like "4 characters per token") works as a sanity check but is unreliable for billing-critical decisions. Code, JSON, non-English text, and markdown formatting all tokenize differently than plain English prose.

Use the Token-Counting Endpoint, Not Estimates

The most reliable practice is to count tokens using the API's token-counting capability before sending the actual generation request. This lets you:

1. Validate that a prompt fits within context limits
2. Estimate cost before committing to a generation call
3. Compare token cost of different prompt formulations

curl https://api.anthropic.com/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-3-5-sonnet-20241022",
    "messages": [
      {"role": "user", "content": "Summarize this document in three sentences."}
    ]
  }'

The response returns an exact input token count for that specific model and message structure — including system prompts and tool definitions if you include them in the request. This is critical: tool schemas and system prompts both consume tokens, and large tool definitions can quietly add hundreds of tokens per request.

If you're routing requests through SubToAPI, the same counting principles apply to your application-level usage metadata — every request logged in your dashboard includes token counts so you can audit cost per endpoint or per customer without re-implementing counting logic yourself. See the messages docs for request structure details.

Best Practices for Accurate Counting

1. Count the Full Request, Not Just the User Message

System prompts, prior conversation turns, and tool definitions all count toward input tokens. If you're building a multi-turn chat application, count the entire message array you're about to send, not just the newest user turn.

2. Re-Count After Every Prompt Change

Token counts shift with small edits — adding a single example to a few-shot prompt, changing JSON key names, or reformatting a system prompt can change the count by dozens of tokens. Don't cache a token count assuming your prompt template is static; re-count whenever the template changes.

3. Account for Tool Definitions Separately

If you use tool calling, the JSON schema for each tool is tokenized and billed as part of the input. Large tool sets (10+ tools with detailed parameter descriptions) can add a meaningful chunk of your token budget before the user's actual question is even processed. Keep tool descriptions concise and only include tools relevant to the current context. Details on structuring this efficiently are in the tools documentation.

4. Track Output Tokens Separately from Input Tokens

Output tokens are typically priced differently from input tokens and are harder to predict in advance since they depend on what the model generates. Set a max_tokens ceiling appropriate to your use case — a classification task needs far fewer output tokens than a long-form content generator — and monitor actual output token usage from the response metadata to tune that ceiling over time.

5. Monitor Token Usage in Production, Not Just in Testing

Token counts in a test environment with sample data rarely match production traffic. Real user inputs vary wildly in length and structure. Log token counts (input and output) for every production request so you can spot anomalies — a sudden spike usually means a bug in prompt construction (e.g., accidentally including an entire conversation history on every turn) rather than legitimate usage growth.

const response = await fetch("https://api.subtoapi.app/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUBTOAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    messages: [{ role: "user", content: userInput }]
  })
});

const data = await response.json();
console.log("input tokens:", data.usage.input_tokens);
console.log("output tokens:", data.usage.output_tokens);

Every SubToAPI response includes this usage object, so you don't need a separate counting call for post-hoc cost tracking — just log it per request. For pre-flight checks (validating a prompt fits before you send it), use Anthropic's count_tokens endpoint directly.

6. Trim Conversation History Deliberately

For chat applications, decide explicitly how much history to retain rather than sending the full transcript on every turn by default. Options include: a rolling window of the last N turns, periodic summarization of older turns, or dropping low-value turns (like tool-call confirmations) once they're no longer relevant. Each of these reduces token cost on every subsequent request, often by a large margin in long conversations.

7. Separate Token Budgets by Feature

If your application has multiple Claude-powered features (a chatbot, a summarizer, a classifier), track token usage per feature rather than as one aggregate number. This makes it obvious which feature is driving cost and lets you optimize the highest-cost prompts first. If you're on a SubToAPI Team or Scale plan, per-key usage breakdowns in the dashboard make this straightforward without building your own analytics layer.

Getting Started

If you're setting up token tracking for a new project, start with the quickstart guide to get an API key, then build token logging into your request wrapper from day one rather than retrofitting it later. Catching a runaway prompt template in week one is far cheaper than discovering it in a monthly invoice.

FAQs

Does counting tokens before a request cost anything? Token-counting calls are typically priced lower than a full generation request since no output is produced, but check current pricing — it's not free, so use it for validation at key points (like saving a new prompt template) rather than on every single request if cost sensitivity is high.

Are input and output tokens priced the same? No. Output tokens are generally priced higher than input tokens for Claude models. Always track them separately in your usage logs so your cost calculations stay accurate.

Why does my token count differ from a character-count estimate? Claude's tokenizer handles whitespace, punctuation, and non-English text differently than a simple character or word count. Formatting like markdown and JSON also tokenizes differently than plain prose, which is why exact counting endpoints are more reliable than rule-of-thumb estimates.