Counting tokens
Token counting lets you determine how many input tokens a request will use before you send it to the model. Use it to:
- Optimize prompts to fit within context limits
- Estimate costs before making API calls
- Route requests based on size (e.g., smaller prompts to faster models)
- Avoid surprises with images and files—no more character-based estimation
The input token count endpoint accepts the same input format as the Responses API. Pass text, messages, images, files, tools, or conversations—the API returns the exact count the model will receive.
The count includes formatting tokens used to represent request structure, such as message roles and boundaries. These tokens might not appear in the text or fields you tokenize locally.
Why use the token counting API?
Local tokenizers like tiktoken work for plain text, but they have limitations:
- Images and files are not supported—estimates like
characters / 4are inaccurate - Tools and schemas add tokens that are hard to count locally
- Model-specific behavior can change tokenization (e.g., reasoning, caching)
The token counting API handles all of these. Use the same payload you would send to responses.create and get an accurate count. Then plug the result into your message validation or cost estimation flow.
Count tokens in basic messages
Simple text input
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5.5",
input="Tell me a joke."
)
print(response.input_tokens)
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5.5",
input: "Tell me a joke.",
});
console.log(response.input_tokens);
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": "Tell me a joke."
}'
openai responses:input-tokens count \
--model gpt-5.5 \
--input "Tell me a joke." \
--raw-output \
--transform input_tokens
Count tokens in conversations
Multi-turn conversation
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5.5",
input=[
{"role": "user", "content": "What is 2 + 2?"},
{"role": "assistant", "content": "2 + 2 equals 4."},
{"role": "user", "content": "What about 3 + 3?"},
],
)
print(response.input_tokens)
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5.5",
input: [
{ role: "user", content: "What is 2 + 2?" },
{ role: "assistant", content: "2 + 2 equals 4." },
{ role: "user", content: "What about 3 + 3?" },
],
});
console.log(response.input_tokens);
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": [
{"role": "user", "content": "What is 2 + 2?"},
{"role": "assistant", "content": "2 + 2 equals 4."},
{"role": "user", "content": "What about 3 + 3?"}
]
}'
openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-5.5
input:
- role: user
content: What is 2 + 2?
- role: assistant
content: 2 + 2 equals 4.
- role: user
content: What about 3 + 3?
YAML
Count tokens with instructions
Input with system instructions
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5.5",
instructions="You are a helpful assistant that explains concepts simply.",
input="Explain quantum computing in one sentence.",
)
print(response.input_tokens)
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5.5",
instructions:
"You are a helpful assistant that explains concepts simply.",
input: "Explain quantum computing in one sentence.",
});
console.log(response.input_tokens);
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"instructions": "You are a helpful assistant that explains concepts simply.",
"input": "Explain quantum computing in one sentence."
}'
openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-5.5
instructions: You are a helpful assistant that explains concepts simply.
input: Explain quantum computing in one sentence.
YAML
Count tokens with images
Images consume tokens based on size and detail level. The token counting API returns the exact count—no guesswork.
Input with an image
from openai import OpenAI
client = OpenAI()
# Use file_id from uploaded file, or image_url for a URL
response = client.responses.input_tokens.count(
model="gpt-5.5",
input=[
{
"role": "user",
"content": [
{"type": "input_image", "image_url": "https://example.com/chart.png"},
{"type": "input_text", "text": "Summarize this chart."},
],
}
],
)
print(response.input_tokens)
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5.5",
input: [
{
role: "user",
content: [
{
type: "input_image",
image_url: "https://example.com/chart.png",
},
{ type: "input_text", text: "Summarize this chart." },
],
},
],
});
console.log(response.input_tokens);
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"input": [{
"role": "user",
"content": [
{"type": "input_image", "image_url": "https://example.com/chart.png"},
{"type": "input_text", "text": "Summarize this chart."}
]
}]
}'
openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-5.5
input:
- role: user
content:
- type: input_image
image_url: https://example.com/chart.png
- type: input_text
text: Summarize this chart.
YAML
You can use file_id (from the Files API) or image_url (a URL or base64 data URL). See images and vision for details.
Count tokens with tools
Tool definitions (function schemas, MCP servers, etc.) add tokens to the context. Count them together with your input:
Input with function tools
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5.5",
tools=[
{
"type": "function",
"name": "get_weather",
"description": "Get the current weather in a location",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
},
}
],
input="What is the weather in San Francisco?",
)
print(response.input_tokens)
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5.5",
tools: [
{
type: "function",
name: "get_weather",
description: "Get the current weather in a location",
parameters: {
type: "object",
properties: { location: { type: "string" } },
required: ["location"],
},
},
],
input: "What is the weather in San Francisco?",
});
console.log(response.input_tokens);
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.5",
"tools": [{
"type": "function",
"name": "get_weather",
"description": "Get the current weather in a location",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"]
}
}],
"input": "What is the weather in San Francisco?"
}'
openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-5.5
tools:
- type: function
name: get_weather
description: Get the current weather in a location
parameters:
type: object
properties:
location:
type: string
required:
- location
input: What is the weather in San Francisco?
YAML
Count tokens with files
File inputs—currently PDFs—are supported. Pass file_id, file_url, or file_data as you would for responses.create. The token count reflects the model’s full processed input.
Understand output token counts
Reported output token usage includes all tokens generated by the model, not only the text visible in a response. The Responses API reports this total as output_tokens, while the Chat Completions API reports it as completion_tokens.
Some models, including GPT-5 models, generate tokens used to format or delimit response channels, tool calls, and other message structure. These formatting tokens don't appear in message content or logprobs, and they aren't necessarily itemized separately in usage. As a result, the reported output or completion token count can be higher than the number of visible tokens or tokens included in logprobs, even when the reported reasoning_tokens value is 0.
The max_output_tokens and max_completion_tokens parameters limit all tokens generated by the model, including non-visible tokens. The number of non-visible tokens varies by model and response shape, so don't assume a fixed difference between reported usage and visible output. Leave headroom in these limits when you need a specific amount of visible output.
API reference
For full parameters and response shape, see the Count input tokens API reference. The endpoint is:
POST /v1/responses/input_tokens
The response includes input_tokens (integer) and object: "response.input_tokens".