SPB Git

Repository Public

token-counting.md 42.4 KB 1,448 lines markdown

1---2title: Token counting3url: https://platform.claude.com/docs/en/build-with-claude/token-counting4description: Count the tokens in a message before you send it to Claude. Use token counts to manage rate limits and costs, make model routing decisions, and fit prompts to a target length.5---67## Compatibility8- [ZDR](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention): eligible (excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements))9- Platforms: Claude API, Claude Platform on AWS, Amazon Bedrock, Google Cloud, Microsoft Foundry1011Token counting lets you determine the number of tokens in a message before you send it to Claude. This helps you make informed decisions about your prompts and usage. With token counting, you can:1213* Proactively manage rate limits and costs14* Make smart model routing decisions15* Optimize prompts to a specific length1617***1819## How to count message tokens2021The [token counting](https://platform.claude.com/docs/en/api/messages-count-tokens) endpoint accepts the same structured list of inputs for creating a message, including support for system prompts, [tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview), [images](https://platform.claude.com/docs/en/build-with-claude/vision), and [PDFs](https://platform.claude.com/docs/en/build-with-claude/pdf-support). The response contains the total number of input tokens.2223This endpoint returns an `invalid_request_error` for a few inputs that the Messages API accepts: [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) such as web search, web fetch, code execution, and tool search (every server tool except the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)), the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector), and `image` or `document` blocks with a `url` or `file` source. Send images and PDFs as base64 to count them. For requests that use server tools or MCP servers, the Messages API response reports the tokens used in its `usage` object.2425<Note>26  The token count is an **estimate**. In some cases, the actual number of input tokens used when creating a message might differ by a small amount.2728  Token counts may include tokens added automatically by Anthropic for system optimizations. **You are not billed for system-added tokens**. Billing reflects only your content.29</Note>3031### Supported models3233All [active models](https://platform.claude.com/docs/en/models/overview) support token counting.3435<Note>36  Claude 4.7 and later models and Claude Mythos Preview use a newer tokenizer. The same input text produces approximately 30 percent more tokens than on earlier models. The exact increase depends on the content and workload shape. Recount prompts against the model you plan to use rather than reusing counts measured against earlier models.37</Note>3839### Count tokens in basic messages4041<CodeGroup>42  ```bash cURL43  curl https://api.anthropic.com/v1/messages/count_tokens \44    -H "x-api-key: $ANTHROPIC_API_KEY" \45    -H "content-type: application/json" \46    -H "anthropic-version: 2023-06-01" \47    -d '{48      "model": "claude-opus-5",49      "system": "You are a scientist",50      "messages": [{51        "role": "user",52        "content": "Hello, Claude"53      }]54    }'55  ```5657  ```bash CLI58  ant messages count-tokens \59    --model claude-opus-5 \60    --system "You are a scientist" \61    --message '{role: user, content: "Hello, Claude"}'62  ```6364  ```python Python65  client = anthropic.Anthropic()6667  response = client.messages.count_tokens(68      model="claude-opus-5",69      system="You are a scientist",70      messages=[{"role": "user", "content": "Hello, Claude"}],71  )7273  print(response.json())74  ```7576  ```typescript TypeScript77  const client = new Anthropic();7879  const response = await client.messages.countTokens({80    model: "claude-opus-5",81    system: "You are a scientist",82    messages: [83      {84        role: "user",85        content: "Hello, Claude"86      }87    ]88  });8990  console.log(response);91  ```9293  ```csharp C#94  using System;95  using System.Threading.Tasks;96  using Anthropic;97  using Anthropic.Models.Messages;9899  AnthropicClient client = new();100101  var parameters = new MessageCountTokensParams102  {103      Model = Model.ClaudeOpus5,104      System = "You are a scientist",105      Messages = [new() { Role = Role.User, Content = "Hello, Claude" }]106  };107108  var response = await client.Messages.CountTokens(parameters);109  Console.WriteLine(response);110  ```111112  ```go Go113  client := anthropic.NewClient()114115  response, err := client.Messages.CountTokens(context.TODO(), anthropic.MessageCountTokensParams{116  	Model: anthropic.ModelClaudeOpus5,117  	System: anthropic.MessageCountTokensParamsSystemUnion{118  		OfString: anthropic.String("You are a scientist"),119  	},120  	Messages: []anthropic.MessageParam{121  		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),122  	},123  })124  if err != nil {125  	log.Fatal(err)126  }127128  fmt.Println(response)129  ```130131  ```java Java132  import com.anthropic.models.messages.MessageCountTokensParams;133  import com.anthropic.models.messages.MessageTokensCount;134  // ...135136  public class CountTokensExample {137138    public static void main(String[] args) {139      AnthropicClient client = AnthropicOkHttpClient.fromEnv();140141      MessageCountTokensParams params = MessageCountTokensParams.builder()142        .model(Model.CLAUDE_OPUS_5)143        .system("You are a scientist")144        .addUserMessage("Hello, Claude")145        .build();146147      MessageTokensCount count = client.messages().countTokens(params);148      System.out.println(count);149    }150  }151  ```152153  ```php PHP154  $client = new Client();155156  $response = $client->messages->countTokens(157      messages: [158          ['role' => 'user', 'content' => 'Hello, Claude']159      ],160      model: 'claude-opus-5',161      system: 'You are a scientist',162  );163164  echo json_encode($response);165  ```166167  ```ruby Ruby168  client = Anthropic::Client.new169170  response = client.messages.count_tokens(171    model: "claude-opus-5",172    system: "You are a scientist",173    messages: [174      { role: "user", content: "Hello, Claude" }175    ]176  )177178  puts response179  ```180</CodeGroup>181182```json Output183{ "input_tokens": 14 }184```185186### Count tokens in messages with tools187188<Note>189  Token counting supports client tools and the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool). Requests that include other [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) return an error. For the advisor tool, the count covers the executor's first sampling call only.190</Note>191192<CodeGroup>193  ```bash cURL194  curl https://api.anthropic.com/v1/messages/count_tokens \195    -H "x-api-key: $ANTHROPIC_API_KEY" \196    -H "content-type: application/json" \197    -H "anthropic-version: 2023-06-01" \198    -d '{199      "model": "claude-opus-5",200      "tools": [201        {202          "name": "get_weather",203          "description": "Get the current weather in a given location",204          "input_schema": {205            "type": "object",206            "properties": {207              "location": {208                "type": "string",209                "description": "The city and state, e.g. San Francisco, CA"210              }211            },212            "required": ["location"]213          }214        }215      ],216      "messages": [217        {218          "role": "user",219          "content": "What'\''s the weather like in San Francisco?"220        }221      ]222    }'223  ```224225  ```bash CLI226  ant messages count-tokens <<'YAML'227  model: claude-opus-5228  tools:229    - name: get_weather230      description: Get the current weather in a given location231      input_schema:232        type: object233        properties:234          location:235            type: string236            description: The city and state, e.g. San Francisco, CA237        required:238          - location239  messages:240    - role: user241      content: What's the weather like in San Francisco?242  YAML243  ```244245  ```python Python246  client = anthropic.Anthropic()247248  response = client.messages.count_tokens(249      model="claude-opus-5",250      tools=[251          {252              "name": "get_weather",253              "description": "Get the current weather in a given location",254              "input_schema": {255                  "type": "object",256                  "properties": {257                      "location": {258                          "type": "string",259                          "description": "The city and state, e.g. San Francisco, CA",260                      }261                  },262                  "required": ["location"],263              },264          }265      ],266      messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],267  )268269  print(response.json())270  ```271272  ```typescript TypeScript273  const client = new Anthropic();274275  const response = await client.messages.countTokens({276    model: "claude-opus-5",277    tools: [278      {279        name: "get_weather",280        description: "Get the current weather in a given location",281        input_schema: {282          type: "object",283          properties: {284            location: {285              type: "string",286              description: "The city and state, e.g. San Francisco, CA"287            }288          },289          required: ["location"]290        }291      }292    ],293    messages: [{ role: "user", content: "What's the weather like in San Francisco?" }]294  });295296  console.log(response);297  ```298299  ```csharp C#300  using System;301  using System.Collections.Generic;302  using System.Text.Json;303  using System.Threading.Tasks;304  using Anthropic;305  using Anthropic.Models.Messages;306307  AnthropicClient client = new();308309  var parameters = new MessageCountTokensParams310  {311      Model = Model.ClaudeOpus5,312      Tools =313      [314          new MessageCountTokensTool(new Tool()315          {316              Name = "get_weather",317              Description = "Get the current weather in a given location",318              InputSchema = new InputSchema()319              {320                  Properties = new Dictionary<string, JsonElement>321                  {322                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }),323                  },324                  Required = ["location"],325              },326          }),327      ],328      Messages = [new() { Role = Role.User, Content = "What's the weather like in San Francisco?" }]329  };330331  var count = await client.Messages.CountTokens(parameters);332  Console.WriteLine(count);333  ```334335  ```go Go336  client := anthropic.NewClient()337338  response, err := client.Messages.CountTokens(context.TODO(), anthropic.MessageCountTokensParams{339  	Model: anthropic.ModelClaudeOpus5,340  	Tools: []anthropic.MessageCountTokensToolUnionParam{341  		{OfTool: &anthropic.ToolParam{342  			Name:        "get_weather",343  			Description: anthropic.String("Get the current weather in a given location"),344  			InputSchema: anthropic.ToolInputSchemaParam{345  				Properties: map[string]any{346  					"location": map[string]any{347  						"type":        "string",348  						"description": "The city and state, e.g. San Francisco, CA",349  					},350  				},351  				Required: []string{"location"},352  			},353  		}},354  	},355  	Messages: []anthropic.MessageParam{356  		anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")),357  	},358  })359  if err != nil {360  	log.Fatal(err)361  }362363  jsonData, _ := json.MarshalIndent(response, "", "  ")364  fmt.Println(string(jsonData))365  ```366367  ```java Java368  import com.anthropic.models.messages.MessageCountTokensParams;369  import com.anthropic.models.messages.MessageTokensCount;370  // ...371      AnthropicClient client = AnthropicOkHttpClient.fromEnv();372373      InputSchema schema = InputSchema.builder()374        .properties(375          JsonValue.from(376            Map.of(377              "location",378              Map.of(379                "type",380                "string",381                "description",382                "The city and state, e.g. San Francisco, CA"383              )384            )385          )386        )387        .putAdditionalProperty("required", JsonValue.from(List.of("location")))388        .build();389390      MessageCountTokensParams params = MessageCountTokensParams.builder()391        .model(Model.CLAUDE_OPUS_5)392        .addTool(393          Tool.builder()394            .name("get_weather")395            .description("Get the current weather in a given location")396            .inputSchema(schema)397            .build()398        )399        .addUserMessage("What's the weather like in San Francisco?")400        .build();401402      MessageTokensCount count = client.messages().countTokens(params);403      System.out.println(count);404  ```405406  ```php PHP407  $client = new Client();408409  $response = $client->messages->countTokens(410      messages: [411          ['role' => 'user', 'content' => "What's the weather like in San Francisco?"]412      ],413      model: 'claude-opus-5',414      tools: [415          [416              'name' => 'get_weather',417              'description' => 'Get the current weather in a given location',418              'input_schema' => [419                  'type' => 'object',420                  'properties' => [421                      'location' => [422                          'type' => 'string',423                          'description' => 'The city and state, e.g. San Francisco, CA'424                      ]425                  ],426                  'required' => ['location']427              ]428          ]429      ],430  );431432  echo json_encode($response, JSON_PRETTY_PRINT);433  ```434435  ```ruby Ruby436  client = Anthropic::Client.new437438  response = client.messages.count_tokens(439    model: "claude-opus-5",440    tools: [441      {442        name: "get_weather",443        description: "Get the current weather in a given location",444        input_schema: {445          type: "object",446          properties: {447            location: {448              type: "string",449              description: "The city and state, e.g. San Francisco, CA"450            }451          },452          required: ["location"]453        }454      }455    ],456    messages: [457      { role: "user", content: "What's the weather like in San Francisco?" }458    ]459  )460461  puts response462  ```463</CodeGroup>464465```json Output466{ "input_tokens": 403 }467```468469### Count tokens in messages with images470471<CodeGroup>472  ```bash cURL473  #!/bin/sh474475  IMAGE_URL="https://platform.claude.com/docs/images/vision-example.jpg"476  IMAGE_MEDIA_TYPE="image/jpeg"477  IMAGE_BASE64=$(curl -s "$IMAGE_URL" | base64 | tr -d '\n')478479  curl https://api.anthropic.com/v1/messages/count_tokens \480    -H "x-api-key: $ANTHROPIC_API_KEY" \481    -H "anthropic-version: 2023-06-01" \482    -H "content-type: application/json" \483    -d @- <<EOF484  {485    "model": "claude-opus-5",486    "messages": [487      {"role": "user", "content": [488        {"type": "image", "source": {489          "type": "base64",490          "media_type": "$IMAGE_MEDIA_TYPE",491          "data": "$IMAGE_BASE64"492        }},493        {"type": "text", "text": "Describe this image"}494      ]}495    ]496  }497  EOF498  ```499500  ```bash CLI501  IMAGE_URL="https://platform.claude.com/docs/images/vision-example.jpg"502  curl -s "$IMAGE_URL" -o ./vision-example.jpg503504  ant messages count-tokens <<'YAML'505  model: claude-opus-5506  messages:507    - role: user508      content:509        - type: image510          source:511            type: base64512            media_type: image/jpeg513            data: "@./vision-example.jpg"514        - type: text515          text: Describe this image516  YAML517  ```518519  ```python Python520  import base64521  import httpx2522523  image_url = "https://platform.claude.com/docs/images/vision-example.jpg"524  image_media_type = "image/jpeg"525  image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")526527  client = anthropic.Anthropic()528529  response = client.messages.count_tokens(530      model="claude-opus-5",531      messages=[532          {533              "role": "user",534              "content": [535                  {536                      "type": "image",537                      "source": {538                          "type": "base64",539                          "media_type": image_media_type,540                          "data": image_data,541                      },542                  },543                  {"type": "text", "text": "Describe this image"},544              ],545          }546      ],547  )548  print(response.json())549  ```550551  ```typescript TypeScript552  const anthropic = new Anthropic();553554  const imageUrl = "https://platform.claude.com/docs/images/vision-example.jpg";555  const imageMediaType = "image/jpeg";556  const imageArrayBuffer = await (await fetch(imageUrl)).arrayBuffer();557  const imageData = Buffer.from(imageArrayBuffer).toString("base64");558559  const response = await anthropic.messages.countTokens({560    model: "claude-opus-5",561    messages: [562      {563        role: "user",564        content: [565          {566            type: "image",567            source: {568              type: "base64",569              media_type: imageMediaType,570              data: imageData571            }572          },573          {574            type: "text",575            text: "Describe this image"576          }577        ]578      }579    ]580  });581  console.log(response);582  ```583584  ```csharp C#585  using System;586  using System.Collections.Generic;587  using System.Net.Http;588  using System.Threading.Tasks;589  using Anthropic;590  using Anthropic.Models.Messages;591592  AnthropicClient client = new();593594  string imageUrl = "https://platform.claude.com/docs/images/vision-example.jpg";595596  using HttpClient httpClient = new();597  byte[] imageBytes = await httpClient.GetByteArrayAsync(imageUrl);598  string imageData = Convert.ToBase64String(imageBytes);599600  var parameters = new MessageCountTokensParams601  {602      Model = Model.ClaudeOpus5,603      Messages =604      [605          new()606          {607              Role = Role.User,608              Content = new MessageParamContent(new List<ContentBlockParam>609              {610                  new ContentBlockParam(new ImageBlockParam(611                      new ImageBlockParamSource(new Base64ImageSource()612                      {613                          Data = imageData,614                          MediaType = MediaType.ImageJpeg,615                      })616                  )),617                  new ContentBlockParam(new TextBlockParam("Describe this image")),618              }),619          }620      ]621  };622623  var count = await client.Messages.CountTokens(parameters);624  Console.WriteLine(count);625  ```626627  ```go Go628  imageURL := "https://platform.claude.com/docs/images/vision-example.jpg"629630  req, err := http.NewRequest("GET", imageURL, nil)631  if err != nil {632  	log.Fatal(err)633  }634  req.Header.Set("User-Agent", "AnthropicDocsBot/1.0")635636  resp, err := http.DefaultClient.Do(req)637  if err != nil {638  	log.Fatal(err)639  }640  defer resp.Body.Close()641642  imageBytes, err := io.ReadAll(resp.Body)643  if err != nil {644  	log.Fatal(err)645  }646  imageData := base64.StdEncoding.EncodeToString(imageBytes)647648  client := anthropic.NewClient()649650  response, err := client.Messages.CountTokens(context.TODO(), anthropic.MessageCountTokensParams{651  	Model: anthropic.ModelClaudeOpus5,652  	Messages: []anthropic.MessageParam{653  		anthropic.NewUserMessage(654  			anthropic.NewImageBlockBase64("image/jpeg", imageData),655  			anthropic.NewTextBlock("Describe this image"),656  		),657  	},658  })659  if err != nil {660  	log.Fatal(err)661  }662663  fmt.Println(response)664  ```665666  ```java Java667  import com.anthropic.models.messages.Base64ImageSource;668  // ...669  import com.anthropic.models.messages.MessageCountTokensParams;670  import com.anthropic.models.messages.MessageTokensCount;671  // ...672      AnthropicClient client = AnthropicOkHttpClient.fromEnv();673674      String imageUrl =675        "https://platform.claude.com/docs/images/vision-example.jpg";676      String imageMediaType = "image/jpeg";677678      HttpClient httpClient = HttpClient.newHttpClient();679      HttpRequest request = HttpRequest.newBuilder().uri(URI.create(imageUrl)).build();680      byte[] imageBytes = httpClient681        .send(request, HttpResponse.BodyHandlers.ofByteArray())682        .body();683      String imageBase64 = Base64.getEncoder().encodeToString(imageBytes);684685      ContentBlockParam imageBlock = ContentBlockParam.ofImage(686        ImageBlockParam.builder()687          .source(688            Base64ImageSource.builder()689              .mediaType(Base64ImageSource.MediaType.IMAGE_JPEG)690              .data(imageBase64)691              .build()692          )693          .build()694      );695696      ContentBlockParam textBlock = ContentBlockParam.ofText(697        TextBlockParam.builder().text("Describe this image").build()698      );699700      MessageCountTokensParams params = MessageCountTokensParams.builder()701        .model(Model.CLAUDE_OPUS_5)702        .addUserMessageOfBlockParams(List.of(imageBlock, textBlock))703        .build();704705      MessageTokensCount count = client.messages().countTokens(params);706      System.out.println(count);707  ```708709  ```php PHP710  $imageUrl = "https://platform.claude.com/docs/images/vision-example.jpg";711  $imageMediaType = "image/jpeg";712  $imageData = base64_encode(file_get_contents($imageUrl));713714  $client = new Client();715716  $response = $client->messages->countTokens(717      messages: [718          [719              'role' => 'user',720              'content' => [721                  [722                      'type' => 'image',723                      'source' => [724                          'type' => 'base64',725                          'media_type' => $imageMediaType,726                          'data' => $imageData727                      ]728                  ],729                  ['type' => 'text', 'text' => 'Describe this image']730              ]731          ]732      ],733      model: 'claude-opus-5',734  );735  print_r($response);736  ```737738  ```ruby Ruby739  require "base64"740  require "net/http"741742  image_url = "https://platform.claude.com/docs/images/vision-example.jpg"743  image_media_type = "image/jpeg"744745  uri = URI(image_url)746  image_data = Base64.strict_encode64(Net::HTTP.get(uri))747748  client = Anthropic::Client.new749750  response = client.messages.count_tokens(751    model: "claude-opus-5",752    messages: [753      {754        role: "user",755        content: [756          {757            type: "image",758            source: {759              type: "base64",760              media_type: image_media_type,761              data: image_data762            }763          },764          { type: "text", text: "Describe this image" }765        ]766      }767    ]768  )769  puts response770  ```771</CodeGroup>772773```json Output774{ "input_tokens": 1028 }775```776777An embedded image block that sets [`"oversized_image": "error"`](https://platform.claude.com/docs/en/build-with-claude/vision-coordinates#oversized-image-error) is rejected at count time exactly as the Messages API would reject it.778779### Count tokens in messages with thinking780781<Note>782  See [Thinking and the context window](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-the-context-window) for more details.783784  * Thinking blocks from **previous** assistant turns count toward your input tokens on models that [keep all prior turns](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model); on models that keep only the last turn, the API strips them and they do **not** count785  * **Current** assistant turn thinking **does** count toward your input tokens786</Note>787788<CodeGroup>789  ```bash cURL790  curl https://api.anthropic.com/v1/messages/count_tokens \791    -H "x-api-key: $ANTHROPIC_API_KEY" \792    -H "content-type: application/json" \793    -H "anthropic-version: 2023-06-01" \794    -d '{795      "model": "claude-opus-5",796      "thinking": {797        "type": "adaptive"798      },799      "messages": [800        {801          "role": "user",802          "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"803        },804        {805          "role": "assistant",806          "content": [807            {808              "type": "thinking",809              "thinking": "This is a nice number theory question. Lets think about it step by step...",810              "signature": "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV..."811            },812            {813              "type": "text",814              "text": "Yes, there are infinitely many prime numbers p such that p mod 4 = 3..."815            }816          ]817        },818        {819          "role": "user",820          "content": "Can you write a formal proof?"821        }822      ]823    }'824  ```825826  ```bash CLI827  ant messages count-tokens <<'YAML'828  model: claude-opus-5829  thinking:830    type: adaptive831  messages:832    - role: user833      content: Are there an infinite number of prime numbers such that n mod 4 == 3?834    - role: assistant835      content:836        - type: thinking837          thinking: >-838            This is a nice number theory question. Lets think about it step by step...839          signature: >-840            EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...841        - type: text842          text: Yes, there are infinitely many prime numbers p such that p mod 4 = 3...843    - role: user844      content: Can you write a formal proof?845  YAML846  ```847848  ```python Python849  client = anthropic.Anthropic()850851  response = client.messages.count_tokens(852      model="claude-opus-5",853      thinking={"type": "adaptive"},854      messages=[855          {856              "role": "user",857              "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",858          },859          {860              "role": "assistant",861              "content": [862                  {863                      "type": "thinking",864                      "thinking": "This is a nice number theory question. Let's think about it step by step...",865                      "signature": "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...",866                  },867                  {868                      "type": "text",869                      "text": "Yes, there are infinitely many prime numbers p such that p mod 4 = 3...",870                  },871              ],872          },873          {"role": "user", "content": "Can you write a formal proof?"},874      ],875  )876877  print(response.json())878  ```879880  ```typescript TypeScript881  const client = new Anthropic();882883  const response = await client.messages.countTokens({884    model: "claude-opus-5",885    thinking: { type: "adaptive" },886    messages: [887      {888        role: "user",889        content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"890      },891      {892        role: "assistant",893        content: [894          {895            type: "thinking",896            thinking:897              "This is a nice number theory question. Let's think about it step by step...",898            signature:899              "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV..."900          },901          {902            type: "text",903            text: "Yes, there are infinitely many prime numbers p such that p mod 4 = 3..."904          }905        ]906      },907      {908        role: "user",909        content: "Can you write a formal proof?"910      }911    ]912  });913914  console.log(response);915  ```916917  ```csharp C#918  using System;919  using System.Threading.Tasks;920  using System.Collections.Generic;921  using Anthropic;922  using Anthropic.Models.Messages;923924  AnthropicClient client = new();925926  var parameters = new MessageCountTokensParams927  {928      Model = Model.ClaudeOpus5,929      Thinking = new ThinkingConfigAdaptive(),930      Messages =931      [932          new()933          {934              Role = Role.User,935              Content = "Are there an infinite number of prime numbers such that n mod 4 == 3?"936          },937          new()938          {939              Role = Role.Assistant,940              Content = new MessageParamContent(new List<ContentBlockParam>941              {942                  new ContentBlockParam(new ThinkingBlockParam()943                  {944                      Thinking = "This is a nice number theory question. Let's think about it step by step...",945                      Signature = "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...",946                  }),947                  new ContentBlockParam(new TextBlockParam("Yes, there are infinitely many prime numbers p such that p mod 4 = 3...")),948              }),949          },950          new()951          {952              Role = Role.User,953              Content = "Can you write a formal proof?"954          }955      ]956  };957958  var response = await client.Messages.CountTokens(parameters);959  Console.WriteLine(response);960  ```961962  ```go Go963  client := anthropic.NewClient()964965  thinkingBlock := anthropic.NewThinkingBlock(966  	"EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...",967  	"This is a nice number theory question. Let's think about it step by step...",968  )969970  textBlock := anthropic.NewTextBlock(971  	"Yes, there are infinitely many prime numbers p such that p mod 4 = 3...",972  )973974  response, err := client.Messages.CountTokens(context.TODO(), anthropic.MessageCountTokensParams{975  	Model: anthropic.ModelClaudeOpus5,976  	Thinking: anthropic.ThinkingConfigParamUnion{977  		OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{},978  	},979  	Messages: []anthropic.MessageParam{980  		anthropic.NewUserMessage(anthropic.NewTextBlock("Are there an infinite number of prime numbers such that n mod 4 == 3?")),981  		anthropic.NewAssistantMessage(thinkingBlock, textBlock),982  		anthropic.NewUserMessage(anthropic.NewTextBlock("Can you write a formal proof?")),983  	},984  })985  if err != nil {986  	log.Fatal(err)987  }988989  fmt.Printf("%+v\n", response)990  ```991992  ```java Java993  import com.anthropic.models.messages.MessageCountTokensParams;994  import com.anthropic.models.messages.MessageTokensCount;995  // ...996  import com.anthropic.models.messages.ThinkingBlockParam;997  import com.anthropic.models.messages.ThinkingConfigAdaptive;998  // ...999      AnthropicClient client = AnthropicOkHttpClient.fromEnv();10001001      List<ContentBlockParam> assistantBlocks = List.of(1002        ContentBlockParam.ofThinking(1003          ThinkingBlockParam.builder()1004            .thinking(1005              "This is a nice number theory question. Let's think about it step by step..."1006            )1007            .signature(1008              "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV..."1009            )1010            .build()1011        ),1012        ContentBlockParam.ofText(1013          TextBlockParam.builder()1014            .text("Yes, there are infinitely many prime numbers p such that p mod 4 = 3...")1015            .build()1016        )1017      );10181019      MessageCountTokensParams params = MessageCountTokensParams.builder()1020        .model(Model.CLAUDE_OPUS_5)1021        .thinking(ThinkingConfigAdaptive.builder().build())1022        .addUserMessage("Are there an infinite number of prime numbers such that n mod 4 == 3?")1023        .addAssistantMessageOfBlockParams(assistantBlocks)1024        .addUserMessage("Can you write a formal proof?")1025        .build();10261027      MessageTokensCount count = client.messages().countTokens(params);1028      System.out.println(count);1029  ```10301031  ```php PHP1032  $client = new Client();10331034  $response = $client->messages->countTokens(1035      messages: [1036          [1037              'role' => 'user',1038              'content' => 'Are there an infinite number of prime numbers such that n mod 4 == 3?'1039          ],1040          [1041              'role' => 'assistant',1042              'content' => [1043                  [1044                      'type' => 'thinking',1045                      'thinking' => 'This is a nice number theory question. Let\'s think about it step by step...',1046                      'signature' => 'EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV...'1047                  ],1048                  [1049                      'type' => 'text',1050                      'text' => 'Yes, there are infinitely many prime numbers p such that p mod 4 = 3...'1051                  ]1052              ]1053          ],1054          [1055              'role' => 'user',1056              'content' => 'Can you write a formal proof?'1057          ]1058      ],1059      model: 'claude-opus-5',1060      thinking: ['type' => 'adaptive'],1061  );10621063  echo json_encode($response);1064  ```10651066  ```ruby Ruby1067  client = Anthropic::Client.new10681069  response = client.messages.count_tokens(1070    model: "claude-opus-5",1071    thinking: {1072      type: "adaptive"1073    },1074    messages: [1075      {1076        role: "user",1077        content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"1078      },1079      {1080        role: "assistant",1081        content: [1082          {1083            type: "thinking",1084            thinking: "This is a nice number theory question. Let's think about it step by step...",1085            signature: "EuYBCkQYAiJAgCs1le6/Pol5Z4/JMomVOouGrWdhYNsH3ukzUECbB6iWrSQtsQuRHJID6lWV..."1086          },1087          {1088            type: "text",1089            text: "Yes, there are infinitely many prime numbers p such that p mod 4 = 3..."1090          }1091        ]1092      },1093      {1094        role: "user",1095        content: "Can you write a formal proof?"1096      }1097    ]1098  )10991100  puts response1101  ```1102</CodeGroup>11031104```json Output1105{ "input_tokens": 88 }1106```11071108### Count tokens in messages with PDFs11091110<Note>1111  Token counting supports base64-encoded PDFs with the same [PDF requirements](https://platform.claude.com/docs/en/build-with-claude/pdf-support#check-pdf-requirements) as the Messages API. This endpoint doesn't support `url` or `file` document sources.1112</Note>11131114<CodeGroup>1115  ```bash cURL1116  curl https://api.anthropic.com/v1/messages/count_tokens \1117    -H "x-api-key: $ANTHROPIC_API_KEY" \1118    -H "content-type: application/json" \1119    -H "anthropic-version: 2023-06-01" \1120    -d @- <<EOF1121  {1122    "model": "claude-opus-5",1123    "messages": [{1124      "role": "user",1125      "content": [1126        {1127          "type": "document",1128          "source": {1129            "type": "base64",1130            "media_type": "application/pdf",1131            "data": "$PDF_BASE64"1132          }1133        },1134        {1135          "type": "text",1136          "text": "Please summarize this document."1137        }1138      ]1139    }]1140  }1141  EOF1142  ```11431144  ```bash CLI1145  ant messages count-tokens <<'YAML'1146  model: claude-opus-51147  messages:1148    - role: user1149      content:1150        - type: document1151          source:1152            type: base641153            media_type: application/pdf1154            data: "@./document.pdf"1155        - type: text1156          text: Please summarize this document.1157  YAML1158  ```11591160  ```python Python1161  import base641162  import anthropic11631164  client = anthropic.Anthropic()11651166  with open("/path/to/document.pdf", "rb") as pdf_file:1167      pdf_base64 = base64.standard_b64encode(pdf_file.read()).decode("utf-8")11681169  response = client.messages.count_tokens(1170      model="claude-opus-5",1171      messages=[1172          {1173              "role": "user",1174              "content": [1175                  {1176                      "type": "document",1177                      "source": {1178                          "type": "base64",1179                          "media_type": "application/pdf",1180                          "data": pdf_base64,1181                      },1182                  },1183                  {"type": "text", "text": "Please summarize this document."},1184              ],1185          }1186      ],1187  )11881189  print(response.json())1190  ```11911192  ```typescript TypeScript1193  import { readFile } from "node:fs/promises";11941195  const client = new Anthropic();11961197  const pdfBase64 = await readFile("/path/to/document.pdf", { encoding: "base64" });11981199  const response = await client.messages.countTokens({1200    model: "claude-opus-5",1201    messages: [1202      {1203        role: "user",1204        content: [1205          {1206            type: "document",1207            source: {1208              type: "base64",1209              media_type: "application/pdf",1210              data: pdfBase641211            }1212          },1213          {1214            type: "text",1215            text: "Please summarize this document."1216          }1217        ]1218      }1219    ]1220  });12211222  console.log(response);1223  ```12241225  ```csharp C#1226  using System;1227  using System.IO;1228  using System.Threading.Tasks;1229  using System.Collections.Generic;1230  using Anthropic;1231  using Anthropic.Models.Messages;12321233  AnthropicClient client = new();12341235  byte[] pdfBytes = await File.ReadAllBytesAsync("/path/to/document.pdf");1236  string pdfBase64 = Convert.ToBase64String(pdfBytes);12371238  var parameters = new MessageCountTokensParams1239  {1240      Model = Model.ClaudeOpus5,1241      Messages =1242      [1243          new()1244          {1245              Role = Role.User,1246              Content = new MessageParamContent(new List<ContentBlockParam>1247              {1248                  new ContentBlockParam(new DocumentBlockParam(1249                      new DocumentBlockParamSource(new Base64PdfSource()1250                      {1251                          Data = pdfBase64,1252                      })1253                  )),1254                  new ContentBlockParam(new TextBlockParam("Please summarize this document.")),1255              }),1256          }1257      ]1258  };12591260  var count = await client.Messages.CountTokens(parameters);1261  Console.WriteLine(count);1262  ```12631264  ```go Go1265  client := anthropic.NewClient()12661267  pdfBytes, err := os.ReadFile("/path/to/document.pdf")1268  if err != nil {1269  	log.Fatal(err)1270  }1271  pdfBase64 := base64.StdEncoding.EncodeToString(pdfBytes)12721273  response, err := client.Messages.CountTokens(context.TODO(), anthropic.MessageCountTokensParams{1274  	Model: anthropic.ModelClaudeOpus5,1275  	Messages: []anthropic.MessageParam{1276  		anthropic.NewUserMessage(1277  			anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{1278  				Data: pdfBase64,1279  			}),1280  			anthropic.NewTextBlock("Please summarize this document."),1281  		),1282  	},1283  })1284  if err != nil {1285  	log.Fatal(err)1286  }12871288  fmt.Println(response)1289  ```12901291  ```java Java1292  import com.anthropic.models.messages.Base64PdfSource;1293  // ...1294  import com.anthropic.models.messages.DocumentBlockParam;1295  import com.anthropic.models.messages.MessageCountTokensParams;1296  import com.anthropic.models.messages.MessageTokensCount;1297  // ...1298      AnthropicClient client = AnthropicOkHttpClient.fromEnv();12991300      byte[] fileBytes = Files.readAllBytes(Path.of("/path/to/document.pdf"));1301      String pdfBase64 = Base64.getEncoder().encodeToString(fileBytes);13021303      ContentBlockParam documentBlock = ContentBlockParam.ofDocument(1304        DocumentBlockParam.builder()1305          .source(Base64PdfSource.builder().data(pdfBase64).build())1306          .build()1307      );13081309      ContentBlockParam textBlock = ContentBlockParam.ofText(1310        TextBlockParam.builder().text("Please summarize this document.").build()1311      );13121313      MessageCountTokensParams params = MessageCountTokensParams.builder()1314        .model(Model.CLAUDE_OPUS_5)1315        .addUserMessageOfBlockParams(List.of(documentBlock, textBlock))1316        .build();13171318      MessageTokensCount count = client.messages().countTokens(params);1319      System.out.println(count);1320  ```13211322  ```php PHP1323  $client = new Client();13241325  $pdfBase64 = base64_encode(file_get_contents("/path/to/document.pdf"));13261327  $response = $client->messages->countTokens(1328      messages: [1329          [1330              'role' => 'user',1331              'content' => [1332                  [1333                      'type' => 'document',1334                      'source' => [1335                          'type' => 'base64',1336                          'media_type' => 'application/pdf',1337                          'data' => $pdfBase641338                      ]1339                  ],1340                  [1341                      'type' => 'text',1342                      'text' => 'Please summarize this document.'1343                  ]1344              ]1345          ]1346      ],1347      model: 'claude-opus-5',1348  );13491350  echo json_encode($response);1351  ```13521353  ```ruby Ruby1354  require "base64"13551356  client = Anthropic::Client.new13571358  pdf_base64 = Base64.strict_encode64(File.binread("/path/to/document.pdf"))13591360  response = client.messages.count_tokens(1361    model: "claude-opus-5",1362    messages: [1363      {1364        role: "user",1365        content: [1366          {1367            type: "document",1368            source: {1369              type: "base64",1370              media_type: "application/pdf",1371              data: pdf_base641372            }1373          },1374          {1375            type: "text",1376            text: "Please summarize this document."1377          }1378        ]1379      }1380    ]1381  )13821383  puts response1384  ```1385</CodeGroup>13861387```json Output1388{ "input_tokens": 2188 }1389```13901391***13921393## Token counts on Claude Fable and Claude Mythos models13941395Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, and Claude Mythos 5 share the tokenizer introduced with Claude Opus 4.7. A prompt counts the same on all four, and roughly 30 percent higher than on models before Claude Opus 4.7 (the exact increase depends on the content). The token counting endpoint counts under the tokenizer of the `model` you pass. To measure the difference for your workload, count the same request twice, once with your current model and once with the model you plan to move to, and compare the two `input_tokens` values.13961397<Note>1398  **Billing and migration:** Usage and billing on these models reflect this tokenizer's counts. When migrating from a model before Claude Opus 4.7, don't reuse token counts measured on the older model to estimate costs or context window fit. Count your prompts with the `model` ID you plan to use (for example, `"claude-fable-5-1"`).1399</Note>14001401***14021403## Pricing and rate limits14041405Token counting is **free to use** but subject to requests per minute rate limits based on your [usage tier](https://platform.claude.com/docs/en/api/rate-limits#rate-limits). If you need higher limits, use **Request rate limit increase** on the [Rate limits](https://platform.claude.com/settings/limits) page.14061407| Usage tier | Requests per minute (RPM) |1408| ---------- | ------------------------- |1409| Start      | 5,000                     |1410| Build      | 10,000                    |1411| Scale      | 20,000                    |14121413<Note>1414  Token counting and message creation have separate and independent rate limits. Usage of one does not count against the limits of the other.1415</Note>14161417***14181419## FAQ14201421<AccordionGroup>1422  <Accordion title="Does token counting use prompt caching?">1423    No, token counting provides an estimate without using caching logic. Although you may provide `cache_control` blocks in your token counting request, prompt caching only occurs during actual message creation.1424  </Accordion>1425</AccordionGroup>14261427***14281429## Next steps14301431<CardGroup cols={2}>1432  <Card title="Count message tokens" icon="code" href="https://platform.claude.com/docs/en/api/messages-count-tokens">1433    Read the full API reference for the token counting endpoint.1434  </Card>14351436  <Card title="Context windows" icon="arrows-maximize" href="https://platform.claude.com/docs/en/build-with-claude/context-windows">1437    Use token counts to keep prompts within a model's context window.1438  </Card>14391440  <Card title="Rate limits" icon="gauge" href="https://platform.claude.com/docs/en/api/rate-limits">1441    Check token counts before you send a request to stay within your usage tier.1442  </Card>14431444  <Card title="Prompt caching" icon="database" href="https://platform.claude.com/docs/en/build-with-claude/prompt-caching">1445    Reduce cost and latency on repeated prompts by caching prompt prefixes.1446  </Card>1447</CardGroup>1448
Files main
Menu

Theme