Count tokens

Counts the input tokens of a Messages request without generating a response. The gateway translates the request like a Messages request and asks the tokenizer of the model server. No inference runs, so the request is not billed.

POST/messages/count_tokens

URL

https://api.bricksum.com/v1/messages/count_tokens

Request

bash

curl https://api.bricksum.com/v1/messages/count_tokens \
  -H "x-api-key: $KILN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-32b",
    "system": "Answer briefly.",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

python

import os
from anthropic import Anthropic

# base_url is the API origin without /v1: the SDK appends /v1/messages/count_tokens.
client = Anthropic(
    base_url="https://api.bricksum.com",
    api_key=os.environ["KILN_API_KEY"],
)

count = client.messages.count_tokens(
    model="qwen3-32b",
    system="Answer briefly.",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(count.input_tokens)

typescript

import Anthropic from "@anthropic-ai/sdk";

// baseURL is the API origin without /v1: the SDK appends /v1/messages/count_tokens.
const client = new Anthropic({
  baseURL: "https://api.bricksum.com",
  apiKey: process.env.KILN_API_KEY,
});

const count = await client.messages.countTokens({
  model: "qwen3-32b",
  system: "Answer briefly.",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(count.input_tokens);

Response

200 OK

{
  "input_tokens": 21
}

404 Not Found

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "token counting is not available for this model"
  }
}

The token counts and cost in these examples are illustrative figures measured on gpt-oss-120b, not qwen3-32b's.

Authentication

Authentication is the same on every endpoint the gateway fronts, and is documented on the API Reference page.

Request body

Support status

supported: The gateway handles it, or a published measurement shows it works.
passed through: Forwarded to the model server; not verified by Kiln.
ignored: Accepted with 200, but not applied. The rest of the response is normal.
not supported: Rejected with an error, or not working on the models named in the description.

Common parameters

These are documented once on the API Reference page. Listed here with what this endpoint does differently.

modelstringsupported
Optional here. When the field is empty or missing, the gateway uses its configured default model. The 404 is not_found_error, and the same status also answers a tokenizer that cannot count.
Full definition
messagesarrayrequiredsupported
In the shape the Messages endpoint takes, and translated with the same rules, so dropped blocks such as thinking and document are not counted. An empty or missing array is rejected with 400 (invalid_request_error).
Full definition
toolsarrayignored
Accepted, but not sent to the tokenizer. The count does not include tool definitions.
Full definition
tool_choiceobjectignored
Accepted, but not sent to the tokenizer. The same applies to thinking, output_config, max_tokens and the sampling parameters.
Full definition

Only on this endpoint

systemstring | arraysupported
System prompt: a string, or an array of text blocks. It is counted as the leading system messages.

Only model and the translated messages reach the tokenizer. Every other field is dropped and does not cause an error.

Response body

Field	Type	Description
input_tokens	integer	Number of tokens of the translated messages, as the tokenizer of the model server counts them with the chat template applied. It is the only field of the response.

Errors

After authentication, errors use the Anthropic envelope: {"type": "error", "error": {"type", "message"}}. Branch on the HTTP status and error.type, not on the message text. Rows with an empty error.type cell come from the gateway before the request reaches this endpoint, and use the body shown under the table.

Every status code is listed on the Errors page.

Status · error.type	Cause	What to do
400invalid_request_error	The body is not valid JSON, messages is empty or missing, or a message content is neither a string nor an array of blocks.	Fix the payload. Do not retry as sent.
404not_found_error	The model ID is not in the catalog.	Check the ID against GET /models.
404not_found_error	Token counting is not available for this model: no model backend could be selected, the tokenizer was unreachable or rejected the request, or its reply held no count. The endpoint answers these failures with 404 instead of 5xx.	Estimate the count in your client. Claude Code does this on its own.
405invalid_request_error	The method is not POST.	Send the request with POST.

401, 402, 403 and 429 come from the gateway before the request reaches this endpoint. They are listed once on the API Reference page.

Authentication, credit, budget and rate-limit (requests/min, tokens/min) errors are returned by the gateway before the Anthropic translation. Their body is not the Anthropic envelope:

json

{
  "error": {
    "message": "invalid API key",
    "type": "authorization"
  }
}

Limits

Billing: not billed. The gateway publishes no usage event for this endpoint, and the response has no X-Neocloud-Generation-Id header.
Optional for Claude Code: when this endpoint answers 404, Claude Code uses its own estimate and /context shows approximate numbers.

Context length, request body size, timeouts and the per-organization rate limits apply here as well; they are listed once on the API Reference page.

Headers and retry guidance for 429 are on the Rate limits page.