Count tokens in a Message changedapi/beta/messages/count_tokens
Recorded here
Lines+16added
Lines−16removed
From line
11
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits25to this page, all time
The whole hunk
from line 11, old and new numbered
/
from line 11
1111
1212The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.
1313
14Learn more about token counting in our [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting)
14Learn more about token counting in our [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting?sdk_languages=http)
1515
1616## Headers
1717
from line 19
1919
2020 The version of the Claude API you want to use.
2121
22 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
22 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
2323
2424- `"anthropic-beta": optional array of AnthropicBeta`
2525
from line 147
147147
148148 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
149149
150 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
150 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors?sdk_languages=http#prefill-not-supported).
151151
152152 Example with a single `user` message:
153153
from line 184
184184 {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
185185 ```
186186
187 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
187 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=http).
188188
189 Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
189 Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=http#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
190190
191191 There is a limit of 100,000 messages in a single request.
192192
from line 219
219219 - `5m`: 5 minutes
220220 - `1h`: 1 hour
221221
222 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
222 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
223223
224224 - `"5m"`
225225
from line 3689
36893689
36903690 - `format: optional BetaJSONOutputFormat or null`
36913691
3692 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3692 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=http)
36933693
36943694 - `type: "json_schema"`
36953695
from line 3729
37293729
37303730 System prompt.
37313731
3732 A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).
3732 A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=http#give-claude-a-role).
37333733
37343734 - `string`
37353735
from line 3753
37533753
37543754 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
37553755
3756 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
3756 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#configuring-thinking) for each model's behavior.
37573757
37583758 - `BetaThinkingConfigEnabled object`
37593759
from line 3765
37653765
37663766 Must be ≥1024 and less than `max_tokens`.
37673767
3768 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
3768 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
37693769
37703770 minimum: 1024
37713771
from line 3783
37833783
37843784 - `display: optional "summarized" or "omitted" or "updates" or null`
37853785
3786 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
3786 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#controlling-thinking-display).
37873787
37883788 - `"summarized"`
37893789
from line 3809
38093809
38103810 - `display: optional "summarized" or "omitted" or "updates" or null`
38113811
3812 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
3812 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#controlling-thinking-display).
38133813
38143814 - `"summarized"`
38153815
from line 3873
38733873
38743874 If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.
38753875
3876 There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)).
3876 There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools?sdk_languages=http), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool?sdk_languages=http)).
38773877
38783878 Each tool definition includes:
38793879
from line 3929
39293929
39303930 Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.
39313931
3932 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
3932 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=http) for more details.
39333933
39343934 - `BetaTool object`
39353935
from line 4016
40164016
40174017 **Deprecated**
40184018
4019 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
4019 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=http)
40204020
40214021 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
40224022
No line in this hunk matches that.