How can an API request require OpenAI web search to run?

Definition: In the OpenAI Responses API, tool_choice controls which tools the model may call. Set it to "required" and provide the hosted web_search tool when the request must call a tool, using the web search tool alone when the required call must be a search.

Key facts

• OpenAI's web search documentation says that tool_choice: "auto" leaves search optional and that tool_choice: "required" or a specific web search tool choice makes search run.
• The Responses API reference defines required as requiring the model to call one or more tools.
• For new Responses API integrations, OpenAI documents { "type": "web_search" }; web_search_preview remains for legacy integrations.
• A response that uses web search contains a web_search_call output item and a message item with the text and URL citation annotations.

What does tool_choice: "required" change?

The Responses API reference describes tool_choice as the parameter that controls how the model selects tools while generating a response. Its options are "none", "auto", and "required": none prevents tool calls, auto lets the model choose between a message and one or more tools, and required requires one or more tools.

OpenAI's web search guide applies that general parameter to search. It states that tool_choice: "auto" makes search optional and recommends tool_choice: "required" or a specific web search tool choice when search must run. If web_search is the only tool in the request, the required tool call is therefore a web search.

const response = await client.responses.create({
  model: "gpt-6-astra",
  tools: [{ type: "web_search" }],
  tool_choice: "required",
  input: "What was a positive news story from today?",
});

Does required select web search by itself?

No. The API reference says that tools is an array of tools the model may call and that tool_choice specifies which tool to use. When several tools are supplied, required requires one or more calls but leaves the permitted set defined by the tools array. To require search specifically, supply the hosted web search tool and use the web search specific choice documented by OpenAI when that form is supported.

The current Responses API web search integration uses { "type": "web_search" }. The guide describes web_search_preview as an earlier tool for legacy integrations and says that it lacks newer controls such as filters, external_web_access, and return_token_budget.

What does a successful search response contain?

OpenAI's guide describes two output parts for responses that use the web search tool. A web_search_call item records the search call and its action, while a message item contains the text result and annotations for cited URLs. The guide says the default response includes inline citations for URLs found in web search results, with the URL, title, and location in the url_citation annotation.

If the application needs every URL retrieved during the search, the same guide documents the include value web_search_call.action.sources. It distinguishes this complete source list from inline citations, which show only the most relevant references. The documented source list can be longer than the citation list.

Can the request constrain the search?

The Responses API web search tool supports domain filtering through filters. OpenAI documents up to 100 allowed_domains or up to 100 blocked_domains, with domains written without the HTTP or HTTPS prefix. The guide says this filtering is available in the Responses API with web_search.

The same documentation also describes external_web_access. Its default is live access when the field is omitted, while setting it to false runs the web_search tool in offline or cache-only mode. The preview tool ignores this parameter and behaves as if live access were enabled.

Related terms

• ChatGPT search
• Answer engine
• AI citation
• Grounding

FAQ

What value makes an OpenAI Responses API request require a tool call?

Set tool_choice to "required". The API reference defines that value as requiring the model to call one or more tools.

How do I make that required call a web search?

Put { "type": "web_search" } in the tools array and use tool_choice: "required" when it is the only supplied tool. OpenAI's web search guide also documents a specific web search tool choice for requests that must run search.

Does required search return citations automatically?

The web search guide says responses using the tool include inline citations for URLs found in search results by default. It also documents source retrieval with include: ["web_search_call.action.sources"].

Sources

1. OpenAI, "Web search", undated
2. OpenAI, "Create a model response", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer