Count tokens in a Message

POST /v1/messages/count_tokens

Copy endpoint

https://api.anthropic.com

Count the number of tokens in a Message.

The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.

Learn more about token counting in our user guide

Parameters

header Header Parameters

Name	Type
`anthropic-version` The version of the Claude API you want to use. Read more about versioning and our version history here.	string

Request Body

application/json required

interface CountMessageTokensParams {
messages:

InputMessage

interface InputMessage {
content: InputContentBlock[] | string;
role: "user" | "assistant";
}

[];
model:

Model

The model that will complete your prompt.\n\nSee models for additional details and options.

;
system?:

RequestTextBlock

interface RequestTextBlock {
cache_control?: CacheControlEphemeral | null;
citations?: (RequestCharLocationCitation | RequestPageLocationCitation | RequestContentBlockLocationCitation | RequestWebSearchResultLocationCitation | RequestSearchResultLocationCitation)[] | null;
text: string;
type: "text";
}

[] | string;
thinking?:

ThinkingConfigParam

Configuration for enabling Claude's extended thinking.

When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.

See extended thinking for details.

type ThinkingConfigParam = ThinkingConfigEnabled | ThinkingConfigDisabled

;
tool_choice?:

ToolChoice

How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.

type ToolChoice = ToolChoiceAuto | ToolChoiceAny | ToolChoiceTool | ToolChoiceNone

;
tools?: (

Tool

interface Tool {
type?: "custom" | null;
description?: string;
name: string;
input_schema: InputSchema;
cache_control?: CacheControlEphemeral | null;
}

BashTool20250124

interface BashTool20250124 {
cache_control?: CacheControlEphemeral | null;
name: "bash";
type: "bash_20250124";
}

TextEditor20250124

interface TextEditor20250124 {
cache_control?: CacheControlEphemeral | null;
name: "str_replace_editor";
type: "text_editor_20250124";
}

TextEditor20250429

interface TextEditor20250429 {
cache_control?: CacheControlEphemeral | null;
name: "str_replace_based_edit_tool";
type: "text_editor_20250429";
}

TextEditor20250728

interface TextEditor20250728 {
cache_control?: CacheControlEphemeral | null;
max_characters?: number | null;
name: "str_replace_based_edit_tool";
type: "text_editor_20250728";
}

WebSearchTool20250305

interface WebSearchTool20250305 {
allowed_domains?: string[] | null;
blocked_domains?: string[] | null;
cache_control?: CacheControlEphemeral | null;
max_uses?: number | null;
name: "web_search";
type: "web_search_20250305";
user_location?: UserLocation | null;
}

)[];
}

Responses

200 application/json

Successful Response

interface CountMessageTokensResponse {
input_tokens: number;
}

Client Errors

4XX application/json

Error response.

See our errors documentation for more details.

interface ErrorResponse {
error:

InvalidRequestError

interface InvalidRequestError {
message: string;
type: "invalid_request_error";
}

AuthenticationError

interface AuthenticationError {
message: string;
type: "authentication_error";
}

BillingError

interface BillingError {
message: string;
type: "billing_error";
}

PermissionError

interface PermissionError {
message: string;
type: "permission_error";
}

NotFoundError

interface NotFoundError {
message: string;
type: "not_found_error";
}

RateLimitError

interface RateLimitError {
message: string;
type: "rate_limit_error";
}

GatewayTimeoutError

interface GatewayTimeoutError {
message: string;
type: "timeout_error";
}

APIError

interface APIError {
message: string;
type: "api_error";
}

OverloadedError

interface OverloadedError {
message: string;
type: "overloaded_error";
}

;
request_id: string | null;
type: "error";
}