web_search tool to let GPT models search for current information and return source citations. This page covers the request format, response structure, and billing.
Integration
In OneToken, use the Responses API (/v1/responses) and add web_search to tools to enable web search. An API key from the default group is sufficient; no additional activation is required.
Model performance reference
The following results were recorded on June 11, 2026, and are provided as a selection reference. Search count, latency, and token usage vary with the question and search results.Quickstart
ReplaceYOUR_ONETOKEN_API_KEY in the examples with your OneToken API key.
cURL
Python (OpenAI SDK)
Response structure
Theoutput array contains these items in execution order:
status: "completed" means the response finished successfully. If the response is incomplete, check incomplete_details. If the output token limit was reached, increase max_output_tokens and retry.
Billing
Web search costs include a tool call fee and a retrieved-content token fee:In the original test, a single request cost approximately $0.01 in search fees plus the cost of 9k input tokens for gpt-5.4, and $0.08 in search fees plus the cost of 50k input tokens for gpt-5.5. Actual charges follow OneToken’s current pricing and your usage bill.
Notes
- Use the Responses API with the
web_searchtool: GPT-5 models do not support the Chat Completionsweb_search_optionsparameter. Using it returns 400Unknown parameter: 'web_search_options'. That parameter is intended for*-search-previewmodels. - Set
max_output_tokensto at least 8192: This limit includes both reasoning and final-answer tokens. If the limit is too low, the response may returnstatus: "incomplete"after exhausting the allowance. Consumed tokens are still billed even when there is no final answer. - The legacy
web_search_previewtool type is also available with the same behavior. New integrations should useweb_search. - To control costs, choose gpt-5.4 or ask the model to reduce search activity, for example, “search at most twice.” Prompts cannot guarantee a search-count limit, so use the returned
web_search_callcount as the source of truth.
FAQ
Q: How can I confirm that the response actually used web search? A: Check thatoutput contains an item with type="web_search_call", and that message.content[].annotations contains url_citation. These records help you verify tool execution and source citations. Do not determine whether web search ran from the answer text alone.
Q: Do I need a different group or a special API key?
A: No. You can use an API key from the OneToken default group.
Q: Which models are supported?
A: The examples use gpt-5.4. You can also change the model to gpt-5.5. For other models, check OneToken’s current model and tool support before integrating, then verify the search call and citation records.
Related docs
API quickstart
Learn the basics of calling the OneToken API
API user manual
Review API key, model, and client configuration

