Grok Web Search

Grok models support real-time access to the internet via the Web Search tool, searching web pages and extracting key information to provide answers with the latest content.

Key Notes: - Our Platform Gateway uniformly adopts the /v1/chat/completions endpoint compatible with OpenAI specifications, triggering the networking capabilities of various models (including Grok) via the web_search_options field. - xAI Official declares the type: "web_search" tool via their proprietary /v1/responses interface.

Below, we will compare our platform's unified calling method with the xAI official calling method.

---

Quick Start

Our Platform Example (New API Platform)

On this platform, whether you are calling GPT, Gemini, or Grok, you only need to send a request to the /v1/chat/completions endpoint and add the web_search_options field in the request body to enable the networking function.

curl https://api-cs-al.naci-tech.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "grok-4-1-fast-reasoning",
    "messages": [
      { "role": "user", "content": "What is the weather in Beijing tomorrow?" }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

• web_search_options: The flag to enable web search. The currently supported configuration items (like search_context_size which controls search context volume) are completely consistent with the networking mechanisms of other models on the platform.

xAI Official Example (Native API)

If you are connecting directly to the xAI official API, you need to declare the native web_search tool through the tools array in their /v1/responses interface:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4-1-fast-reasoning",
  "input": [
    {
      "role": "user",
      "content": "What is xAI?"
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}'

---

xAI Official Advanced Features

Although you can easily solve the problem using web_search_options on our site, understanding the official native capabilities will help you grasp the potential of Grok Web Search.

According to xAI's official documentation, the native Web Search tool supports the following common parameters (passed via tools[].filters or tool properties):

Parameter	Description
allowed_domains	Only search within specified domains (up to 5)
excluded_domains	Exclude specified domains from the search (up to 5)
enable_image_understanding	Enable image understanding to analyze images encountered during the search

Search only specific domains (allowed_domains)

xAI Official Example:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4-1-fast-reasoning",
  "input": [
    { "role": "user", "content": "What is xAI?" }
  ],
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": ["grokipedia.com"]
      }
    }
  ]
}'

Note: allowed_domains and excluded_domains cannot be set at the same time.

Enable Image Understanding (enable_image_understanding)

Setting enable_image_understanding: true allows the agent to call internal tools like view_image during the search to extract and understand image content from web pages.

xAI Official Example:

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4-1-fast-reasoning",
  "input": [
    {
      "role": "user",
      "content": "What is included in the image in xAI'\''s official website?"
    }
  ],
  "tools": [
    {
      "type": "web_search",
      "enable_image_understanding": true
    }
  ]
}'

---

Citations

Grok Web Search will generate answers with citations based on the search results. In the xAI official Responses API, you can view the citation details via the response.citations or the sources field returned by the SDK (see official documentation Citations).

When calling on this platform using /v1/chat/completions, the gateway processes this in the background and returns the organized results directly as plain text concatenation, or through a compatible Citation format, consistent with the behavior of other models.

---

Appendix: Function Calling

In addition to the Web Search tool, you can also define your own business tools for Grok; our platform uniformly supports the OpenAI Function Calling format. For example:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_user_info",
        "description": "Get user information",
        "parameters": {
          "type": "object",
          "properties": {
            "user_id": { "type": "string" }
          },
          "required": ["user_id"]
        }
      }
    }
  ]
}

For more general instructions on tool calls, please refer to the tools overview document in this directory: index.md.