Count Message Tokens

Count the number of tokens in a message for Anthropic models

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

Show message object

role · string · required

Either user or assistant

content · string | array · required

Message content (text or array of content blocks)

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

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

Cost Estimation

Calculate the cost of a request before sending it by counting tokens and multiplying by the model’s per-token price.

Context Window Management

Ensure your messages fit within the model’s context window (e.g., 200K tokens for Claude 3.5 Sonnet).

Prompt Optimization

Compare token counts across different prompt formulations to optimize for cost and efficiency.

Dynamic Context Trimming

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.

Related Endpoints

Create Message

Send a messages request to Claude

Anthropic Provider

Anthropic integration guide