What Is the OpenAI Web Search API? A Practical Guide for Developers

TLDR: The OpenAI web search capability is not a standalone search endpoint. It is a hosted tool called web_search that you attach to a Responses API request, and the model decides when to search, reads the results, and answers with citations (OpenAI documentation, fetched 2026-09-17). That design is ideal when you want grounded answers out of a GPT model, and the wrong fit when your application needs the raw results themselves. This guide covers the two integration paths, the domain and context controls, verified code, and the failure mode that costs teams the most.

What is the OpenAI web search API? It is the web_search tool type in the Responses API, plus search-enabled Chat Completions models such as gpt-5-search-api. The model triggers searches itself, then generates an answer whose claims are annotated with the source URLs it used, so grounding happens inside the model call rather than in your retrieval pipeline.

The distinction matters more than the naming suggests. A standalone web search API hands your application a list of results with titles, URLs, and snippets, and you decide what to do with them. OpenAI's web search hands the model the results and gives you back an answer. If your job is to feed a RAG pipeline, rank sources, or store results, you want the first shape. If your job is to get a current, cited answer from a GPT model with zero retrieval code, you want the second.

How Does the web_search Tool Work in the Responses API?

You add the tool to a Responses API request and the model handles the rest. It analyzes the prompt, decides whether a search would improve the answer, generates the queries, reads the results, and produces output annotated with citations (OpenAI documentation, fetched 2026-09-17).

Here is a minimal Python call with realistic error handling, written against the documented surface:

from openai import OpenAI
client = OpenAI() # reads OPENAI_API_KEY from the environment

try:
    response = client.responses.create(
        model="gpt-5.5",
        tools=[{"type": "web_search"}],
        input="What changed in the EU AI Act implementation guidance this month?",
    )
    print(response.output_text)
except Exception as e:
    print(f"request failed: {e}") # surface auth, rate limit, or billing errors, do not retry blindly

The response breaks the work into actions you can audit: search actions carry the queries the model ran, open_page represents a page being opened, and find_in_page represents in-page search, with the latter two supported in reasoning models (OpenAI documentation, fetched 2026-09-17). Those action records are how you verify the model actually searched, which matters for the failure mode covered below.

What Is the Difference Between Responses web_search and Chat Completions Search Models?

There are two integration paths and the difference is control. In the Responses API, web_search is an optional tool: the model can search when the question needs it. In Chat Completions, the search-enabled models such as gpt-5-search-api always search before responding, every request, whether or not the question needs it (OpenAI documentation, fetched 2026-09-17).

OpenAI also states plainly that the older preview search models, gpt-4o-search-preview and gpt-4o-mini-search-preview, were deprecated and shut down on 2026-07-23, and directs existing users to migrate to the Responses API web_search tool or to gpt-5-search-api (OpenAI documentation, fetched 2026-09-17). If you have older code referencing the preview models, that code is now broken at the model identifier level and will fail on request, which is worth an immediate check.

The migration guidance also notes what web_search supports that the old surface did not: filters, external web access control, and a return token budget (OpenAI documentation, fetched 2026-09-17). Those controls are the reason new integrations should build on Responses.

What Controls Does web_search Give You Over the Search?

Three documented controls shape what the model sees. First, search_context_size sets how much context from search results reaches the model: low for simple lookups, medium as the balanced default, and high when the answer needs more detail (OpenAI documentation, fetched 2026-09-17). Raising it improves recall on research-heavy questions and costs more tokens on every call.

Second, the filters parameter accepts up to 100 allowed_domains or up to 100 blocked_domains, without the HTTP or HTTPS prefix, and subdomains are included. Domain filtering is available in the Responses API only, which is one more reason to prefer it over Chat Completions for anything that must respect a source policy (OpenAI documentation, fetched 2026-09-17).

Third, user_location with type approximate localizes results, accepting country, region, city, and similar fields (OpenAI documentation, fetched 2026-09-17). This is the control that changes answers for queries like "best restaurants near me."

When Should You Use a Hosted Search Tool Instead of a Standalone Search API?

Decision framework: use OpenAI's web search when the deliverable is an answer from a GPT model and you accept model-mediated retrieval, and use a standalone web search API when the deliverable is the results themselves. The tradeoff is convenience against control. A hosted tool gives you zero retrieval code to write and no result ranking to own, at the cost of deciding what "relevant" means inside someone else's model loop. A standalone API gives you the raw results, lets you cache them, filter domains deterministically, and pipe them into any model or no model, at the cost of owning the retrieval layer.

Concretely, a support copilot that must answer customers with current policy pages is a hosted-tool problem. A RAG pipeline that indexes fresh web content nightly, an agent that stores its sources for audit, or a system where two different models consume the same search results is a standalone-API problem, and for those the You.com Web Search API returns web and news results with snippets, source URLs, and metadata in a single request.

You can also mix both shapes: search first with a standalone API, pass the results into the model context, and fall back to the hosted tool only when the standalone results are thin. The LLM web search API guide covers that retrieval-first architecture in detail.

What Is the Failure Mode That Catches Teams Using web_search?

The concrete failure mode to detect: the model does not search, and answers from training data without telling you. Because search is model-determined, a question phrased in a way the model considers answerable from memory can skip the tool entirely, and the output looks like a grounded answer because nothing errors. On anything time-sensitive, that is a stale answer wearing the costume of a cited one.

Detection is to check the response for search actions. The response includes the search queries that were executed, so an answer with zero search actions on a question that required fresh data is a red flag you can alert on in code (OpenAI documentation, fetched 2026-09-17). A cheap policy is to log the action count per request and review the zero-search subset weekly against questions that were genuinely time-sensitive.

The second cost to watch is token spend from search context. Results retrieved by the tool are part of the model's context, and search_context_size set to high multiplies that on every call. Search actions also incur a tool call cost per search, billed on top of tokens, with current rates on the OpenAI pricing page (OpenAI documentation, fetched 2026-09-17).

How Do the Other First-Party Vendor Tools Compare?

OpenAI is one of three first-party vendors that bolt search onto their own models. Anthropic ships a server-side web search tool for the Claude Messages API, versioned as web_search_20260318 at the time of writing, with its own domain filters and a dynamic filtering feature that runs code over results before they reach the context window (Anthropic documentation, fetched 2026-09-17). Google ships grounding with Google Search for the Gemini API as the google_search tool, which returns inline citation annotations and is billed per executed query on Gemini 3 models (Google documentation, fetched 2026-09-17).

All three share the same architectural property: the vendor's model mediates the search, and you get an answer plus citations rather than a result list. The companion guides cover each in depth: the Claude web search tool guide and the Gemini grounding guide. For a vendor-neutral comparison focused on evaluation criteria rather than features, the web search API evaluation guide lays out the test harness. The hub page for the whole category is the search API overview.

Next action: audit any existing code for the retired gpt-4o-search-preview model identifiers before anything else, then run the example call above with your most time-sensitive internal question and check that the response reports at least one search action. If it does not, tighten the prompt or move to a standalone search API where retrieval is guaranteed because you initiate it. A key for the You.com platform covers the standalone path, with rates on the pricing page.