Skip to main content
POST
/
v1
/
messages
/
count_tokens
curl --request POST \
  --url https://api.mixroute.ai/v1/messages/count_tokens \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

{
  "input_tokens": 14
}

​
Introduction

Calculate the token count for Claude messages, used for cost estimation before sending requests. This endpoint does not consume quota, only performs local calculation.

​
Authentication

Bearer Token, e.g., Bearer sk-xxxxxxxxxx

​
Request Parameters

​
model
string
required
Claude model identifier, supported models include:
  • claude-sonnet-4-20250514
  • claude-sonnet-4-5-20250929
  • claude-haiku-4-5-20251001
  • claude-opus-4-5-20251101 (recommended replacement for claude-3-opus)
  • Other Claude series models
​
messages
array
required
Conversation messages list, each element contains role (user/assistant) and content. content can be a string or media content array.Supported content types:
  • Plain text messages
  • Multimodal messages (with images)
  • Tool call results
​
system
string
System prompt (optional), can be a string or media content array. Used to set model behavior and role.
​
tools
array
Tool definition list (optional), used to calculate tool call related token count.

​
Response Parameters

​
input_tokens
integer
Total token count of input messages, including:
  • All messages token count
  • System prompt token count
  • Tools definition token count (if any)

​
Basic Examples

curl -X POST "https://api.mixroute.ai/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ]
  }'

​
Python Example

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-xxxxxxxxxx",
    base_url="https://api.mixroute.ai"
)

# Count tokens
response = client.messages.count_tokens(
    model="claude-sonnet-4-5-20250929",
    system="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

print(f"Input tokens: {response.input_tokens}")

​
Response Example

{
  "input_tokens": 14
}

​
Advanced Use Cases

curl -X POST "https://api.mixroute.ai/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {
        "role": "user",
        "content": "What is the weather in San Francisco?"
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ]
  }'

​
Use Cases

​
1. Cost Estimation

Calculate token count before sending bulk requests to estimate costs: 
# Batch cost calculation
messages_batch = [...]  # Batch messages
total_tokens = 0

for messages in messages_batch:
    response = client.messages.count_tokens(
        model="claude-sonnet-4-5-20250929",
        messages=messages
    )
    total_tokens += response.input_tokens

# Calculate total cost based on pricing
cost = total_tokens * price_per_token
print(f"Estimated cost: ${cost:.4f}")

​
2. Context Window Management

Check if messages exceed the model’s context window limit: 
MAX_CONTEXT_WINDOW = 200000  # Claude Sonnet 4.5 context window

response = client.messages.count_tokens(
    model="claude-sonnet-4-5-20250929",
    messages=long_conversation
)

if response.input_tokens > MAX_CONTEXT_WINDOW:
    print(f"Warning: Message token count ({response.input_tokens}) exceeds context window limit")
    # Execute message truncation or summarization

​
3. Prompt Optimization

Compare token consumption of different prompts: 
prompts = [
    "Concise prompt...",
    "Detailed prompt...",
    "Very detailed prompt..."
]

for prompt in prompts:
    response = client.messages.count_tokens(
        model="claude-sonnet-4-5-20250929",
        system=prompt,
        messages=[{"role": "user", "content": "Test"}]
    )
    print(f"{len(prompt)} characters -> {response.input_tokens} tokens")

​
Notes

  • This endpoint does not make actual AI requests, does not consume quota
  • Does not include output-related parameters like max_tokens, only calculates input token count
  • Image tokens use fixed estimates (approx 1000 tokens), actual may vary based on resolution

​
Error Handling

​
Missing Required Parameters

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Key: 'ClaudeCountTokensRequest.Model' Error:Field validation for 'Model' failed on the 'required' tag"
  }
}

​
Invalid API Key

{
  "error": {
    "message": "Invalid token",
    "type": "invalid_request_error"
  }
}

curl --request POST \
  --url https://api.mixroute.ai/v1/messages/count_tokens \
  --header 'Authorization: Bearer sk-xxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

{
  "input_tokens": 14
}