# xAI Web Search tool (`type: "web_search"`)

**Status:** DOCUMENTED · LIVE_VERIFIED (2026-09-19, grok-4.3: `web_search_call` with `action.open_page` on https://x.ai/news, `web_search_calls: 1`, `url_citation` annotation; a first "today's date" prompt was answered without any search call)
**Sources:** https://docs.x.ai/developers/tools/web-search · https://docs.x.ai/developers/tools/citations · https://docs.x.ai/developers/tools/tool-usage-details · https://docs.x.ai/developers/pricing#tools-pricing · OpenAPI `ModelTool` (web_search variant), `WebSearchCall`, `WebSearchAction`, `WebSearchFilters`
**Last verified:** 2026-09-19

## Parameters (`tools[]` entry, Responses only)
| Field | Type | Notes |
|---|---|---|
| `type` | `"web_search"` | Chat Completions rejects it (422) |
| `allowed_domains` | string[] ≤5 | whitelist; exclusive with `excluded_domains`; also accepted nested as `filters.allowed_domains` (OpenAI shape, echoed live) |
| `excluded_domains` | string[] ≤5 | blacklist |
| `enable_image_understanding` | bool | grants `view_image` (also enables it for x_search in the same request) |
| `enable_image_search` | bool | `search_images` sub-tool; results embedded as `![alt](url)` |
| `search_context_size`, `user_location`, `external_web_access` | OpenAI compat | **request rejected 400 "Argument not supported: search_context_size"** if set; response echoes `search_context_size:"medium"` regardless |

Server sub-tools: `web_search`, `web_search_with_snippets`, `browse_page`, `open_page`, `open_page_with_find` (+ `search_images`, `view_image`).

## Output
Item `{"type":"web_search_call","id":"ws_<resp>_call-…","status":"completed","action":{"type":"open_page","url":"https://x.ai/news"}}`; other actions `{"type":"search","query","sources":[{type,url}]}` (sources only with `include:["web_search_call.action.sources"]`) and `{"type":"find_in_page","url","pattern"}`. Final message `content[0].annotations[] = [{"type":"url_citation","url":"https://x.ai/news","start_index":0,"end_index":0,"title":"https://x.ai/news"}]` — live indices were 0/0 and `title` = URL (docs: char offsets + display number); inline `[[N]](url)` markdown is on by default (`include:["no_inline_citations"]` to disable). Usage: `num_server_side_tools_used`, `server_side_tool_usage_details.web_search_calls`; live 7 467 input tokens (704 cached), 411 reasoning, cost ticks 146 845 500 ≈ $0.0147 incl. the $0.005 call.

## Billing / limits
$5 per 1k successful calls + tokens. Image search billed as web search; `view_image` billed as image tokens. The model decides whether to search — prompt explicitly ("Use the web_search tool…") to force it. `max_turns` caps the loop.

Examples: `examples/xai/tools/web-search/`. Test: `tests/xai/test_tools.py::test_web_search_tool` (RUN_EXPENSIVE_TESTS).