--- title: "Get input token counts" method: POST path: "/responses/input_tokens" tags: ["Responses"] --- # Get input token counts `POST /responses/input_tokens` ## Request - Base URL: `https://api.openai.com/v1` - URL: `https://api.openai.com/v1/responses/input_tokens` - Auth: HTTP bearer Returns input token counts of the request. Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. ## Request body - TokenCountsBody - `model` string, nullable: Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. Refer to the [model guide](https://developers.openai.com/api/docs/models) to browse and compare available models. - `input` union - string: A text input to the model, equivalent to a text input with the `user` role. - InputItem[]: A list of one or many input items to the model, containing different content types. - union - EasyInputMessage: A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role. Messages with the `assistant` role are presumed to have been generated by the model in previous interactions. - `role` 'user' | 'assistant' | 'system' | 'developer', required: The role of the message input. One of `user`, `assistant`, `system`, or `developer`. - `content` union, required: Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses. - string: A text input to the model. - InputContent[]: A list of one or many input items to the model, containing different content types. - … - `phase` 'commentary' | 'final_answer': Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `type` 'message': The type of the message input. Always `message`. - union: Content item used to generate a response. - object: A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role. - `type` 'message': The type of the message input. Always set to `message`. - `role` 'user' | 'system' | 'developer', required: The role of the message input. One of `user`, `system`, or `developer`. - `status` 'in_progress' | 'completed' | 'incomplete': The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `content` InputContent[], required: A list of one or many input items to the model, containing different content types. - … - object: An output message from the model. - `id` string, required: The unique ID of the output message. - `type` 'message', required: The type of the output message. Always `message`. - `role` 'assistant', required: The role of the output message. Always `assistant`. - `content` OutputMessageContent[], required: The content of the output message. - … - `phase` 'commentary' | 'final_answer': Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - `status` 'in_progress' | 'completed' | 'incomplete', required: The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - object: The results of a file search tool call. See the [file search guide](https://developers.openai.com/api/docs/guides/tools-file-search) for more information. - `id` string, required: The unique ID of the file search tool call. - `type` 'file_search_call', required: The type of the file search tool call. Always `file_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required: The status of the file search tool call. One of `in_progress`, `searching`, `incomplete` or `failed`, - `queries` string[], required: The queries used to search for files. - `results` object[], nullable: The results of the file search tool call. - … - object: A tool call to a computer use tool. See the [computer use guide](https://developers.openai.com/api/docs/guides/tools-computer-use) for more information. - `type` 'computer_call', required: The type of the computer call. Always `computer_call`. - `id` string, required: The unique ID of the computer call. - `call_id` string, required: An identifier used when responding to the tool call with output. - `action` union - … - `actions` ComputerAction[]: Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. - … - `pending_safety_checks` ComputerCallSafetyCheckParam[], required: The pending safety checks for the computer call. - … - `status` 'in_progress' | 'completed' | 'incomplete', required: The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object: The output of a computer tool call. - `id` string, nullable: The ID of the computer tool call output. - `call_id` string, required: The ID of the computer tool call that produced the output. - `type` 'computer_call_output', required: The type of the computer tool call output. Always `computer_call_output`. - `output` ComputerScreenshotImage, required: A computer screenshot image used with the computer use tool. - … - `acknowledged_safety_checks` ComputerCallSafetyCheckParam[], nullable: The safety checks reported by the API that have been acknowledged by the developer. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object: The results of a web search tool call. See the [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) for more information. - `id` string, required: The unique ID of the web search tool call. - `type` 'web_search_call', required: The type of the web search tool call. Always `web_search_call`. - `status` 'in_progress' | 'searching' | 'completed' | 'failed' | 'incomplete', required - `action` union: An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page). - … - object: A tool call to run a function. See the [function calling guide](https://developers.openai.com/api/docs/guides/function-calling) for more information. - `id` string: The unique ID of the function tool call. - `type` 'function_call', required: The type of the function tool call. Always `function_call`. - `call_id` string, required: The unique ID of the function tool call generated by the model. - `caller` union: The execution context that produced this tool call. - … - `namespace` string: The namespace of the function to run. - `name` string, required: The name of the function to run. - `arguments` string, required: A JSON string of the arguments to pass to the function. - `status` 'in_progress' | 'completed' | 'incomplete': The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `async` boolean: Whether the function tool call runs asynchronously. - object: The output of a function tool call. - `id` string, nullable: The unique ID of the function tool call output. Populated when this item is returned via API. - `call_id` string, nullable: The unique ID of the function tool call generated by the model. - `type` 'function_call_output', required: The type of the function tool call output. Always `function_call_output`. - `output` union, required: Text, image, or file output of the function tool call. - … - `name` string, nullable: The name of the tool that produced the output. - `namespace` string, nullable: The namespace of the tool that produced the output. - `caller` union: The execution context that produced this tool call. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable: The unique ID of this tool search call. - `call_id` string, nullable: The unique ID of the tool search call generated by the model. - `type` 'tool_search_call', required: The item type. Always `tool_search_call`. - `execution` 'server' | 'client' - `arguments` EmptyModelParam, required - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable: The unique ID of this tool search output. - `call_id` string, nullable: The unique ID of the tool search call generated by the model. - `type` 'tool_search_output', required: The item type. Always `tool_search_output`. - `execution` 'server' | 'client' - `tools` ToolSearchOutputTool[], required: The loaded tool definitions returned by the tool search output. - … - `status` 'in_progress' | 'completed' | 'incomplete' - object - `id` string, nullable: The unique ID of this additional tools item. - `type` 'additional_tools', required: The item type. Always `additional_tools`. - `role` 'developer', required: The role that provided the additional tools. Only `developer` is supported. - `tools` Tool[], required: A list of additional tools made available at this item. - … - object: An update to the conversation's response configuration. The configuration remains in effect for subsequent responses until it is replaced by another configuration update. - `id` string, nullable: The unique ID of the configuration update item. - `type` 'configuration_update', required: The item type. Always `configuration_update`. - `reasoning` object: Updates to reasoning configuration. Only effort is supported. - … - object: A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://developers.openai.com/api/docs/guides/conversation-state). - `type` 'reasoning', required: The type of the object. Always `reasoning`. - `id` string, required: The unique identifier of the reasoning content. - `encrypted_content` string, nullable: The encrypted content of the reasoning item. This is populated by default for reasoning items returned by `POST /v1/responses` and WebSocket `response.create` requests. When streaming, use the completed reasoning item and its `encrypted_content` from the `response.output_item.done` event in subsequent requests. The `encrypted_content` in `response.output_item.added` may be incomplete. This is especially important when `store` is `false` or when using Zero Data Retention. - `summary` SummaryTextContent[], required: Reasoning summary content. - … - `content` ReasoningTextContent[]: Reasoning text content. - … - `status` 'in_progress' | 'completed' | 'incomplete': The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - object: A compaction item generated by the [`v1/responses/compact` API](https://developers.openai.com/api/reference/resources/responses/methods/compact). - `id` string, nullable: The ID of the compaction item. - `type` 'compaction', required: The type of the item. Always `compaction`. - `encrypted_content` string, required: The encrypted content of the compaction summary. - object: An image generation request made by the model. - `type` 'image_generation_call', required: The type of the image generation call. Always `image_generation_call`. - `id` string, required: The unique ID of the image generation call. - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required: The status of the image generation call. - `result` string, nullable, required: The generated image encoded in base64. - `error` ImageGenToolCallError - … - `size` union - … - `quality` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto', nullable: The quality of the image generated by the image generation tool call. One of `low`, `medium`, `high`, `xhigh`, `max`, or `auto`. - `action` 'generate' | 'edit' | 'auto', nullable - `background` 'transparent' | 'opaque' | 'auto', nullable - `output_format` 'png' | 'webp' | 'jpeg', nullable - `revised_prompt` string, nullable: The prompt that was used after any model prompt rewriting. - object: A tool call to run code. - `type` 'code_interpreter_call', required: The type of the code interpreter tool call. Always `code_interpreter_call`. - `id` string, required: The unique ID of the code interpreter tool call. - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required: The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - `container_id` string, required: The ID of the container used to run the code. - `code` string, nullable, required: The code to run, or null if not available. - `outputs` union[], nullable, required: The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available. - … - object: A tool call to run a command on the local shell. - `type` 'local_shell_call', required: The type of the local shell call. Always `local_shell_call`. - `id` string, required: The unique ID of the local shell call. - `call_id` string, required: The unique ID of the local shell tool call generated by the model. - `action` LocalShellExecAction, required: Execute a shell command on the server. - … - `status` 'in_progress' | 'completed' | 'incomplete', required: The status of the local shell call. - object: The output of a local shell tool call. - `type` 'local_shell_call_output', required: The type of the local shell tool call output. Always `local_shell_call_output`. - `id` string, required: The unique ID of the local shell tool call generated by the model. - `output` string, required: A JSON string of the output of the local shell tool call. - `status` 'in_progress' | 'completed' | 'incomplete', nullable: The status of the item. One of `in_progress`, `completed`, or `incomplete`. - object: A tool representing a request to execute one or more shell commands. - `id` string, nullable: The unique ID of the shell tool call. Populated when this item is returned via API. - `call_id` string, required: The unique ID of the shell tool call generated by the model. - `caller` union: The execution context that produced this tool call. - … - `type` 'shell_call', required: The type of the item. Always `shell_call`. - `action` FunctionShellActionParam, required: Commands and limits describing how to run the shell tool call. - … - `status` 'in_progress' | 'completed' | 'incomplete': Status values reported for shell tool calls. - `environment` union - … - object: The streamed output items emitted by a shell tool call. - `id` string, nullable: The unique ID of the shell tool call output. Populated when this item is returned via API. - `call_id` string, required: The unique ID of the shell tool call generated by the model. - `caller` union: The execution context that produced this tool call. - … - `type` 'shell_call_output', required: The type of the item. Always `shell_call_output`. - `output` FunctionShellCallOutputContentParam[], required: Captured chunks of stdout and stderr output, along with their associated outcomes. - … - `status` 'in_progress' | 'completed' | 'incomplete': Status values reported for shell tool calls. - `max_output_length` integer, nullable: The maximum number of UTF-8 characters captured for this shell call's combined output. - object: A tool call representing a request to create, delete, or update files using diff patches. - `type` 'apply_patch_call', required: The type of the item. Always `apply_patch_call`. - `id` string, nullable: The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id` string, required: The unique ID of the apply patch tool call generated by the model. - `caller` union: The execution context that produced this tool call. - … - `status` 'in_progress' | 'completed', required: Status values reported for apply_patch tool calls. - `operation` union, required: One of the create_file, delete_file, or update_file operations supplied to the apply_patch tool. - … - object: The streamed output emitted by an apply patch tool call. - `type` 'apply_patch_call_output', required: The type of the item. Always `apply_patch_call_output`. - `id` string, nullable: The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `call_id` string, required: The unique ID of the apply patch tool call generated by the model. - `caller` union: The execution context that produced this tool call. - … - `status` 'completed' | 'failed', required: Outcome values reported for apply_patch tool call outputs. - `output` string, nullable: Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - object: A list of tools available on an MCP server. - `type` 'mcp_list_tools', required: The type of the item. Always `mcp_list_tools`. - `id` string, required: The unique ID of the list. - `server_label` string, required: The label of the MCP server. - `tools` MCPListToolsTool[], required: The tools available on the server. - … - `error` string, nullable: Error message if the server could not list tools. - object: A request for human approval of a tool invocation. - `type` 'mcp_approval_request', required: The type of the item. Always `mcp_approval_request`. - `id` string, required: The unique ID of the approval request. - `server_label` string, required: The label of the MCP server making the request. - `name` string, required: The name of the tool to run. - `arguments` string, required: A JSON string of arguments for the tool. - object: A response to an MCP approval request. - `type` 'mcp_approval_response', required: The type of the item. Always `mcp_approval_response`. - `id` string, nullable: The unique ID of the approval response - `approval_request_id` string, required: The ID of the approval request being answered. - `approve` boolean, required: Whether the request was approved. - `reason` string, nullable: Optional reason for the decision. - object: An invocation of a tool on an MCP server. - `type` 'mcp_call', required: The type of the item. Always `mcp_call`. - `id` string, required: The unique ID of the tool call. - `server_label` string, required: The label of the MCP server running the tool. - `name` string, required: The name of the tool that was run. - `arguments` string, required: A JSON string of the arguments passed to the tool. - `output` string, nullable: The output from the tool call. - `error` union - … - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed' - `approval_request_id` string, nullable: Unique identifier for the MCP tool call approval request. Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - object: The output of a custom tool call from your code, being sent back to the model. - `type` 'custom_tool_call_output', required: The type of the custom tool call output. Always `custom_tool_call_output`. - `id` string: The unique ID of the custom tool call output in the OpenAI platform. - `call_id` string, required: The call ID, used to map this custom tool call output to a custom tool call. - `caller` union: The execution context that produced this tool call. - … - `output` union, required: The output from the custom tool call generated by your code. Can be a string or an list of output content. - … - object: A call to a custom tool created by the model. - `type` 'custom_tool_call', required: The type of the custom tool call. Always `custom_tool_call`. - `id` string: The unique ID of the custom tool call in the OpenAI platform. - `call_id` string, required: An identifier used to map this custom tool call to a tool call output. - `caller` union: The execution context that produced this tool call. - … - `namespace` string: The namespace of the custom tool being called. - `name` string, required: The name of the custom tool being called. - `input` string, required: The input for the custom tool call generated by the model. - `async` boolean: Whether the custom tool call runs asynchronously. - CompactionTriggerItemParam: Compacts the current context. Must be the final input item. - `id` string, nullable: The unique ID of this compaction trigger. - `type` 'compaction_trigger', required: The type of the item. Always `compaction_trigger`. - ItemReferenceParam: An internal identifier for an item to reference. - `type` 'item_reference', nullable: The type of item to reference. Always `item_reference`. - `id` string, required: The ID of the item to reference. - ProgramItemParam - `id` string, required: The unique ID of this program item. - `type` 'program', required: The item type. Always `program`. - `call_id` string, required: The stable call ID of the program item. - `code` string, required: The JavaScript source executed by programmatic tool calling. - `fingerprint` string, required: Opaque program replay fingerprint that must be round-tripped. - ProgramOutputItemParam - `id` string, required: The unique ID of this program output item. - `type` 'program_output', required: The item type. Always `program_output`. - `call_id` string, required: The call ID of the program item. - `result` string, required: The result produced by the program item. - `status` 'completed' | 'incomplete', required - `previous_response_id` string, nullable: The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about [conversation state](https://developers.openai.com/api/docs/guides/conversation-state). Cannot be used in conjunction with `conversation`. - `tools` Tool[], nullable: An array of tools the model may call while generating a response. You can specify which tool to use by setting the `tool_choice` parameter. - union: A tool that can be used to generate a response. - FunctionTool: Defines a function in your own code the model can choose to call. Learn more about [function calling](https://developers.openai.com/api/docs/guides/function-calling). - `type` 'function', required: The type of the function tool. Always `function`. - `name` string, required: The name of the function to call. - `async` boolean - `description` string, nullable: A description of the function. Used by the model to determine whether or not to call the function. - `parameters` object, nullable, required: A JSON schema object describing the parameters of the function. - `output_schema` object, nullable: A JSON schema object describing the JSON value encoded in string outputs for this function. - `strict` boolean, nullable, required: Whether strict parameter validation is enforced for this function tool. - `defer_loading` boolean: Whether this function is deferred and loaded via tool search. - `allowed_callers` CallableToolAllowedCaller[], nullable: The tool invocation context(s). - FileSearchTool: A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://developers.openai.com/api/docs/guides/tools-file-search). - `type` 'file_search', required: The type of the file search tool. Always `file_search`. - `vector_store_ids` string[], required: The IDs of the vector stores to search. - `max_num_results` integer: The maximum number of results to return. This number should be between 1 and 50 inclusive. - `ranking_options` RankingOptions - `ranker` 'auto' | 'default-2024-11-15' - `score_threshold` number: The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - `hybrid_search` HybridSearchOptions - `embedding_weight` number, required: The weight of the embedding in the reciprocal ranking fusion. - `text_weight` number, required: The weight of the text in the reciprocal ranking fusion. - `filters` union - ComparisonFilter: A filter used to compare a specified attribute key to a given value using a defined comparison operation. - `type` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin', required: Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - `eq`: equals - `ne`: not equal - `gt`: greater than - `gte`: greater than or equal - `lt`: less than - `lte`: less than or equal - `in`: in - `nin`: not in - `key` string, required: The key to compare against the value. - `value` union, required: The value to compare against the attribute key; supports string, number, or boolean types. - … - CompoundFilter: Combine multiple filters using `and` or `or`. - `type` 'and' | 'or', required: Type of operation: `and` or `or`. - `filters` union[], required: Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - … - ComputerTool: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). - `type` 'computer', required: The type of the computer tool. Always `computer`. - ComputerUsePreviewTool: A tool that controls a virtual computer. Learn more about the [computer tool](https://developers.openai.com/api/docs/guides/tools-computer-use). - `type` 'computer_use_preview', required: The type of the computer use tool. Always `computer_use_preview`. - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required - `display_width` integer, required: The width of the computer display. - `display_height` integer, required: The height of the computer display. - WebSearchTool: Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). - `type` 'web_search' | 'web_search_2025_08_26', required: The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - `external_web_access` boolean: Allow live internet access for web search. Defaults to true when omitted. When false, the web search tool runs in offline/cache-only mode and will not fetch new external content. - `filters` object, nullable: Filters for the search. - `allowed_domains` string[], nullable: Allowed domains for the search. If not provided, all domains are allowed. Subdomains of the provided domains are allowed as well. Example: `["pubmed.ncbi.nlm.nih.gov"]` - `user_location` WebSearchApproximateLocation, nullable: The approximate location of the user. - `type` 'approximate': The type of location approximation. Always `approximate`. - `country` string, nullable: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable: Free text input for the region of the user, e.g. `California`. - `city` string, nullable: Free text input for the city of the user, e.g. `San Francisco`. - `timezone` string, nullable: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `search_context_size` 'low' | 'medium' | 'high': High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - MCPTool: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). - `type` 'mcp', required: The type of the MCP tool. Always `mcp`. - `server_label` string, required: A label for this MCP server, used to identify it in tool calls. - `server_url` string, uri: The URL for the MCP server. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `connector_id` 'connector_dropbox' | 'connector_gmail' | 'connector_googlecalendar' | 'connector_googledrive' | 'connector_microsoftteams' | 'connector_outlookcalendar' | 'connector_outlookemail' | 'connector_sharepoint': Identifier for service connectors, like those available in ChatGPT. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more about service connectors [here](https://developers.openai.com/api/docs/guides/tools-connectors-mcp#connectors). This field is deprecated for models released after September 1, 2026. Use `server_url` to connect to a remote MCP server, or `tunnel_id` to connect through a Secure MCP Tunnel. Currently supported `connector_id` values are: - Dropbox: `connector_dropbox` - Gmail: `connector_gmail` - Google Calendar: `connector_googlecalendar` - Google Drive: `connector_googledrive` - Microsoft Teams: `connector_microsoftteams` - Outlook Calendar: `connector_outlookcalendar` - Outlook Email: `connector_outlookemail` - SharePoint: `connector_sharepoint` - `tunnel_id` string: The Secure MCP Tunnel ID to use instead of a direct server URL. One of `server_url`, `connector_id`, or `tunnel_id` must be provided. - `authorization` string: An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here. - `server_description` string: Optional description of the MCP server, used to provide more context. - `headers` object, nullable: Optional HTTP headers to send to the MCP server. Use for authentication or other purposes. - `allowed_tools` union - string[]: A string array of allowed tool names - MCPToolFilter: A filter object to specify which tools are allowed. - `tool_names` string[]: List of allowed tool names. - `read_only` boolean: Indicates whether or not a tool modifies data or is read-only. If an MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), it will match this filter. - `allowed_callers` CallableToolAllowedCaller[], nullable: The tool invocation context(s). - `require_approval` union - object: Specify which of the MCP server's tools require approval. Can be `always`, `never`, or a filter object associated with tools that require approval. - `always` MCPToolFilter: A filter object to specify which tools are allowed. - … - `never` MCPToolFilter: A filter object to specify which tools are allowed. - … - 'always' | 'never': Specify a single approval policy for all tools. One of `always` or `never`. When set to `always`, all tools will require approval. When set to `never`, all tools will not require approval. - `defer_loading` boolean: Whether this MCP tool is deferred and discovered via tool search. - CodeInterpreterTool: A tool that runs Python code to help generate a response to a prompt. - `type` 'code_interpreter', required: The type of the code interpreter tool. Always `code_interpreter`. - `container` union, required: The code interpreter container. Can be a container ID or an object that specifies uploaded file IDs to make available to your code, along with an optional `memory_limit` setting. - string: The container ID. - AutoCodeInterpreterToolParam: Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - `type` 'auto', required: Always `auto`. - `file_ids` string[]: An optional list of uploaded files to make available to your code. - `memory_limit` '1g' | '4g' | '16g' | '64g' - `network_policy` union: Network access policy for the container. - … - `allowed_callers` CallableToolAllowedCaller[], nullable: The tool invocation context(s). - ProgrammaticToolCallingParam - `type` 'programmatic_tool_calling', required: The type of the tool. Always `programmatic_tool_calling`. - ImageGenTool: A tool that generates images using the GPT image models. - `type` 'image_generation', required: The type of the image generation tool. Always `image_generation`. - `model` union - string - 'gpt-image-1' | 'gpt-image-1-mini' | 'gpt-image-1.5' | 'gpt-image-2' | 'gpt-image-2-2026-04-21' | 'gpt-image-2.5-sunburst' | 'gpt-image-2.5-sunburst-2026-09-08' | 'gpt-image-2.5-flare' | 'gpt-image-2.5-flare-2026-09-08': The image generation model to use. One of `gpt-image-1-mini`, `gpt-image-1.5`, `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, `gpt-image-2.5-flare-2026-09-08`, or `chatgpt-image-latest`. Default: `gpt-image-2`. `gpt-image-1` was shut down on October 23, 2026. Use `gpt-image-2.5-sunburst` or `gpt-image-2.5-flare` instead. - `quality` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto': The quality of the generated image. The GPT image models support `low`, `medium`, and `high`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, also support `xhigh` and `max`. Default: `auto`. - `size` union: The size of the generated images. For `gpt-image-2`, `gpt-image-2-2026-04-21`, `gpt-image-2.5-sunburst`, `gpt-image-2.5-sunburst-2026-09-08`, `gpt-image-2.5-flare`, and `gpt-image-2.5-flare-2026-09-08`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. - string - '1024x1024' | '1024x1536' | '1536x1024' | 'auto' - `output_format` 'png' | 'webp' | 'jpeg': The output format of the generated image. One of `png`, `webp`, or `jpeg`. Default: `png`. - `output_compression` integer: Compression level for the output image. Default: 100. - `moderation` 'auto' | 'low': Moderation level for the generated image. Default: `auto`. - `background` 'transparent' | 'opaque' | 'auto': Set the background of the generated image. One of `transparent`, `opaque`, or `auto`. `gpt-image-2.5-sunburst` and `gpt-image-2.5-flare`, including their `2026-09-08` snapshots, support `opaque` and `transparent` backgrounds. Transparent backgrounds are available for supported GPT Image models. For `gpt-image-2` and `gpt-image-2-2026-04-21`, this support is in preview. When using `transparent`, set the output format to `png` or `webp`. Default: `auto`. - `input_fidelity` 'high' | 'low': Control how much effort the model will exert to match the style and features, especially facial features, of input images. Supports `high` and `low` on `gpt-image-1.5`; `gpt-image-1-mini` supports only `low`. For `gpt-image-2`, omit this parameter. Defaults to `low` on supported models. - `input_image_mask` object: Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional). - `image_url` string: Base64-encoded mask image. - `file_id` string: File ID for the mask image. - `partial_images` integer: Number of partial images to generate in streaming mode, from 0 (default value) to 3. - `action` 'generate' | 'edit' | 'auto' - LocalShellToolParam: A tool that allows the model to execute shell commands in a local environment. - `type` 'local_shell', required: The type of the local shell tool. Always `local_shell`. - FunctionShellToolParam: A tool that allows the model to execute shell commands. - `type` 'shell', required: The type of the shell tool. Always `shell`. - `environment` union - ContainerAutoParam - `type` 'container_auto', required: Automatically creates a container for this request - `file_ids` string[]: An optional list of uploaded files to make available to your code. - `memory_limit` '1g' | '4g' | '16g' | '64g' - `network_policy` union: Network access policy for the container. - … - `skills` union[]: An optional list of skills referenced by id or inline data. - … - LocalEnvironmentParam - `type` 'local', required: Use a local computer environment. - `skills` LocalSkillParam[]: An optional list of skills. - … - ContainerReferenceParam - `type` 'container_reference', required: References a container created with the /v1/containers endpoint - `container_id` string, required: The ID of the referenced container. - `allowed_callers` CallableToolAllowedCaller[], nullable: The tool invocation context(s). - CustomToolParam: A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools) - `type` 'custom', required: The type of the custom tool. Always `custom`. - `name` string, required: The name of the custom tool, used to identify it in tool calls. - `async` boolean: Whether the tool response can be returned asynchronously versus immediately returned on next response creation. - `description` string: Optional description of the custom tool, used to provide more context. - `format` union: The input format for the custom tool. Default is unconstrained text. - CustomTextFormatParam: Unconstrained free-form text. - `type` 'text', required: Unconstrained text format. Always `text`. - CustomGrammarFormatParam: A grammar defined by the user. - `type` 'grammar', required: Grammar format. Always `grammar`. - `syntax` 'lark' | 'regex', required - `definition` string, required: The grammar definition. - `defer_loading` boolean: Whether this tool should be deferred and discovered via tool search. - `allowed_callers` CallableToolAllowedCaller[], nullable: The tool invocation context(s). - NamespaceToolParam: Groups function/custom tools under a shared namespace. - `type` 'namespace', required: The type of the tool. Always `namespace`. - `name` string, required: The namespace name used in tool calls (for example, `crm`). - `description` string, required: A description of the namespace shown to the model. - `tools` union[], required: The function/custom tools available inside this namespace. - union: A function or custom tool that belongs to a namespace. - FunctionToolParam - … - CustomToolParam: A custom tool that processes input using a specified format. Learn more about [custom tools](https://developers.openai.com/api/docs/guides/function-calling#custom-tools) - … - ToolSearchToolParam: Hosted or BYOT tool search configuration for deferred tools. - `type` 'tool_search', required: The type of the tool. Always `tool_search`. - `execution` 'server' | 'client' - `description` string, nullable: Description shown to the model for a client-executed tool search tool. - `parameters` EmptyModelParam - WebSearchPreviewTool: This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://developers.openai.com/api/docs/guides/tools-web-search). - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required: The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - `user_location` ApproximateLocation - `type` 'approximate', required: The type of location approximation. Always `approximate`. - `country` string, nullable: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - `region` string, nullable: Free text input for the region of the user, e.g. `California`. - `city` string, nullable: Free text input for the city of the user, e.g. `San Francisco`. - `timezone` string, nullable: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - `search_context_size` 'low' | 'medium' | 'high' - `search_content_types` SearchContentType[] - ApplyPatchToolParam: Allows the assistant to create, delete, or update files using unified diffs. - `type` 'apply_patch', required: The type of the tool. Always `apply_patch`. - `allowed_callers` CallableToolAllowedCaller[], nullable: The tool invocation context(s). - `text` ResponseTextParam: Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text) - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs) - `format` union: An object specifying the format that the model must output. Configuring `{ "type": "json_schema" }` enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs). The default format is `{ "type": "text" }` with no additional options. **Not recommended for gpt-4o and newer models:** Setting to `{ "type": "json_object" }` enables the older JSON mode, which ensures the message the model generates is valid JSON. Using `json_schema` is preferred for models that support it. - ResponseFormatText: Default response format. Used to generate text responses. - `type` 'text', required: The type of response format being defined. Always `text`. - TextResponseFormatJsonSchema: JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs). - `type` 'json_schema', required: The type of response format being defined. Always `json_schema`. - `description` string: A description of what the response format is for, used by the model to determine how to respond in the format. - `name` string, required: The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - `schema` ResponseFormatJsonSchemaSchema, required: The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas [here](https://json-schema.org/). - `strict` boolean, nullable: Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the `schema` field. Only a subset of JSON Schema is supported when `strict` is `true`. To learn more, read the [Structured Outputs guide](https://developers.openai.com/api/docs/guides/structured-outputs). - ResponseFormatJsonObject: JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so. - `type` 'json_object', required: The type of response format being defined. Always `json_object`. - `verbosity` 'low' | 'medium' | 'high', nullable: Constrains the verbosity of the model's response. Lower values will result in more concise responses, while higher values will result in more verbose responses. Currently supported values are `low`, `medium`, and `high`. The default is `medium`. - `reasoning` Reasoning: Configuration options for [reasoning models](https://developers.openai.com/api/docs/guides/reasoning). - `mode` union - string - 'standard' | 'pro' - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', nullable: Constrains effort on reasoning for reasoning models. Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Not all reasoning models support every value. See the [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) for model-specific support. - `summary` 'auto' | 'concise' | 'detailed', nullable: A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`. `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - `context` 'auto' | 'current_turn' | 'all_turns', nullable: Controls which reasoning items are rendered back to the model on later turns. If omitted or set to `auto`, the model determines the context mode. The `gpt-5.6` model family defaults to `all_turns`; earlier models default to `current_turn`. When returned on a response, this is the effective reasoning context mode used for the response. - `generate_summary` 'auto' | 'concise' | 'detailed', nullable: **Deprecated:** use `summary` instead. A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of `auto`, `concise`, or `detailed`. - `truncation` 'auto' | 'disabled' - `instructions` string, nullable: A system (or developer) message inserted into the model's context. When used along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses. - `personality` union - string - 'friendly' | 'pragmatic' - `conversation` union: The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request. Input items and output items from this response are automatically added to this conversation after this response completes. - string: The unique ID of the conversation. - ConversationParam2: The conversation that this response belongs to. - `id` string, required: The unique ID of the conversation. - `tool_choice` union: How the model should select which tool (or tools) to use when generating a response. See the `tools` parameter to see how to specify which tools the model can call. - 'none' | 'auto' | 'required': Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. - ToolChoiceAllowed: Constrains the tools available to the model to a pre-defined set. - `type` 'allowed_tools', required: Allowed tool configuration type. Always `allowed_tools`. - `mode` 'auto' | 'required', required: Constrains the tools available to the model to a pre-defined set. `auto` allows the model to pick from among the allowed tools and generate a message. `required` requires the model to call one or more of the allowed tools. - `tools` object[], required: A list of tool definitions that the model should be allowed to call. For the Responses API, the list of tool definitions might look like: ```json [ { "type": "function", "name": "get_weather" }, { "type": "mcp", "server_label": "deepwiki" }, { "type": "image_generation" } ] ``` - ToolChoiceTypes: Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://developers.openai.com/api/docs/guides/tools). - `type` 'file_search' | 'web_search_preview' | 'computer' | 'computer_use_preview' | 'computer_use' | 'web_search_preview_2025_03_11' | 'image_generation' | 'code_interpreter', required: The type of hosted tool the model should to use. Learn more about [built-in tools](https://developers.openai.com/api/docs/guides/tools). Allowed values are: - `file_search` - `web_search_preview` - `computer` - `computer_use_preview` - `computer_use` - `code_interpreter` - `image_generation` - ToolChoiceFunction: Use this option to force the model to call a specific function. - `type` 'function', required: For function calling, the type is always `function`. - `name` string, required: The name of the function to call. - ToolChoiceMCP: Use this option to force the model to call a specific tool on a remote MCP server. - `type` 'mcp', required: For MCP tools, the type is always `mcp`. - `server_label` string, required: The label of the MCP server to use. - `name` string, nullable: The name of the tool to call on the server. - ToolChoiceCustom: Use this option to force the model to call a specific custom tool. - `type` 'custom', required: For custom tool calling, the type is always `custom`. - `name` string, required: The name of the custom tool to call. - SpecificProgrammaticToolCallingParam - `type` 'programmatic_tool_calling', required: The tool to call. Always `programmatic_tool_calling`. - SpecificApplyPatchParam: Forces the model to call the apply_patch tool when executing a tool call. - `type` 'apply_patch', required: The tool to call. Always `apply_patch`. - SpecificFunctionShellParam: Forces the model to call the shell tool when a tool call is required. - `type` 'shell', required: The tool to call. Always `shell`. - `parallel_tool_calls` boolean, nullable: Whether to allow the model to run tool calls in parallel. ## Response `200` Success - TokenCountsResource - `object` 'response.input_tokens', required - `input_tokens` integer, required ## Other responses - `400`: The request to count input tokens is invalid or contains incompatible parameters. - `429`: The request was rejected because a rate limit was exceeded. ## Changes - **2026-10-26** `410e6429083a`: 9 info - added the new optional request property `input/anyOf[subschema #1]/oneOf[subschema #2]/items/oneOf[subschema #1: Input message]/content/oneOf[subschema #2: Input item content list]/items/oneOf[subschema #1: Input text]/prompt_cache_breakpoint/ttl` - added the new optional request property `input/anyOf[subschema #1]/oneOf[subschema #2]/items/oneOf[subschema #1: Input message]/content/oneOf[subschema #2: Input item content list]/items/oneOf[subschema #2: Input image]/prompt_cache_breakpoint/ttl` - added the new optional request property `input/anyOf[subschema #1]/oneOf[subschema #2]/items/oneOf[subschema #1: Input message]/content/oneOf[subschema #2: Input item content list]/items/oneOf[subschema #3: Input file]/prompt_cache_breakpoint/ttl` - added the new optional request property `input/anyOf[subschema #1]/oneOf[subschema #2]/items/oneOf[subschema #2: Item]/oneOf[subschema #1: Input message]/content/items/oneOf[subschema #1: Input text]/prompt_cache_breakpoint/ttl` - …5 more - **2026-10-23** `af780af62f70`: 3 info - the `` request property default value changed from `gpt-image-1` to `gpt-image-2` - the `` request property default value changed from `gpt-image-1` to `gpt-image-2` - the `` request property default value changed from `gpt-image-1` to `gpt-image-2` - …earlier changes not shown [Operation history](https://skmtc.dev/omnistack-sh/apis/openai-api/changes/responses/input_tokens/post.md) --- [API](https://skmtc.dev/omnistack-sh/apis/openai-api.md) - [All operations](https://skmtc.dev/omnistack-sh/apis/openai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnistack-sh/apis/openai-api/revisions/0a26f104d35f?raw)