Documentation 2026-04-28 06:15 UTC to 2026-04-30 06:13 UTC

12 customUserLocationExampleCoarse,12 customUserLocationExampleCoarse,

13 customUserLocationExampleCoarseChat,13 customUserLocationExampleCoarseChat,

14 listSourcesExample,14 listSourcesExample,

15 searchContextSize,

15} from "./web-search-examples";16} from "./web-search-examples";

16 17 

17 18 

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

22 23 

231. 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.241. 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.

242. 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 GPT-5’s reasoning level to change both the depth and latency of the search.252. 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.

253. 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. These tasks typically use models like `o3-deep-research`, `o4-mini-deep-research`, or `gpt-5` with reasoning level set to `high`.263. 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`.

27 

28## Choose an integration

29 

30| Use case | Recommended path | Notes |

31| --------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------- |

32| 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 |

33| Existing Chat Completions search integration | Chat Completions with `gpt-5-search-api` | Use this only when you need to preserve a Chat Completions integration |

34| 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 |

26 35 

27Using the [Responses API](https://developers.openai.com/api/docs/api-reference/responses), 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.36Using the [Responses API](https://developers.openai.com/api/docs/api-reference/responses), 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.

28 37 

38For 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`.

39 

29## Output and citations40## Output and citations

30 41 

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

49 {60 {

50 "type": "web_search_call",61 "type": "web_search_call",

51 "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",62 "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",

52 "status": "completed"63 "status": "completed",

64 "action": {

65 "type": "search",

66 "query": "latest news about AI"

67 }

53 },68 },

54 {69 {

55 "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",70 "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",

79 94 

80 95 

81 96 

97## Migrating from legacy web search

98 

99| If you use | Recommended path | Notes |

100| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |

101| `web_search_preview` in Responses | Migrate to `web_search` | `web_search` supports newer controls such as `filters` and `external_web_access` |

102| `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 |

103| 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 |

104 

105## Search context size

106 

107`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.

108 

109 

110 

82## Domain filtering111## Domain filtering

83 112 

84Domain 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.113Domain 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.

113 142 

114 143 

115 144 

116## API compatibility145## Limitations

117 146 

118Web search is available in the Responses API as the generally available version of the tool, `web_search`, as well as the earlier tool version, `web_search_preview`.147#### Chat Completions API

119To use web search in the Chat Completions API, use the specialized web search models `gpt-5-search-api`, `gpt-4o-search-preview` and `gpt-4o-mini-search-preview`.

120 148 

121## Limitations149The 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.

150 

151| Model | Context window | Limitation |

152| ---------------------------- | -------------: | -------------------------------------------------------------------------------------------------------------------------------------------- |

153| `gpt-5-search-api` | 200k | Uses the Chat Completions search model path |

154| `gpt-4o-search-preview` | 128k | Uses the Chat Completions search model path; [deprecated, shutdown 2026-07-23](https://developers.openai.com/api/docs/deprecations#2026-04-22-legacy-gpt-model-snapshots) |

155| `gpt-4o-mini-search-preview` | 128k | Uses the Chat Completions search model path; [deprecated, shutdown 2026-07-23](https://developers.openai.com/api/docs/deprecations#2026-04-22-legacy-gpt-model-snapshots) |

156 

157#### Responses API

158 

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

160 

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

162 

163| Model | Model context window | Limitation |

164| -------------- | -------------------: | ---------------------------------------------------------------------------------------------------------------------------------- |

165| `gpt-4.1` | 1M | Search context is limited to 128k |

166| `gpt-4.1-mini` | 1M | Search context is limited to 128k |

167| `o4-mini` | 200k | Search context is limited to 128k; [deprecated, shutdown 2026-10-23](https://developers.openai.com/api/docs/deprecations#2026-04-22-legacy-gpt-model-snapshots) |

168 

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

122 170 

123- Web search is currently not supported in [`gpt-5`](https://developers.openai.com/api/docs/models/gpt-5) with `minimal` reasoning, and [`gpt-4.1-nano`](https://developers.openai.com/api/docs/models/gpt-4.1-nano).171- Web search does not support [`gpt-5`](https://developers.openai.com/api/docs/models/gpt-5) with `minimal` reasoning.

124- When used as a tool in the [Responses API](https://developers.openai.com/api/docs/api-reference/responses), web search has the same tiered rate limits as the models above.172- [`gpt-5.4`](https://developers.openai.com/api/docs/models/gpt-5.4) with reasoning effort set to `none` may produce lower-quality results.

125- Web search is limited to a context window size of 128000 (even with [`gpt-4.1`](https://developers.openai.com/api/docs/models/gpt-4.1) and [`gpt-4.1-mini`](https://developers.openai.com/api/docs/models/gpt-4.1-mini) models).173- Responses API web search uses the underlying model's tiered rate limits.

174- `web_search_preview` does not support `filters` and ignores `external_web_access`.

175- With `tool_choice: "auto"`, search is optional. Use `tool_choice: "required"` or a specific web search tool choice when search must run.

126 176 

127## Usage notes177## Usage notes

128 178