​
What Is a Token?

A token is the basic unit of text that Claude processes. Tokens are not the same as words — they are chunks of characters that the model’s tokenizer splits text into before processing. As a rough guide:
These are approximations. Actual token counts vary by language, punctuation, and word complexity. Technical content with long variable names or URLs may tokenize differently than plain prose.

​
Input and Output Tokens

Every API request involves two types of tokens: Both are returned in the usage object of every response:

​
How Token Counts Grow

Token counts are not fixed, they grow with the complexity of your request. Here is what was observed across real API tests:
Tool definitions are the single biggest driver of input token costs. Every tool you define — its name, description, and input schema — is included in the input token count on every request, whether Claude uses the tool or not.

​
Tokens in Streaming Responses

Streaming responses split token reporting across two events:
  • message_start → input_tokens reported here
  • message_delta → output_tokens reported here
Input tokens are known before generation begins. Output tokens are only known after generation completes — which is why they appear at the end of the stream in the message_delta event. This matters for applications doing real-time cost tracking — you cannot know the full cost of a streaming request until the stream ends.

​
Cache Tokens

Every response includes cache-related fields in the usage object:
These fields relate to Anthropic’s prompt caching feature — a way to reduce costs on repeated requests that share a large common prefix, such as a long system prompt or a shared document. When caching is not enabled, all four fields return 0. For most standard integrations this is expected behavior.

​
Managing Token Costs

​
Control Output Length

The max_tokens parameter sets a hard ceiling on output tokens. Set it to match your use case — not arbitrarily high:
Setting max_tokens too low causes silent truncation. A request with max_tokens: 0 returns a 200 OK with an empty content array and stop_reason: "max_tokens" — no error is thrown. Always check stop_reason to confirm a response is complete.

​
Constrain Output in Your System Prompt

You can also control output length through your system prompt:
This is softer than max_tokens — Claude will try to comply but is not hard-limited. Use both together for the most predictable output length.

​
Summarize Long Conversations

In multi-turn applications, input tokens accumulate with every request because the full conversation history is passed each time. For long conversations, consider summarizing older turns: Instead of passing 20 raw messages, pass a summary of the first 15 and the last 5 in full. This keeps input token counts manageable without losing important context.

​
Keep Tool Definitions Concise

Tool definitions are included in input tokens on every request. A verbose tool description with unnecessary detail costs tokens on every single call. Write tool descriptions that are clear and specific — not exhaustive.

​
Always Check stop_reason

Token limits interact directly with response completeness. Before processing any response, check stop_reason: A 200 OK status code only means the request was received successfully — it does not mean the response is complete.

​
Next Steps

API Reference

See all request parameters including max_tokens

Streaming

Understand how token reporting works across streaming events

Tool Use

Learn why tool definitions are the biggest driver of input tokens

Error Handling

Handle truncated responses and token limit errors gracefully