Tools

Web Search

The Web Search tool enables Grok to search the web in real-time and browse web pages to find information. This powerful tool allows the model to search the internet, access web pages, and extract relevant information to answer queries with up-to-date content.

SDK Support

SDK/API	Tool Name
xAI SDK	`web_search`
OpenAI Responses API	`web_search`
Vercel AI SDK	`xai.tools.webSearch()`

This tool is also supported in all Responses API compatible SDKs.

Basic Usage

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4-1-fast-reasoning",  # reasoning model
    tools=[web_search()],
    include=["verbose_streaming"],
)

chat.append(user("What is xAI?"))

is_thinking = True
for response, chunk in chat.stream():
    for tool_call in chunk.tool_calls:
        print(f"\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")
    if response.usage.reasoning_tokens and is_thinking:
        print(f"\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)
    if chunk.content and is_thinking:
        print("\n\nFinal Response:")
        is_thinking = False
    if chunk.content and not is_thinking:
        print(chunk.content, end="", flush=True)

print("\n\nCitations:")
print(response.citations)

Web Search Parameters

Parameter	Description
`allowed_domains`	Only search within specific domains (max 5)
`excluded_domains`	Exclude specific domains from search (max 5)
`enable_image_understanding`	Enable analysis of images found during browsing

Only Search in Specific Domains

Use allowed_domains to make the web search only perform the search and web browsing on web pages that fall within the specified domains.

allowed_domains cannot be set together with excluded_domains in the same request.

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4-1-fast-reasoning",
    tools=[
        web_search(allowed_domains=["wikipedia.org"]),
    ],
)

chat.append(user("What is xAI?"))
# stream or sample the response...

Exclude Specific Domains

Use excluded_domains to prevent the model from including the specified domains in any web search tool invocations.

chat = client.chat.create(
    model="grok-4-1-fast-reasoning",
    tools=[
        web_search(excluded_domains=["wikipedia.org"]),
    ],
)

Enable Image Understanding

Setting enable_image_understanding to true equips the agent with access to the view_image tool, allowing it to analyze images encountered during the search process.

When enabled, you will see SERVER_SIDE_TOOL_VIEW_IMAGE in response.server_side_tool_usage along with the number of times it was called.

Enabling this parameter for Web Search will also enable the image understanding for X Search tool if it's also included in the request.

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import web_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4-1-fast-reasoning",
    tools=[
        web_search(enable_image_understanding=True),
    ],
)

chat.append(user("What is included in the image in xAI's official website?"))
# stream or sample the response...

Citations

For details on how to retrieve and use citations from search results, see the Citations page.