---
title: "Count tokens in a message."
method: POST
path: "/v1/messages/count_tokens"
tags: ["Messages"]
---

# Count tokens in a message.

`POST /v1/messages/count_tokens`

Count the number of tokens in a message request.

## Request body

- AnthropicCountTokensRequest — Request body for POST /v1/messages/count_tokens.
  - `model` string, required — The model to use for token counting.
  - `messages` AnthropicMessage[], required — The messages to count tokens for.
    - `role` 'user' | 'assistant' | 'system', required
    - `content` union, required — Message content: a string for simple text, or a list of content blocks.
      - string
      - union[]
        - union
          - AnthropicTextBlock — A text content block.
            - `type` 'text'
            - `text` string, required
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
          - AnthropicImageBlock — An image content block.
            - `type` 'image'
            - `source` union, required
              - …
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
          - AnthropicToolUseBlock — A tool use content block in an assistant message.
            - `type` 'tool_use'
            - `id` string, required — Unique ID for this tool invocation.
            - `name` string, required — Name of the tool being called.
            - `input` object, required — Tool input arguments.
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
          - AnthropicToolResultBlockInput — A tool result content block in a user message.
            - `type` 'tool_result'
            - `tool_use_id` string, required — The ID of the tool_use block this result corresponds to.
            - `content` union — The result content.
              - …
            - `is_error` boolean, nullable — Whether the tool call resulted in an error.
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
          - AnthropicThinkingBlock — A thinking content block (extended thinking).
            - `type` 'thinking'
            - `thinking` string, required — The model's thinking text.
            - `signature` string, nullable — Signature for the thinking block.
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
          - AnthropicRedactedThinkingBlock — A redacted thinking content block. Must be echoed back as-is in multi-turn.
            - `type` 'redacted_thinking'
            - `data` string, required — Opaque redacted thinking data.
  - `system` union — System prompt.
    - string
    - AnthropicTextBlock[]
      - `type` 'text'
      - `text` string, required
      - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
        - `type` 'ephemeral'
  - `tools` union[], nullable — Tools to include in token count.
    - union
      - AnthropicCustomToolDef — Definition of a custom (function-calling) tool.
        - `type` 'custom'
        - `name` string, required
        - `description` string, nullable
        - `input_schema` object, required — JSON Schema for the tool's input.
        - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
          - `type` 'ephemeral'
      - AnthropicWebSearchTool — Built-in web search tool (web_search_20250305).
        - `type` 'web_search_20250305'
        - `name` 'web_search'
        - `max_uses` integer, nullable
        - `allowed_domains` string[], nullable
        - `blocked_domains` string[], nullable
        - `user_location` WebSearchUserLocation
          - `type` 'approximate'
          - `city` string, nullable
          - `country` string, nullable
          - `region` string, nullable
          - `timezone` string, nullable
        - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
          - `type` 'ephemeral'
      - AnthropicBashTool — Built-in bash tool (bash_20250124).
        - `type` 'bash_20250124'
        - `name` 'bash'
        - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
          - `type` 'ephemeral'
      - AnthropicTextEditorTool — Built-in text editor tool (all versions).
        - `type` 'text_editor_20250124' | 'text_editor_20250429' | 'text_editor_20250728', required
        - `name` string, required
        - `max_characters` integer, nullable
        - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
          - `type` 'ephemeral'

## Response `200`

Token count for the request.

- AnthropicCountTokensResponse — Response from POST /v1/messages/count_tokens.
  - `input_tokens` integer, required

## Other responses

- `400` — The request was invalid or malformed
- `429` — The client has sent too many requests in a given amount of time
- `500` — The server encountered an unexpected error
- `default` — An error occurred

---

[API](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis.md) · [All operations](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ogx-ai/ogx-specification-stable-experimental-apis/revisions/f3f783962256/schema)