Skip to main content

​
POST /v1/messages/count_tokens

Count the number of tokens that would be used by a messages request. This is useful for estimating costs and ensuring you stay within model token limits.
This endpoint is specific to Anthropic’s API format. For OpenAI-format requests, token counting is typically done client-side or through the provider’s tokenizer.

​
Authentication

Requires provider authentication headers: 
x-portkey-provider: anthropic
Authorization: Bearer YOUR_ANTHROPIC_API_KEY

​
Request

​
Headers

​
x-portkey-provider
string
required
Must be set to anthropic
​
Authorization
string
required
Bearer token for Anthropic API
​
anthropic-version
string
API version (e.g., 2023-06-01)

​
Body Parameters

​
model
string
required
The model to count tokens for (e.g., claude-3-5-sonnet-20241022)
​
messages
array
required
Array of message objects in Anthropic format
​
system
string
System prompt (optional)
​
tools
array
Array of tool definitions (if using tool calling)

​
Response

​
input_tokens
integer
Number of tokens in the input (messages + system prompt + tools)

​
Example

curl https://localhost:8787/v1/messages/count_tokens \
  -H "x-portkey-provider: anthropic" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "system": "You are a helpful assistant.",
    "messages": [
      {
        "role": "user",
        "content": "Hello! How are you today?"
      }
    ]
  }'

​
Response Example

{
  "input_tokens": 28
}

​
Use Cases

Calculate the cost of a request before sending it by counting tokens and multiplying by the model’s per-token price.
Ensure your messages fit within the model’s context window (e.g., 200K tokens for Claude 3.5 Sonnet).
Compare token counts across different prompt formulations to optimize for cost and efficiency.
Determine which messages to keep or remove when approaching token limits in multi-turn conversations.

​
Token Counting with Tools

When using tool calling, tools are included in the token count: 
token_count = client.messages.count_tokens(
    model="claude-3-5-sonnet-20241022",
    messages=[{"role": "user", "content": "What's the weather?"}],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            }
        }
    ]
)

​
Pricing

Token counting requests do not consume any tokens or incur costs. Use this endpoint freely to estimate costs before making actual API calls.

Create Message

Send a messages request to Claude

Anthropic Provider

Anthropic integration guide

Build docs developers (and LLMs) love

Get started for freeTalk to us