xAI Grok Search

---

name: xai-grok-search

version: 1.0.3

description: Search the web and X (Twitter) using xAI's Grok API with real-time access, citations, and image understanding

homepage: https://github.com/yourusername/xai-grok-search

metadata:

category: search

api_base: https://api.x.ai/v1

capabilities:

- api

- web-search

- x-search

dependencies: []

interface: REST

openclaw:

emoji: "🔍"

install:

env:

- XAI_API_KEY

author:

name: Christopher Stanley

---

# xAI Grok Search

Search the web and X (Twitter) using xAI's Grok API with real-time internet access, citations, and optional image/video understanding.

When to Use This Skill

Use Web Search For:

Use X Search For:

**Do NOT use for:**

Setup

Required Environment Variables

export XAI_API_KEY="your-xai-api-key-here"

Get your API key from: https://console.x.ai/

Usage

The agent will automatically choose the right tool based on the user's query:

**User:** "What's the latest news about AI regulation?"

→ Uses `web_search`

**User:** "What are people saying about OpenAI on X?"

→ Uses `x_search`

API Reference

Function: search_web

Search the web using xAI's Grok API.

**Parameters:**

**Returns:**

Function: search_x

Search X (Twitter) using xAI's Grok API.

**Parameters:**

**Returns:**

Implementation

This skill uses the xAI Responses API (`/v1/responses` endpoint).

Web Search

async function search_web(options) {
  const { query, model = 'grok-4-1-fast-reasoning', 
          allowed_domains, excluded_domains, enable_image_understanding } = options;

  const tool = { type: 'web_search' };
  if (allowed_domains) tool.allowed_domains = allowed_domains;
  if (excluded_domains) tool.excluded_domains = excluded_domains;
  if (enable_image_understanding) tool.enable_image_understanding = true;

  const response = await fetch('https://api.x.ai/v1/responses', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.XAI_API_KEY}`
    },
    body: JSON.stringify({
      model,
      input: [{ role: 'user', content: query }],
      tools: [tool]
    })
  });

  const data = await response.json();
  return { 
    content: data.output[data.output.length - 1].content,
    citations: data.citations 
  };
}

X Search

async function search_x(options) {
  const { query, model = 'grok-4-1-fast-reasoning',
          allowed_x_handles, excluded_x_handles, from_date, to_date,
          enable_image_understanding, enable_video_understanding } = options;

  const tool = { type: 'x_search' };
  if (allowed_x_handles) tool.allowed_x_handles = allowed_x_handles;
  if (excluded_x_handles) tool.excluded_x_handles = excluded_x_handles;
  if (from_date) tool.from_date = from_date;
  if (to_date) tool.to_date = to_date;
  if (enable_image_understanding) tool.enable_image_understanding = true;
  if (enable_video_understanding) tool.enable_video_understanding = true;

  const response = await fetch('https://api.x.ai/v1/responses', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.XAI_API_KEY}`
    },
    body: JSON.stringify({
      model,
      input: [{ role: 'user', content: query }],
      tools: [tool]
    })
  });

  const data = await response.json();
  return { 
    content: data.output[data.output.length - 1].content,
    citations: data.citations 
  };
}

Examples

Web Search - Current Events

const result = await search_web({ 
  query: "latest AI regulation developments" 
});

Web Search - Specific Domains

const result = await search_web({
  query: "UN climate summit latest",
  allowed_domains: ["un.org", "gov.uk", "grokipedia.com"]
});

X Search - Social Sentiment

const result = await search_x({
  query: "new iPhone reactions opinions"
});

X Search - Specific Handles

const result = await search_x({
  query: "AI thoughts",
  allowed_x_handles: ["elonmusk", "cstanley"],
  from_date: "2025-01-01"
});

X Search - With Media

const result = await search_x({
  query: "Mars landing images",
  enable_image_understanding: true,
  enable_video_understanding: true
});

Best Practices

Web Search

X Search

Troubleshooting

"XAI_API_KEY not found"

export XAI_API_KEY="your-key-here"

Rate Limiting

Poor Results

Slow Responses

Search queries using reasoning models (e.g. `grok-4-1-fast-reasoning`) can take 30-60+ seconds to return, especially when the model performs multiple web or X searches. If the search is lagging, inform the user that results are still loading and ask them to type **"poll"** to check for the completed response.

API Documentation