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.

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

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.

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 +334 −0

21 21

22## Count tokens in basic messages22## Count tokens in basic messages

23 23

24Simple text input

26```python

27from openai import OpenAI

29client = OpenAI()

31response = client.responses.input_tokens.count(

32 model="gpt-5.5",

33 input="Tell me a joke."

34)

35print(response.input_tokens)

36```

38```javascript

39import OpenAI from "openai";

41const client = new OpenAI();

43const response = await client.responses.input_tokens.count({

44 model: "gpt-5.5",

45 input: "Tell me a joke.",

46});

48console.log(response.input_tokens);

49```

51```bash

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

53 -H "Authorization: Bearer $OPENAI_API_KEY" \

54 -H "Content-Type: application/json" \

55 -d '{

56 "model": "gpt-5.5",

57 "input": "Tell me a joke."

58 }'

59```

61```cli

62openai responses:input-tokens count \

63 --model gpt-5.5 \

64 --input "Tell me a joke." \

65 --raw-output \

66 --transform input_tokens

67```

24## Count tokens in conversations70## Count tokens in conversations

25 71

72Multi-turn conversation

74```python

75from openai import OpenAI

77client = OpenAI()

79response = client.responses.input_tokens.count(

80 model="gpt-5.5",

81 input=[

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

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

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

85 ],

86)

87print(response.input_tokens)

88```

90```javascript

91import OpenAI from "openai";

93const client = new OpenAI();

95const response = await client.responses.input_tokens.count({

96 model: "gpt-5.5",

97 input: [

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

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

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

101 ],

102});

103

104console.log(response.input_tokens);

105```

106

107```bash

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

109 -H "Authorization: Bearer $OPENAI_API_KEY" \

110 -H "Content-Type: application/json" \

111 -d '{

112 "model": "gpt-5.5",

113 "input": [

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

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

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

117 ]

118 }'

119```

120

121```cli

122openai responses:input-tokens count \

123 --raw-output \

124 --transform input_tokens <<'YAML'

125model: gpt-5.5

126input:

127 - role: user

128 content: What is 2 + 2?

129 - role: assistant

130 content: 2 + 2 equals 4.

131 - role: user

132 content: What about 3 + 3?

133YAML

134```

135

136

26## Count tokens with instructions137## Count tokens with instructions

27 138

139Input with system instructions

140

141```python

142from openai import OpenAI

143

144client = OpenAI()

145

146response = client.responses.input_tokens.count(

147 model="gpt-5.5",

148 instructions="You are a helpful assistant that explains concepts simply.",

149 input="Explain quantum computing in one sentence.",

150)

151print(response.input_tokens)

152```

153

154```javascript

155import OpenAI from "openai";

156

157const client = new OpenAI();

158

159const response = await client.responses.input_tokens.count({

160 model: "gpt-5.5",

161 instructions:

162 "You are a helpful assistant that explains concepts simply.",

163 input: "Explain quantum computing in one sentence.",

164});

165

166console.log(response.input_tokens);

167```

168

169```bash

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

171 -H "Authorization: Bearer $OPENAI_API_KEY" \

172 -H "Content-Type: application/json" \

173 -d '{

174 "model": "gpt-5.5",

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

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

177 }'

178```

179

180```cli

181openai responses:input-tokens count \

182 --raw-output \

183 --transform input_tokens <<'YAML'

184model: gpt-5.5

185instructions: You are a helpful assistant that explains concepts simply.

186input: Explain quantum computing in one sentence.

187YAML

188```

189

190

28## Count tokens with images191## Count tokens with images

29 192

30Images consume tokens based on size and detail level. The token counting API returns the exact count—no guesswork.193Images consume tokens based on size and detail level. The token counting API returns the exact count—no guesswork.

31 194

195Input with an image

196

197```python

198from openai import OpenAI

199

200client = OpenAI()

201

202# Use file_id from uploaded file, or image_url for a URL

203response = client.responses.input_tokens.count(

204 model="gpt-5.5",

205 input=[

206 {

207 "role": "user",

208 "content": [

209 {"type": "input_image", "image_url": "https://example.com/chart.png"},

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

211 ],

212 }

213 ],

214)

215print(response.input_tokens)

216```

217

218```javascript

219import OpenAI from "openai";

220

221const client = new OpenAI();

222

223const response = await client.responses.input_tokens.count({

224 model: "gpt-5.5",

225 input: [

226 {

227 role: "user",

228 content: [

229 {

230 type: "input_image",

231 image_url: "https://example.com/chart.png",

232 },

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

234 ],

235 },

236 ],

237});

238

239console.log(response.input_tokens);

240```

241

242```bash

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

244 -H "Authorization: Bearer $OPENAI_API_KEY" \

245 -H "Content-Type: application/json" \

246 -d '{

247 "model": "gpt-5.5",

248 "input": [{

249 "role": "user",

250 "content": [

251 {"type": "input_image", "image_url": "https://example.com/chart.png"},

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

253 ]

254 }]

255 }'

256```

257

258```cli

259openai responses:input-tokens count \

260 --raw-output \

261 --transform input_tokens <<'YAML'

262model: gpt-5.5

263input:

264 - role: user

265 content:

266 - type: input_image

267 image_url: https://example.com/chart.png

268 - type: input_text

269 text: Summarize this chart.

270YAML

271```

272

273

32You can use `file_id` (from the [Files API](https://developers.openai.com/api/docs/api-reference/files)) or `image_url` (a URL or base64 data URL). See [images and vision](https://developers.openai.com/api/docs/guides/images-vision) for details.274You can use `file_id` (from the [Files API](https://developers.openai.com/api/docs/api-reference/files)) or `image_url` (a URL or base64 data URL). See [images and vision](https://developers.openai.com/api/docs/guides/images-vision) for details.

33 275

34## Count tokens with tools276## Count tokens with tools

35 277

36Tool definitions (function schemas, MCP servers, etc.) add tokens to the context. Count them together with your input:278Tool definitions (function schemas, MCP servers, etc.) add tokens to the context. Count them together with your input:

37 279

280Input with function tools

281

282```python

283from openai import OpenAI

284

285client = OpenAI()

286

287response = client.responses.input_tokens.count(

288 model="gpt-5.5",

289 tools=[

290 {

291 "type": "function",

292 "name": "get_weather",

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

294 "parameters": {

295 "type": "object",

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

297 "required": ["location"],

298 },

299 }

300 ],

301 input="What is the weather in San Francisco?",

302)

303print(response.input_tokens)

304```

305

306```javascript

307import OpenAI from "openai";

308

309const client = new OpenAI();

310

311const response = await client.responses.input_tokens.count({

312 model: "gpt-5.5",

313 tools: [

314 {

315 type: "function",

316 name: "get_weather",

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

318 parameters: {

319 type: "object",

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

321 required: ["location"],

322 },

323 },

324 ],

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

326});

327

328console.log(response.input_tokens);

329```

330

331```bash

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

333 -H "Authorization: Bearer $OPENAI_API_KEY" \

334 -H "Content-Type: application/json" \

335 -d '{

336 "model": "gpt-5.5",

337 "tools": [{

338 "type": "function",

339 "name": "get_weather",

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

341 "parameters": {

342 "type": "object",

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

344 "required": ["location"]

345 }

346 }],

347 "input": "What is the weather in San Francisco?"

348 }'

349```

350

351```cli

352openai responses:input-tokens count \

353 --raw-output \

354 --transform input_tokens <<'YAML'

355model: gpt-5.5

356tools:

357 - type: function

358 name: get_weather

359 description: Get the current weather in a location

360 parameters:

361 type: object

362 properties:

363 location:

364 type: string

365 required:

366 - location

367input: What is the weather in San Francisco?

368YAML

369```

370

371

38## Count tokens with files372## Count tokens with files

39 373

40[File inputs](https://developers.openai.com/api/docs/guides/pdf-files)—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.374[File inputs](https://developers.openai.com/api/docs/guides/pdf-files)—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.