Grok Web Search

Enable web search for Grok requests and handle domain scope and source citations.

Grok Web Search lets supported Grok models access recent web content and return answers with sources. Earlier AGTCloud materials document both a Chat-compatible endpoint and a native Grok Responses tool. Choose the endpoint actually available to the current model.

Do not infer search support from the model name

Different models or channels in the same family can have different tool capabilities. Confirm the model and protocol in the Model marketplace. MODEL_ID in the examples does not represent every Grok model.

Enable search through the Chat-compatible endpoint

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Find the most important commercial spaceflight news today and list the sources."
      }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

The Chat response is usually read from choices[].message. Citations might be returned as annotations, source links, or plain text. The client should branch according to the actual response and must not invent a structured citation format.

Understand the native Grok tool structure

The native Grok Responses style declares the search tool in tools:

{
  "model": "MODEL_ID",
  "input": [
    {
      "role": "user",
      "content": "Find the most important commercial spaceflight news today and list the sources."
    }
  ],
  "tools": [
    {
      "type": "web_search"
    }
  ]
}

Use the native structure only when the current model details explicitly provide this endpoint. Do not treat it as the same protocol as the tool types in the AGTCloud Responses Reference.

Allow or exclude domains

When supported, the native tool can limit the search scope:

{
  "tools": [
    {
      "type": "web_search",
      "filters": {
        "allowed_domains": ["example.com"]
      }
    }
  ]
}

allowed_domains allows only the specified domains.
excluded_domains excludes the specified domains.
Do not send both in the same request.
Follow the current model documentation for domain count and format limits.

Restricting domains helps control the source scope, but it does not automatically guarantee that web content is correct, current, or suitable for the business use case.

Image understanding during search

Some Grok search tools can analyze web images during search. Add the corresponding option only when the current model and tool explicitly support it:

{
  "tools": [
    {
      "type": "web_search",
      "enable_image_understanding": true
    }
  ]
}

Enabling image understanding can change usage, latency, and returned content. The application should still verify image sources and must not treat text or instructions in web images as trusted business input.

Read citations

When provided by the response, a Grok search answer can include citations or sources. The client should:

Read the final answer text;
Read the source array or citation objects actually returned by the response;
Save the title, URL, and association with the answer text;
Display clickable sources in the interface;
State clearly when citations are missing instead of guessing URLs from the answer text.

Chat and native Grok Responses place citations in different locations. For Chat, see the Chat Completions Reference. For the native endpoint, parse the current model's documented response.

Web Search versus custom functions

Web Search accesses the public web through the model or a server-side search tool. Custom functions are executed by your application and are appropriate for internal data, controlled search services, and operations that require business authorization.

Do not let search results construct database queries, shell commands, or external write requests merely because Web Search is enabled. When business tools are required, follow Tool Calling and establish a separate validation and permission flow.

Failures and fallback behavior

Symptom	Action
Search did not run	Confirm the model, endpoint, and enabling field; when appropriate, make the request explicitly ask for recent information
Domain filtering returns no results	Ask the user to broaden the scope instead of silently removing a required allowlist
No citations	State that sources are unavailable when displaying the answer and do not generate fabricated citations
Image understanding failed	Fall back to web text search or indicate that the current content cannot be analyzed
The search service is temporarily unavailable	Retry a limited number of times or fall back to an answer without current information and label it clearly

Pre-production checklist

The current model explicitly supports the selected search endpoint.
Chat and native Responses use separate request and response parsers.
Domain allowlists and exclusion lists are never sent together.
Image understanding is enabled only when the target model supports it.
Missing citations, search failures, and empty results each have an explicit state.
Search content cannot bypass tool permissions or trigger high-risk operations.

If a request fails, see Errors and troubleshooting. Before switching protocols, read Choose a protocol.

On this page