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  |
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).