Count tokens

Estimate how many input tokens a Messages-API request will use, before you send it. Useful for staying under context limits or budgeting cost per request.

Endpoint:

POST /v1/messages/count_tokens

Auth: Bearer token or x-api-key. Requires scope inference.chat. Header: anthropic-version is optional. Send it if your client already does — current SDKs send 2026-10-21, older ones 2023-06-01; we accept any value and never reject a request for it.

Example

curl https://api.melious.ai/v1/messages/count_tokens \
  -H "x-api-key: sk-mel-<YOUR_API_KEY>" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "system": "You are concise.",
    "messages": [{"role": "user", "content": "Name three Hanseatic cities."}]
  }'

Response:

{ "input_tokens": 18 }

Request

Image content blocks contribute a fixed per-image cost (the high-detail rate). Tool schemas count as their serialized JSON.

What's counted: system, text blocks, tool_result content — a string, or the bare strings and text blocks of a list — tool_use blocks (name plus JSON-encoded input), one fixed image price per image block, and each tool's name, description, and schema. Not counted: thinking, document, and search_result blocks, and non-text items nested in a tool_result list. It's an estimate from a general tokenizer, not the provider's exact count; budget with a margin.

Response

{ "input_tokens": 18 }

Always input_tokens, always a non-negative integer. No environment or billing fields — this endpoint is free.

Errors

Same shape as Messages: {"type": "error", "error": {...}, "request_id": "..."}, with the same id in the request-id header.

• 400 — malformed body.
• Permission error — insufficient scope.
• model_not_allowed — 403: the key can't use the named model.

Related

Messages for the full endpoint • Context window errors.