# Web search (`web_search`, `web_search_2025_08_26`, legacy `web_search_preview`, `web_search_preview_2025_03_11`)

Status: web_search DOCUMENTED · LIVE_VERIFIED (2026-09-18, gpt-5.4-nano) · web_search_preview* DOCUMENTED · LEGACY · web_search_2025_08_26 DOCUMENTED (alias, not called) Sources: https://developers.openai.com/api/docs/guides/tools-web-search · https://developers.openai.com/api/docs/pricing#built-in-tools · openapi-master.yaml WebSearchTool, WebSearchPreviewTool, WebSearchToolCall, WebSearchActionSearch|OpenPage|Find, IncludeEnum Last verified: 2026-09-18

# Parameters (`tools[]` entry)

Parameter	Type / enum	Default	In spec	Notes
`type`	`web_search` \| `web_search_2025_08_26`		yes	preview variants: `web_search_preview` \| `web_search_preview_2025_03_11`
`search_context_size`	`low` \| `medium` \| `high`	`medium`	yes	context budget for results; search context window capped at 128k regardless of model
`user_location`	`{type:"approximate", country (ISO-2), region, city, timezone (IANA)}`	null	yes	not supported for deep research models
`filters.allowed_domains`	string[] (≤ 100)	[]	yes	subdomains included; no scheme
`filters.blocked_domains`	string[] (≤ 100)		guide only	not in OpenAPI spec
`external_web_access`	boolean	`true`	yes	`false` = cache-only mode; ignored by preview
`return_token_budget`	`default` \| `unlimited`	`default`	guide only	echoed live in `response.tools[0]`; GPT-5+ reasoning web search only
`search_content_types`	`["text","image"]`	`["text"]` (echoed live)	preview only in spec	image search; result fields `max_results`, `caption`, `thumbnail_url` (guide)

Chat Completions: no web_search tool — use search models (gpt-5-search-api; gpt-4o-search-preview/gpt-4o-mini-search-preview deprecated, shutdown 2026-07-23) with web_search_options {user_location, search_context_size}.

# Output

Item web_search_call {id:"ws_…", type, status: in_progress|searching|completed|failed|incomplete, action} where action is:

{type:"search", query, queries[], sources[]} — sources only with include:["web_search_call.action.sources"]. Spec: sources[].type = "url", url. Live: {"type":"api","name":"oai-time"} (no url) — third-party feeds oai-time, oai-weather, oai-sports, oai-finance are surfaced here; the Python SDK 3.16.2 emits pydantic serialization warnings for this shape.
{type:"open_page", url} and {type:"find_in_page", url, pattern} — reasoning models. Message annotations: url_citation {url, title, start_index, end_index} (none in our date query, whose only source was the oai-time API).

# `tool_choice`

"auto": search is optional — live, gpt-5.4-nano answered the date question without searching.
{"type":"web_search"}: accepted live and forces a search; the response echoes tool_choice: {"type":"web_search_preview"} (spec ToolChoiceTypes only lists web_search_preview, web_search_preview_2025_03_11). "required" also works.

# Billing (pricing page, cited)

web_search (all models) and image web search: $10.00 / 1k calls + search content tokens at model rates. web_search_preview: $10/1k on reasoning models; $25/1k with free content tokens on non-reasoning models. Rate limits = the model's tiered limits.

# Limits (docs)

Not supported with gpt-5 minimal reasoning; gpt-5.4 with reasoning none may degrade; 128k search context even on 1M models (gpt-4.1*); o4-mini deprecated (shutdown 2026-10-23); preview ignores external_web_access and lacks filters/return_token_budget; use background: true for long research runs.

# Live evidence

Probe	Status	Result
`max_output_tokens: 64`, auto	200	`status: incomplete` (max_output_tokens) before any tool call — budget ≥ 300 tokens
`max_output_tokens: 600`, auto (stream)	200	no search; answer from `oai-time`-less reasoning; tools echo shows `return_token_budget`, `search_content_types`
forced `{"type":"web_search"}` (stream)	200	events `web_search_call.in_progress → searching → completed`; action `search`, `queries: ["time: {\"utc_offset\":\"-04:00\"}"]`, `sources: [{type:"api", name:"oai-time"}]`; usage 4671 in (3584 cached) / 329 out
sh/py/ts examples	200	same shape; answers "September 18/19, 2026" (UTC vs Toronto)

Examples: examples/openai/tools/web-search/. Test (expensive): test_web_search_forced. Deep research variant: deep-research.

# Web search (web_search, web_search_2025_08_26, legacy web_search_preview, web_search_preview_2025_03_11)

# Parameters (tools[] entry)