Research — Grok Web + X Search

How It Works

Uses xAI's Responses API (/v1/responses) with built-in tools (web_search, x_search) for real-time research. This is NOT the chat completions endpoint — that has no search capability.

API Key

Store your xAI API key at ~/.config/xai/api_key.

XAI_KEY=$(cat ~/.config/xai/api_key)

Basic Research Query

XAI_KEY=$(cat ~/.config/xai/api_key)

curl -s https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "input": "YOUR RESEARCH QUERY HERE",
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
  }' | python3 -c "
import sys, json
data = json.load(sys.stdin)
for item in data.get('output', []):
    if item.get('type') == 'message':
        for c in item.get('content', []):
            if c.get('type') == 'output_text':
                print(c['text'])
            for ann in c.get('annotations', []):
                if ann.get('url'):
                    print(f'  [{ann[\"url\"]}]')
"

Tool Options

Both can be used together: "tools": [{"type": "web_search"}, {"type": "x_search"}]

Web Search Parameters

{"type": "web_search", "allowed_domains": ["example.com"]}
{"type": "web_search", "excluded_domains": ["reddit.com"]}

Model Requirements

• Only grok-4 family models support server-side tools
• Use grok-4.3 for reasoning workloads (current default; 1M ctx, $1.25/$2.50 per 1M in/out, 3 reasoning efforts)
• Use grok-4.20-0309-non-reasoning for fast non-reasoning workloads
• Pre-grok-4.3 fast variants (grok-4-1-fast-*, grok-4-fast-*) and grok-3 are deprecated and retire 2026-05-15 12:00 PT — do not use
• Older non-grok-4 models do NOT support tools

Important Notes

• The /chat/completions endpoint does NOT support web search — only /responses does
• Responses can take 30-90 seconds for complex queries
• Always use yieldMs: 90000 and timeout: 120 for exec calls

Parsing the Response

The response output array contains:

• web_search_call items (searches performed)
• x_search_call items (X searches performed)
• message items with content[].output_text (the final answer)
• Annotations with citation URLs

When to Use

• Finding media appearances, podcast episodes, interviews
• Researching people, companies, events
• Checking recent news or social media discussion
• X/Twitter sentiment or discussion analysis

When NOT to Use

• Simple factual questions (use regular chat)
• Code generation or analysis
• Tasks that don't need web data