Repository Public
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