Implementation:Anthropics Anthropic sdk python Beta MessageCountTokensParams

Knowledge Sources	Anthropic SDK Python
Domains	API Types, Beta, Token Counting
Last Updated	2026-02-15 12:00 GMT

Overview

MessageCountTokensParams (beta) is a TypedDict that defines the request parameters for the beta token counting endpoint. It allows callers to estimate the number of tokens a message request would consume before actually sending it, with support for the full range of beta tools and configuration options.

Description

The MessageCountTokensParams class in the anthropic.types.beta module is a typed dictionary for constructing requests to the beta count_tokens endpoint. It requires messages (an iterable of BetaMessageParam) and model (a ModelParam).

The class supports the complete set of beta features:

• System prompts -- via system, accepting either a string or an iterable of BetaTextBlockParam.
• Extended thinking -- via thinking (BetaThinkingConfigParam).
• Tool choice -- via tool_choice (BetaToolChoiceParam).
• Tools -- via tools, accepting a broad union of beta tool types including client tools, bash, computer use, text editor, code execution, web search, web fetch, memory, tool search, and MCP toolsets.
• Output configuration -- via output_config and the deprecated output_format.
• Context management -- via context_management (BetaContextManagementConfigParam).
• MCP servers -- via mcp_servers.
• Speed mode -- via speed (Literal["standard", "fast"]).
• Beta headers -- via betas (aliased to the anthropic-beta HTTP header).

The file also defines a Tool type alias, which is a union of all supported beta tool parameter types.

Usage

Use this parameter type when calling client.beta.messages.count_tokens() to estimate token consumption before sending a full request. This is valuable for:

• Validating that a request fits within model context limits.
• Estimating costs before committing to a request.
• Debugging token usage in complex tool-heavy or multi-turn conversations.

Code Reference

Source Location

• Repository: Anthropic SDK Python
• File: src/anthropic/types/beta/message_count_tokens_params.py

Signature

class MessageCountTokensParams(TypedDict, total=False):
    messages: Required[Iterable[BetaMessageParam]]
    model: Required[ModelParam]
    context_management: Optional[BetaContextManagementConfigParam]
    mcp_servers: Iterable[BetaRequestMCPServerURLDefinitionParam]
    output_config: BetaOutputConfigParam
    output_format: Optional[BetaJSONOutputFormatParam]
    speed: Optional[Literal["standard", "fast"]]
    system: Union[str, Iterable[BetaTextBlockParam]]
    thinking: BetaThinkingConfigParam
    tool_choice: BetaToolChoiceParam
    tools: Iterable[Tool]
    betas: Annotated[List[AnthropicBetaParam], PropertyInfo(alias="anthropic-beta")]


Tool: TypeAlias = Union[
    BetaToolParam,
    BetaToolBash20241022Param,
    BetaToolBash20250124Param,
    BetaCodeExecutionTool20250522Param,
    BetaCodeExecutionTool20250825Param,
    BetaToolComputerUse20241022Param,
    BetaMemoryTool20250818Param,
    BetaToolComputerUse20250124Param,
    BetaToolTextEditor20241022Param,
    BetaToolComputerUse20251124Param,
    BetaToolTextEditor20250124Param,
    BetaToolTextEditor20250429Param,
    BetaToolTextEditor20250728Param,
    BetaWebSearchTool20250305Param,
    BetaWebFetchTool20250910Param,
    BetaToolSearchToolBm25_20251119Param,
    BetaToolSearchToolRegex20251119Param,
    BetaMCPToolsetParam,
]

Import

from anthropic.types.beta import MessageCountTokensParams

I/O Contract

Fields

Field	Type	Required	Description
messages	Iterable[BetaMessageParam]	Yes	Input messages in alternating user/assistant turns.
model	ModelParam	Yes	The model to use for token counting.
context_management	Optional[BetaContextManagementConfigParam]	No	Context management configuration for multi-request scenarios.
mcp_servers	Iterable[BetaRequestMCPServerURLDefinitionParam]	No	MCP servers to be utilized in the request.
output_config	BetaOutputConfigParam	No	Configuration for model output format.
output_format	Optional[BetaJSONOutputFormatParam]	No	Deprecated. Use output_config.format instead.
speed	Optional[Literal["standard", "fast"]]	No	Inference speed mode.
system	Union[str, Iterable[BetaTextBlockParam]]	No	System prompt providing context and instructions.
thinking	BetaThinkingConfigParam	No	Extended thinking configuration.
tool_choice	BetaToolChoiceParam	No	How the model should select from available tools.
tools	Iterable[Tool]	No	Definitions of tools the model may use (union of 18 beta tool types).
betas	List[AnthropicBetaParam]	No	Beta version(s) to use (sent as anthropic-beta header).

Usage Examples

import anthropic

client = anthropic.Anthropic()

# Count tokens for a beta request with tools
token_count = client.beta.messages.count_tokens(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "Search the web for the latest Python release."}
    ],
    tools=[
        {
            "name": "web_search",
            "type": "web_search_20250305",
        }
    ],
    system="You are a helpful research assistant.",
    betas=["web-search-2025-03-05"],
)

print(f"Input tokens: {token_count.input_tokens}")

Related Pages

• MessageCountTokensParams -- Stable (non-beta) version of the token counting parameters.
• BetaUsage -- Beta usage model returned from API responses, showing actual token consumption.
• BetaWebSearchTool_20250305 -- One of the beta tool types accepted in the tools parameter.
• BetaWebFetchTool_20250910 -- Another beta tool type accepted in the tools parameter.