# How to Count Tokens Before Sending a Request with the Anthropic Python SDK

> Discover how to count tokens before sending requests with the Anthropic Python SDK. Use the count_tokens method to preview exact token consumption and avoid unexpected costs. Learn more now.

- Repository: [Anthropic/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Tags: how-to-guide
- Published: 2026-02-23

---

**The Anthropic Python SDK provides a dedicated `count_tokens` method on the Messages resource that previews exact token consumption—including tools, images, and system prompts—before you incur generation costs.**

The `anthropics/anthropic-sdk-python` repository ships with a first-class **Token Count API** designed for cost estimation and context window management. By counting tokens before sending a request, you can prevent runtime errors, optimize prompt length, and accurately budget for complex multimodal workflows.

## Understanding the Token Count API

The SDK implements token counting as a synchronous method on both stable and beta versions of the Messages resource. Unlike the standard generation endpoint, this API returns only metadata about token distribution without producing model output.

### Implementation in the Source Code

The public `count_tokens` method is implemented in [`src/anthropic/resources/messages/messages.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/messages/messages.py) at lines 1264–1283. For beta functionality, the equivalent method resides in [`src/anthropic/resources/beta/messages/messages.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/messages/messages.py) at lines 1622–1660.

Both implementations construct a `MessageCountTokensParams` object from your arguments (`messages`, `model`, `tools`, etc.) and dispatch a **POST** request to the Anthropic service. The stable endpoint targets `"/v1/messages/count_tokens"`, while the beta variant appends `?beta=true` to support experimental parameters.

### How the Request Flow Works

Under the hood, the SDK follows a three-step process:

1. **Parameter preparation** – Your input is validated against `MessageCountTokensParams` and serialized into JSON.
2. **HTTP dispatch** – The `_post` method sends the payload to the appropriate endpoint with `body=params` and request options.
3. **Response parsing** – The server returns a `MessageTokensCount` object containing `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, and other usage fields, which the SDK deserializes into a typed Python model.

## Why Count Tokens Before Sending Requests?

Counting tokens prior to generation provides several production-grade benefits:

- **Cost estimation** – Know the exact input token count (and expected output budget) before the API call to prevent surprise billing.
- **Prompt sizing** – Verify that large prompts stay within the model’s context window (e.g., 100 k tokens) to avoid `max_tokens` runtime errors.
- **Dynamic truncation** – Programmatically trim or chunk conversations when counts exceed thresholds, keeping applications responsive.
- **Tool-aware budgeting** – The endpoint calculates tokens for tool definitions, images, and documents, delivering a true-to-life estimate for complex payloads.

## How to Count Tokens: Practical Examples

### Basic Token Counting for Single Messages

Use `client.messages.count_tokens` to audit a simple user message before generation:

```python
from anthropic import Anthropic

client = Anthropic(api_key="YOUR_API_KEY")

messages = [
    {"role": "user", "content": "Explain quantum computing in one paragraph."}
]

token_info = client.messages.count_tokens(
    messages=messages,
    model="claude-3-haiku-20240307"
)

print("Input tokens:", token_info.input_tokens)
print("Estimated output tokens:", token_info.output_tokens)

```

### Counting Tokens with Tools and System Prompts

When using function calling or system instructions, include all parameters in the count request to capture the full token footprint:

```python
from anthropic import Anthropic

client = Anthropic(api_key="YOUR_API_KEY")

tools = [
    {
        "name": "weather",
        "description": "Get current weather for a location.",
        "input_schema": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
        },
    }
]

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the weather in Paris?"},
]

token_info = client.messages.count_tokens(
    messages=messages,
    model="claude-3-opus-20240229",
    tools=tools,
)

print(token_info)

# Output: MessageTokensCount(input_tokens=..., output_tokens=..., cache_creation_input_tokens=0, ...)

```

### Using the Beta API Endpoint

For newer model features, access the beta token counter via `client.beta.messages.count_tokens`:

```python
from anthropic import Anthropic

client = Anthropic(api_key="YOUR_API_KEY")

messages = [
    {"role": "user", "content": "Summarize the attached PDF."}
]

# Beta supports additional flags like 'speed'

token_info = client.beta.messages.count_tokens(
    messages=messages,
    model="claude-3-5-sonnet-20240620",
    speed="fast",
)

print(token_info.input_tokens, token_info.output_tokens)

```

### Dynamic Truncation Workflow

Implement a trimming loop to enforce context limits before sending:

```python
MAX_TOKENS = 100_000

def trim_conversation(messages, model):
    while True:
        token_info = client.messages.count_tokens(messages=messages, model=model)
        if token_info.input_tokens <= MAX_TOKENS:
            break
        # Remove oldest user-assistant pair (assumes alternating turns)

        messages = messages[2:]
    return messages

```

## Summary

- The **Token Count API** lives at `client.messages.count_tokens` with a beta variant at `client.beta.messages.count_tokens`.
- Source implementations are located in [`src/anthropic/resources/messages/messages.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/messages/messages.py) and the corresponding beta directory.
- The endpoint accepts the same parameters as `messages.create` but returns a `MessageTokensCount` object instead of generated text.
- Token counting supports **multimodal inputs**, **tool definitions**, and **system prompts** for accurate pre-flight estimation.
- Use this flow to enforce **context limits**, **estimate costs**, and **dynamically truncate** conversations.

## Frequently Asked Questions

### Does the token count API incur generation charges?

No, the endpoint returns token usage metadata—including `input_tokens` and `output_tokens`—without performing actual text generation, allowing you to estimate costs before sending the main request.

### What fields are included in the token count response?

The response deserializes into a `MessageTokensCount` typed model containing fields such as `input_tokens`, `output_tokens`, and `cache_creation_input_tokens`, providing a complete breakdown of expected usage.

### Can I count tokens for multimodal inputs like images and documents?

Yes, according to the source implementation, the endpoint processes tool definitions, images, and documents included in your request payload, delivering a comprehensive token count for complex, multimodal prompts.

### What is the difference between the stable and beta token count methods?

The stable method in [`src/anthropic/resources/messages/messages.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/messages/messages.py) targets `"/v1/messages/count_tokens"`, while the beta version in [`src/anthropic/resources/beta/messages/messages.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/beta/messages/messages.py) supports additional beta-specific parameters and targets `"/v1/messages/count_tokens?beta=true"`.