Counting tokens

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.

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 / 4 are 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

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.inputTokens.count({
  model: "gpt-5.6",
  input: "Tell me a joke.",
});

console.log(response.input_tokens);

from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-5.6", input="Tell me a joke."
)
print(response.input_tokens)

package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
		Model: openai.String("gpt-5.6"),
		Input: responses.InputTokenCountParamsInputUnion{OfString: openai.String("Tell me a joke.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(count.InputTokens)
}

require "openai"

client = OpenAI::Client.new

count = client.responses.input_tokens.count(
  model: "gpt-5.6",
  input: "Tell me a joke."
)

puts(count.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.6",
    "input": "Tell me a joke."
  }'

openai responses:input-tokens count \
  --model gpt-5.6 \
  --input "Tell me a joke." \
  --raw-output \
  --transform input_tokens

Count tokens in conversations

Multi-turn conversation

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.inputTokens.count({
  model: "gpt-5.6",
  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);

from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-5.6",
    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)

package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	input := []responses.ResponseInputItemUnionParam{
		responses.ResponseInputItemParamOfMessage("What is 2 + 2?", responses.EasyInputMessageRoleUser),
		responses.ResponseInputItemParamOfMessage("2 + 2 equals 4.", responses.EasyInputMessageRoleAssistant),
		responses.ResponseInputItemParamOfMessage("What about 3 + 3?", responses.EasyInputMessageRoleUser),
	}
	count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
		Model: openai.String("gpt-5.6"),
		Input: responses.InputTokenCountParamsInputUnion{OfResponseInputItemArray: input},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(count.InputTokens)
}

require "openai"

client = OpenAI::Client.new
conversation = [
  {role: :user, content: "What is 2 + 2?"},
  {role: :assistant, content: "2 + 2 equals 4."},
  {role: :user, content: "What about 3 + 3?"}
]

count = client.responses.input_tokens.count(
  model: "gpt-5.6",
  input: conversation
)

puts(count.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.6",
    "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.6
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

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.inputTokens.count({
  model: "gpt-5.6",
  instructions: "You are a helpful assistant that explains concepts simply.",
  input: "Explain quantum computing in one sentence.",
});

console.log(response.input_tokens);

from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-5.6",
    instructions="You are a helpful assistant that explains concepts simply.",
    input="Explain quantum computing in one sentence.",
)
print(response.input_tokens)

package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
		Model:        openai.String("gpt-5.6"),
		Instructions: openai.String("You are a helpful assistant that explains concepts simply."),
		Input:        responses.InputTokenCountParamsInputUnion{OfString: openai.String("Explain quantum computing in one sentence.")},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(count.InputTokens)
}

require "openai"

client = OpenAI::Client.new

count = client.responses.input_tokens.count(
  model: "gpt-5.6",
  instructions: "You are a helpful assistant that explains concepts simply.",
  input: "Explain quantum computing in one sentence."
)

puts(count.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.6",
    "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.6
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

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.inputTokens.count({
  model: "gpt-5.6",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_image",
          image_url: "https://example.com/chart.png",
          detail: "auto",
        },
        { type: "input_text", text: "Summarize this chart." },
      ],
    },
  ],
});

console.log(response.input_tokens);

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.6",
    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)

package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	input := []responses.ResponseInputItemUnionParam{
		responses.ResponseInputItemParamOfMessage(
			responses.ResponseInputMessageContentListParam{
				{OfInputImage: &responses.ResponseInputImageParam{ImageURL: openai.String("https://example.com/chart.png"), Detail: responses.ResponseInputImageDetailAuto}},
				{OfInputText: &responses.ResponseInputTextParam{Text: "Summarize this chart."}},
			},
			responses.EasyInputMessageRoleUser,
		),
	}
	count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
		Model: openai.String("gpt-5.6"),
		Input: responses.InputTokenCountParamsInputUnion{OfResponseInputItemArray: input},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(count.InputTokens)
}

require "openai"

client = OpenAI::Client.new

count = client.responses.input_tokens.count(
  model: "gpt-5.6",
  input: [
    {
      role: :user,
      content: [
        {
          type: :input_image,
          image_url: "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",
          detail: :auto
        },
        {type: :input_text, text: "Summarize this chart."}
      ]
    }
  ]
)

puts(count.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.6",
    "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.6
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

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.inputTokens.count({
  model: "gpt-5.6",
  tools: [
    {
      type: "function",
      name: "get_weather",
      description: "Get the current weather in a location",
      strict: true,
      parameters: {
        type: "object",
        properties: { location: { type: "string" } },
        required: ["location"],
        additionalProperties: false,
      },
    },
  ],
  input: "What is the weather in San Francisco?",
});

console.log(response.input_tokens);

from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-5.6",
    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)

package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	client := openai.NewClient()
	parameters := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"location": map[string]any{"type": "string"},
		},
		"required":             []string{"location"},
		"additionalProperties": false,
	}
	tool := responses.ToolParamOfFunction("get_weather", parameters, true)
	tool.OfFunction.Description = openai.String("Get the current weather in a location")
	count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
		Model: openai.String("gpt-5.6"),
		Input: responses.InputTokenCountParamsInputUnion{OfString: openai.String("What is the weather in San Francisco?")},
		Tools: []responses.ToolUnionParam{tool},
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(count.InputTokens)
}

require "openai"

client = OpenAI::Client.new

count = client.responses.input_tokens.count(
  model: "gpt-5.6",
  input: "What is the weather in San Francisco?",
  tools: [
    {
      type: :function,
      name: "get_weather",
      description: "Get the current weather in a location",
      strict: true,
      parameters: {
        type: "object",
        properties: {location: {type: "string"}},
        required: ["location"],
        additionalProperties: false
      }
    }
  ]
)

puts(count.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.6",
    "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.6
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".

guides/token-counting.md +97 −0

75}75}

76```76```

77 77

78```ruby

79require "openai"

81client = OpenAI::Client.new

83count = client.responses.input_tokens.count(

84 model: "gpt-5.6",

85 input: "Tell me a joke."

86)

88puts(count.input_tokens)

89```

78```bash91```bash

79curl https://api.openai.com/v1/responses/input_tokens \92curl https://api.openai.com/v1/responses/input_tokens \

80 -H "Authorization: Bearer $OPENAI_API_KEY" \93 -H "Authorization: Bearer $OPENAI_API_KEY" \

160}173}

161```174```

162 175

176```ruby

177require "openai"

178

179client = OpenAI::Client.new

180conversation = [

181 {role: :user, content: "What is 2 + 2?"},

182 {role: :assistant, content: "2 + 2 equals 4."},

183 {role: :user, content: "What about 3 + 3?"}

184]

185

186count = client.responses.input_tokens.count(

187 model: "gpt-5.6",

188 input: conversation

189)

190

191puts(count.input_tokens)

192```

193

163```bash194```bash

164curl https://api.openai.com/v1/responses/input_tokens \195curl https://api.openai.com/v1/responses/input_tokens \

165 -H "Authorization: Bearer $OPENAI_API_KEY" \196 -H "Authorization: Bearer $OPENAI_API_KEY" \

246}277}

247```278```

248 279

280```ruby

281require "openai"

282

283client = OpenAI::Client.new

284

285count = client.responses.input_tokens.count(

286 model: "gpt-5.6",

287 instructions: "You are a helpful assistant that explains concepts simply.",

288 input: "Explain quantum computing in one sentence."

289)

290

291puts(count.input_tokens)

292```

293

249```bash294```bash

250curl https://api.openai.com/v1/responses/input_tokens \295curl https://api.openai.com/v1/responses/input_tokens \

251 -H "Authorization: Bearer $OPENAI_API_KEY" \296 -H "Authorization: Bearer $OPENAI_API_KEY" \

356}401}

357```402```

358 403

404```ruby

405require "openai"

406

407client = OpenAI::Client.new

408

409count = client.responses.input_tokens.count(

410 model: "gpt-5.6",

411 input: [

412 {

413 role: :user,

414 content: [

415 {

416 type: :input_image,

417 image_url: "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",

418 detail: :auto

419 },

420 {type: :input_text, text: "Summarize this chart."}

421 ]

422 }

423 ]

424)

425

426puts(count.input_tokens)

427```

428

359```bash429```bash

360curl https://api.openai.com/v1/responses/input_tokens \430curl https://api.openai.com/v1/responses/input_tokens \

361 -H "Authorization: Bearer $OPENAI_API_KEY" \431 -H "Authorization: Bearer $OPENAI_API_KEY" \

482}552}

483```553```

484 554

555```ruby

556require "openai"

557

558client = OpenAI::Client.new

559

560count = client.responses.input_tokens.count(

561 model: "gpt-5.6",

562 input: "What is the weather in San Francisco?",

563 tools: [

564 {

565 type: :function,

566 name: "get_weather",

567 description: "Get the current weather in a location",

568 strict: true,

569 parameters: {

570 type: "object",

571 properties: {location: {type: "string"}},

572 required: ["location"],

573 additionalProperties: false

574 }

575 }

576 ]

577)

578

579puts(count.input_tokens)

580```

581

485```bash582```bash

486curl https://api.openai.com/v1/responses/input_tokens \583curl https://api.openai.com/v1/responses/input_tokens \

487 -H "Authorization: Bearer $OPENAI_API_KEY" \584 -H "Authorization: Bearer $OPENAI_API_KEY" \