Anthropic Token Counting API

openapi: 3.1.0
info:
  title: Anthropic Token Counting API
  description: >
    Count the number of tokens in a Message, including tools, images, and
    documents, without creating it. The Token Count API accepts the same
    structured list of inputs for creating a message, including support for
    system prompts, tools, images, and PDFs. Token counting is free to use
    but subject to requests-per-minute rate limits.
  version: 2023-06-01
  contact:
    name: Anthropic Support
    url: https://support.claude.com
  license:
    name: Anthropic Terms of Service
    url: https://www.anthropic.com/terms
servers:
  - url: https://api.anthropic.com
    description: Production Server
security:
  - ApiKeyAuth: []
tags:
  - name: Token Counting
    description: Count tokens before sending a Message request
paths:
  /v1/messages/count_tokens:
    post:
      summary: Anthropic Count Message Tokens
      description: >
        Count tokens for a prospective Message request, including any tools,
        images, and documents. Returns the input token total without creating
        the message or charging output tokens.
      operationId: countMessageTokens
      tags:
        - Token Counting
      parameters:
        - $ref: '#/components/parameters/AnthropicVersion'
        - $ref: '#/components/parameters/AnthropicBeta'
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/ContentType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CountTokensRequest'
            examples:
              SimpleCount:
                $ref: '#/components/examples/SimpleCountTokensExample'
      responses:
        '200':
          description: Token count returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountTokensResponse'
              examples:
                Default:
                  $ref: '#/components/examples/CountTokensResponseExample'
        '4XX':
          $ref: '#/components/responses/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  parameters:
    AnthropicVersion:
      name: anthropic-version
      in: header
      required: true
      description: API version date.
      schema:
        type: string
        default: "2023-06-01"
    AnthropicBeta:
      name: anthropic-beta
      in: header
      required: false
      description: Comma-separated beta feature headers.
      schema:
        type: string
    ApiKey:
      name: x-api-key
      in: header
      required: true
      description: Anthropic API key.
      schema:
        type: string
    ContentType:
      name: content-type
      in: header
      required: true
      description: Must be application/json.
      schema:
        type: string
        default: application/json
  schemas:
    CountTokensRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: Claude model ID (for example, claude-opus-4-7).
          example: claude-opus-4-7
        messages:
          type: array
          description: Ordered conversation messages.
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - user
                  - assistant
              content:
                oneOf:
                  - type: string
                  - type: array
                    items:
                      type: object
        system:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
          description: Optional system prompt(s).
        tools:
          type: array
          description: Tool definitions to include in the count.
          items:
            type: object
    CountTokensResponse:
      type: object
      properties:
        input_tokens:
          type: integer
          description: Total input tokens for the prospective request.
          example: 2095
    Error:
      type: object
      properties:
        type:
          type: string
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
  responses:
    ErrorResponse:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  examples:
    SimpleCountTokensExample:
      summary: Simple token count
      value:
        model: claude-opus-4-7
        messages:
          - role: user
            content: How many tokens is this prompt?
    CountTokensResponseExample:
      summary: Token count response
      value:
        input_tokens: 9