# 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](deep-research.md).