Web search | OpenAI API

Web search allows models to access up-to-date information from the internet and provide answers with sourced citations. To enable this, use the web search tool in the Responses API or, in some cases, Chat Completions.

There are three main types of web search available with OpenAI models:

Non‑reasoning web search: The non-reasoning model sends the user’s query to the web search tool, which returns the response based on top results. There’s no internal planning and the model simply passes along the search tool’s responses. This method is fast and ideal for quick lookups.
Agentic search with reasoning models is an approach where the model actively manages the search process. It can perform web searches as part of its chain of thought, analyze results, and decide whether to keep searching. This flexibility makes agentic search well suited to complex workflows, but it also means searches take longer than quick lookups. For example, you can adjust reasoning levels on models like gpt-5.5 to change both the depth and latency of the search.
Deep research is a specialized, agent-driven method for in-depth, extended investigations by reasoning models. The model conducts web searches as part of its chain of thought, often tapping into hundreds of sources. Deep research can run for several minutes and is best used with background mode. Use gpt-5.5 with reasoning set to high or xhigh.

Choose an integration

Use case	Recommended path	Notes
New web search integration	Responses API with `web_search` and `gpt-5.5`	Supports hosted web search controls such as filters, sources, and live-access control
Existing Chat Completions search integration	Chat Completions with `gpt-5-search-api`	Use this only when you need to preserve a Chat Completions integration
Multi-step research or long-running reporting	`gpt-5.5` with `high` or `xhigh` reasoning	Use background mode for reports that can take several minutes

Using the Responses API, you can enable web search by configuring it in the tools array in an API request to generate content. Like any other tool, the model can choose to search the web or not based on the content of the input prompt.

For new Responses API integrations, use { "type": "web_search" }. The earlier web_search_preview tool remains available for legacy integrations, but it does not support newer controls such as filters and external_web_access.

Web search tool example

javascript

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const client = new OpenAI();

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

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    tools=[{"type": "web_search"}],
    input="What was a positive news story from today?"
)

print(response.output_text)

1
2
3
4
5
6
7
8
curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-5.5",
        "tools": [{"type": "web_search"}],
        "input": "what was a positive news story from today?"
}'

1
2
3
4
5
6
7
8
openai responses create \
  --model gpt-5.5 \
  --raw-output \
  --transform 'output.#(type=="message").content.0.text' <<'YAML'
tools:
  - type: web_search
input: What was a positive news story from today?
YAML

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
using OpenAI.Responses;

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
OpenAIResponseClient client = new(model: "gpt-5.5", apiKey: key);

ResponseCreationOptions options = new();
options.Tools.Add(ResponseTool.CreateWebSearchTool());

OpenAIResponse response = (OpenAIResponse)client.CreateResponse([
    ResponseItem.CreateUserMessageItem([
        ResponseContentPart.CreateInputTextPart("What was a positive news story from today?"),
    ]),
], options);

Console.WriteLine(response.GetOutputText());

Output and citations

Model responses that use the web search tool will include two parts:

A web_search_call output item with the ID of the search call, along with the action taken in web_search_call.action. The action is one of:
- search, which represents a web search. It will usually (but not always) includes the search queries which were searched. Search actions incur a tool call cost (see pricing).
- open_page, which represents a page being opened. Supported in reasoning models.
- find_in_page, which represents searching within a page. Supported in reasoning models.
A message output item containing:
- The text result in message.content[0].text
- Annotations message.content[0].annotations for the cited URLs

By default, the model’s response will include inline citations for URLs found in the web search results. In addition to this, the url_citation annotation object will contain the URL, title and location of the cited source.

When displaying web results or information contained in web results to end users, inline citations must be made clearly visible and clickable in your user interface.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed",
    "action": {
      "type": "search",
      "query": "latest news about AI"
    }
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

Using the Chat Completions API, you can directly access the fine-tuned models and tool used by Search in ChatGPT.

When using Chat Completions, the model always retrieves information from the web before responding to your query. To let the model decide whether to search, switch to the Responses API with the web_search tool.

Currently, use this model for web search in Chat Completions:

gpt-5-search-api

Web search parameter example

javascript

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
    model: "gpt-5-search-api",
    web_search_options: {},
    messages: [{
        "role": "user",
        "content": "What was a positive news story from today?"
    }],
});

console.log(completion.choices[0].message.content);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5-search-api",
    web_search_options={},
    messages=[
        {
            "role": "user",
            "content": "What was a positive news story from today?",
        }
    ],
)

print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9
10
11
curl -X POST "https://api.openai.com/v1/chat/completions" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-5-search-api",
        "web_search_options": {},
        "messages": [{
            "role": "user",
            "content": "What was a positive news story from today?"
        }]
    }'

Output and citations

The API response item in the choices array will include:

message.content with the text result from the model, inclusive of any inline citations
annotations with a list of cited URLs

When displaying web results or information contained in web results to end users, inline citations must be made clearly visible and clickable in your user interface.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "the model response is here...",
      "refusal": null,
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "end_index": 985,
            "start_index": 764,
            "title": "Page title...",
            "url": "https://..."
          }
        }
      ]
    },
    "finish_reason": "stop"
  }
]

Migrating from legacy web search

If you use	Recommended path	Notes
`web_search_preview` in Responses	Migrate to `web_search`	`web_search` supports newer controls such as `filters` and `external_web_access`
`gpt-4o-search-preview` or `gpt-4o-mini-search-preview`	Migrate to Responses `web_search`, or use `gpt-5-search-api` if you must stay on Chat Completions	The preview search models are deprecated and shut down on 2026-07-23
Chat Completions search integrations	Use `gpt-5-search-api`, or migrate to Responses `web_search` for more tool controls and optional search	Chat Completions search models always search before responding; Responses search is a tool

Search context size

search_context_size controls how much context from web search results is made available to the model before it generates a response. Use low for simple lookups, medium for a balanced default, and high when the answer may require more detail from search results. This setting does not set an exact token count or guarantee a specific number of sources or citations.

Set search context size

javascript

1
2
3
4
5
6
7
8
9
10
11
12
13
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    tools=[{
        "type": "web_search",
        "search_context_size": "low",
    }],
    input="What movie won best picture in 2025?",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
using OpenAI.Responses;

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
OpenAIResponseClient client = new(model: "gpt-5.5", apiKey: key);

ResponseCreationOptions options = new();
options.Tools.Add(ResponseTool.CreateWebSearchTool(
    searchContextSize: WebSearchToolContextSize.Low
));

OpenAIResponse response = (OpenAIResponse)client.CreateResponse([
    ResponseItem.CreateUserMessageItem([
        ResponseContentPart.CreateInputTextPart(
            "What movie won best picture in 2025?"
        )
    ])
], options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
    model: "gpt-5.5",
    tools: [{
        type: "web_search",
        search_context_size: "low",
    }],
    input: "What movie won best picture in 2025?",
});
console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-5.5",
        "tools": [{
            "type": "web_search",
            "search_context_size": "low"
        }],
        "input": "What movie won best picture in 2025?"
    }'

Domain filtering

Domain filtering in web search lets you limit results to a specific set of domains. With the filters parameter you can configure up to 100 allowed_domains or up to 100 blocked_domains. When formatting domains, omit the HTTP or HTTPS prefix. For example, use openai.com instead of https://openai.com/. This approach also includes subdomains in the search. Note that domain filtering is only available in the Responses API with the web_search tool.

Sources

To view all URLs retrieved during a web search, use the sources field. Unlike inline citations, which show only the most relevant references, sources returns the complete list of URLs the model consulted when forming its response. The number of sources is often greater than the number of citations. Real-time third-party feeds are also surfaced here and are labeled as oai-sports, oai-weather, or oai-finance. The sources field is available with both the web_search and web_search_preview tools.

List sources

curl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.5",
    "reasoning": { "effort": "low" },
    "tools": [
      {
        "type": "web_search",
        "filters": {
          "allowed_domains": [
            "pubmed.ncbi.nlm.nih.gov",
            "clinicaltrials.gov",
            "www.who.int",
            "www.cdc.gov",
            "www.fda.gov"
          ],
          "blocked_domains": [
            "reddit.com",
            "quora.com",
            "wikipedia.org"
          ]
        }
      }
    ],
    "tool_choice": "auto",
    "include": ["web_search_call.action.sources"],
    "input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
  }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
    model: "gpt-5.5",
    reasoning: { effort: "low" },
    tools: [
        {
            type: "web_search",
            filters: {
                allowed_domains: [
                    "pubmed.ncbi.nlm.nih.gov",
                    "clinicaltrials.gov",
                    "www.who.int",
                    "www.cdc.gov",
                    "www.fda.gov",
                ],
                blocked_domains: [
                    "reddit.com",
                    "quora.com",
                    "wikipedia.org",
                ],
            },
        },
    ],
    tool_choice: "auto",
    include: ["web_search_call.action.sources"],
    input: "Please perform a web search on how semaglutide is used in the treatment of diabetes.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    reasoning={"effort": "low"},
    tools=[
        {
            "type": "web_search",
            "filters": {
                "allowed_domains": [
                    "pubmed.ncbi.nlm.nih.gov",
                    "clinicaltrials.gov",
                    "www.who.int",
                    "www.cdc.gov",
                    "www.fda.gov",
                ],
                "blocked_domains": [
                    "reddit.com",
                    "quora.com",
                    "wikipedia.org",
                ],
            },
        }
    ],
    tool_choice="auto",
    include=["web_search_call.action.sources"],
    input="Please perform a web search on how semaglutide is used in the treatment of diabetes.",
)

print(response.output_text)

User location

To refine search results based on geography, you can specify an approximate user location using country, city, region, and/or timezone.

The city and region fields are free text strings, like Minneapolis and Minnesota respectively.
The country field is a two-letter ISO country code, like US.
The timezone field is an IANA timezone like America/Chicago.

Note that user location is not supported for deep research models using web search.

Customizing user location

javascript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    tools=[{
        "type": "web_search",
        "user_location": {
            "type": "approximate",
            "country": "GB",
            "city": "London",
            "region": "London",
        }
    }],
    input="What are the best restaurants near me?",
)

print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
using OpenAI.Responses;

string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
OpenAIResponseClient client = new(model: "gpt-5.5", apiKey: key);

ResponseCreationOptions options = new();
options.Tools.Add(ResponseTool.CreateWebSearchTool(
    userLocation: WebSearchToolLocation.CreateApproximateLocation(
        country: "GB",
        city: "London",
        region: "Granary Square"
    )
));

OpenAIResponse response = (OpenAIResponse)client.CreateResponse([
    ResponseItem.CreateUserMessageItem([
        ResponseContentPart.CreateInputTextPart(
            "What are the best restaurants near me?"
        )
    ])
], options);

Console.WriteLine(response.GetOutputText());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
    model: "gpt-5.5",
    tools: [{
        type: "web_search",
        user_location: {
            type: "approximate",
            country: "GB",
            city: "London",
            region: "London"
        }
    }],
    input: "What are the best restaurants near me?",
});
console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl "https://api.openai.com/v1/responses" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
        "model": "gpt-5.5",
        "tools": [{
            "type": "web_search",
            "user_location": {
                "type": "approximate",
                "country": "GB",
                "city": "London",
                "region": "London"
            }
        }],
        "input": "What are the best restaurants near me?"
    }'

Customizing user location

javascript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
from openai import OpenAI
client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-5-search-api",
    web_search_options={
        "user_location": {
            "type": "approximate",
            "approximate": {
                "country": "GB",
                "city": "London",
                "region": "London",
            }
        },
    },
    messages=[{
        "role": "user",
        "content": "What are the best restaurants near me?",
    }],
)

print(completion.choices[0].message.content)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import OpenAI from "openai";
const client = new OpenAI();

const completion = await client.chat.completions.create({
    model: "gpt-5-search-api",
    web_search_options: {
        user_location: {
            type: "approximate",
            approximate: {
                country: "GB",
                city: "London",
                region: "London",
            },
        },
    },
    messages: [{
        "role": "user",
        "content": "What are the best restaurants near me?",
    }],
});
console.log(completion.choices[0].message.content);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
curl -X POST "https://api.openai.com/v1/chat/completions" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -H "Content-type: application/json" \
    -d '{
        "model": "gpt-5-search-api",
        "web_search_options": {
            "user_location": {
                "type": "approximate",
                "approximate": {
                    "country": "GB",
                    "city": "London",
                    "region": "London"
                }
            }
        },
        "messages": [{
            "role": "user",
            "content": "What are the best restaurants near me?"
        }]
    }'

Live internet access

Control whether the web search tool fetches live content or uses only cached/indexed results in the Responses API.

Set external_web_access: false on the web_search tool to run in offline/cache‑only mode.
Default is true (live access) if you do not set it.
Preview variants (web_search_preview) ignore this parameter and behave as if external_web_access is true.

Control live internet access

curl

1
2
3
4
5
6
7
8
curl "https://api.openai.com/v1/responses" -H "Content-Type: application/json" -H "Authorization: Bearer $OPENAI_API_KEY" -d '{
  "model": "gpt-5.5",
  "tools": [
    { "type": "web_search", "external_web_access": false }
  ],
  "tool_choice": "auto",
  "input": "Find when the Eiffel Tower opened to the public and cite the source."
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
model: "gpt-5.5",
tools: [
{ type: "web_search", external_web_access: false },
],
tool_choice: "auto",
input: "Find when the Eiffel Tower opened to the public and cite the source.",
});

console.log(response.output_text);

1
2
3
4
5
6
7
8
9
10
from openai import OpenAI
client = OpenAI()

resp = client.responses.create(
model="gpt-5.5",
tools=[{ "type": "web_search", "external_web_access": False }],
tool_choice="auto",
input="Find when the Eiffel Tower opened to the public and cite the source.",
)
print(resp.output_text)

Limitations

Chat Completions API

The Chat Completions API supports only specialized search models for web search. These models do not support Responses API web_search features such as domain filters, complete source lists, live-access control.

Model	Context window	Limitation
`gpt-5-search-api`	200k	Uses the Chat Completions search model path
`gpt-4o-search-preview`	128k	Uses the Chat Completions search model path; deprecated, shutdown 2026-07-23
`gpt-4o-mini-search-preview`	128k	Uses the Chat Completions search model path; deprecated, shutdown 2026-07-23

Responses API

Use the hosted web_search tool. The Responses API still accepts web_search_preview for legacy integrations, but use web_search for new integrations.

For a larger model context window, use gpt-5.5. The web search context window remains 128k.

Model	Model context window	Limitation
`gpt-4.1`	1M	Search context is limited to 128k
`gpt-4.1-mini`	1M	Search context is limited to 128k
`o4-mini`	200k	Search context is limited to 128k; deprecated, shutdown 2026-10-23

For Responses API web search, the search context window is limited to 128k, even when the model context window is larger.

Web search does not support gpt-5 with minimal reasoning.
gpt-5.4 with reasoning effort set to none may produce lower-quality results.
Responses API web search uses the underlying model’s tiered rate limits.
web_search_preview does not support filters and ignores external_web_access.
With tool_choice: "auto", search is optional. Use tool_choice: "required" or a specific web search tool choice when search must run.

Usage notes

API Availability	Rate limits	Notes
Responses Chat Completions Assistants	Same as tiered rate limits for underlying model used with the tool.	Pricing ZDR and data residency

Suggested

Get started

Core concepts

Agents SDK

Tools

Run and scale

Evaluation

Realtime and audio

Model optimization

Specialized models

Going live

Legacy APIs

Resources

Getting Started

Using Codex

Configuration

Administration

Automation

Learn

Releases

Core Concepts

Plan

Build

Deploy

Conversion apps

Guides

Resources

Guides

File Upload

API

Measurement

Advertiser API

API Reference

Recent

Topics

Topics

Contribute

Categories

Topics

Programs

Events

Choose an integration

Output and citations

Output and citations

Migrating from legacy web search

Search context size

Domain filtering

Sources

User location

Live internet access

Limitations

Chat Completions API

Responses API

Usage notes