Enable Web Search in the API

Updated November 2, 2026. Based on xAI documentation: with the xai-sdk, web search is enabled via the web_search() function imported from xai_sdk.tools, in a conversation created by client.chat.create; the old example called client.tools.web_search() and client.responses.create, which do not exist in this SDK. Source: Web Search.

Give Grok real-time web access

Web Search is the most used integrated tool in the Grok API. It lets the model search for up-to-date information on the web, bridging the natural limit of its training data. Activation is simple, but there are key points to master to use it effectively.

Prerequisites: The Responses API

Web Search is available exclusively on the Responses API. The old Chat Completions API offered a “Live Search” system that is now deprecated. If you still use Chat Completions for web search, you must migrate to the Responses API.

The Responses API uses client.responses.create() instead of client.chat.completions.create(). The request and response structure differs, but both the xAI SDK and the OpenAI SDK support them.

Basic activation

You enable Web Search by adding a {"type": "web_search"} object to the tools array in your request:

{
  "model": "grok-4.20-0309-reasoning",
  "input": "What are the latest advancements in artificial intelligence?",
  "tools": [
    {"type": "web_search"}
  ]
}

That’s all you need for basic web search. The model automatically determines whether to perform a search and formulates the optimal search query from the user message.

Activation with the xAI SDK (Python)

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

client = Client()

chat = client.chat.create(
    model="grok-4.20-0309-reasoning",
    tools=[web_search()],
)
chat.append(user("What are the latest advancements in AI?"))

response = chat.sample()
print(response.content)
print(response.citations)

The SDK provides the web_search() function, which generates the tool configuration object. It also accepts allowed_domains or excluded_domains—up to five domains, and never both in the same request.

Activation with the OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="xai-your-key",
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest advancements in AI?",
    tools=[{"type": "web_search"}]
)

The OpenAI SDK works with the Grok API by simply changing the base_url. The tool syntax remains identical.

Activation with the Vercel AI SDK

import { xai } from "@ai-sdk/xai";

const response = await generateText({
  model: xai("grok-4.20-0309-reasoning"),
  prompt: "What are the latest advancements in AI?",
  tools: [xai.tools.webSearch()]
});

The Vercel AI SDK uses xai.tools.webSearch() with the JavaScript camelCase convention.

Combine web search with other tools

You can enable multiple tools simultaneously. The model will choose the most appropriate one, or use them sequentially:

{
  "tools": [
    {"type": "web_search"},
    {"type": "code_interpreter"}
  ]
}

In this example, the model can search for data on the web and then analyze it with Code Execution.

Key takeaways

• Web Search is available exclusively on the Responses API—Chat Completions is deprecated for this feature
• Enable it with {"type": "web_search"} in the tools array
• The model automatically decides when and how to search
• All SDKs (xAI, OpenAI, Vercel AI) support Web Search
• You can enable multiple tools simultaneously in the same request