Enable Web Search in the Grok API

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

Updated November 3, 2026. The first example called client.responses.create() on the xai-sdk client, which has no responses attribute: with this SDK, search goes through client.chat.create(..., tools=[web_search()]), and client.responses.create() belongs to the openai SDK pointed at https://api.x.ai/v1. The Vercel AI SDK example passed tools as an array and did not import generateText: they declare in an object, as in xAI documentation. Code verified with xai-sdk 1.21.0 and openai 3.42.1. Source: Web Search.

Why Connect Grok to the Real-Time Web

Classic language models work with knowledge frozen at their training date. For a developer building applications that require current data (stock prices, news, sports results, weather), this limitation is a dealbreaker. The web_search tool in the Grok API solves this problem by letting the model query the web in real time, directly from your API call.

Unlike other providers that require third-party integrations or separate plugins, xAI offers web search as a server-side built-in tool. You have no infrastructure to manage: the model decides when to search, executes the query, and integrates the results into its response.

The Responses API: The Only Supported Endpoint

Web search works exclusively on the Responses API. The old Chat Completions endpoint offered a search_parameters parameter, but it is now deprecated. If you are migrating from the old API, you will need to adapt your calls.

Activation happens by adding the web_search tool to the tools array in your request:

import os

from openai import OpenAI

client = OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1")

response = client.responses.create(
    model="grok-4.5",
    input="What is the weather like in Paris today?",
    tools=[{"type": "web_search"}],
)

print(response.output_text)

This example uses the openai SDK, compatible with the xAI Responses API; the native xAI SDK, presented below, goes through a conversation.

That’s it. The model analyzes your prompt, determines if it needs fresh information, and triggers the search automatically. You do not have to manage a call loop or conditional logic.

The Five-Step Execution Flow

When you send a request with web_search enabled, the process follows a specific sequence:

1. Analysis: the model evaluates whether the question requires recent data
2. Decision: it chooses to search or answer with its internal knowledge
3. Execution: web search runs server-side (you manage nothing)
4. Processing: results are analyzed and synthesized
5. Response: final text is generated with associated citations

This mechanism means the model can decide not to search if the question does not justify it. For example, asking for the definition of photosynthesis will probably not trigger a web search.

Usage with Different SDKs

The xAI SDK provides a dedicated function, web_search(), to pass into the conversation tools list:

# Native xAI SDK
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.5", tools=[web_search()])
chat.append(user("Latest AI news in Europe"))

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

With the openai SDK, it is the call from the start of the lesson: client.responses.create() with base_url="https://api.x.ai/v1" and tools=[{"type": "web_search"}].

For the Vercel AI SDK in JavaScript:

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: xai.responses('grok-4.5'),
  prompt: "Latest AI news in Europe",
  tools: {
    web_search: xai.tools.webSearch(),
  },
});

console.log(text);
console.log('Citations:', sources);

Hands-On Practice

Create a script that queries Grok on a current event of your choice. Verify that the response contains recent information (dates, events occurring after the model cutoff date). Then try the same question without the web_search tool to see the difference.

Key Takeaways

• Web search activates with {"type": "web_search"} in tools (openai SDK, Responses API) or web_search() in client.chat.create (xai-sdk)
• It works only on the Responses API (not Chat Completions)
• The model autonomously decides when it needs to search
• Citations are automatically included in the response
• Cost is $5 per 1,000 tool calls, plus consumed tokens