Introduction
# 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: - Current information from websites, news articles, documentation - Real-time data (stock prices, weather, recent events) - Research topics with up-to-date web sources - Finding information from specific websites/domains - Verifying current facts
### Use X Search For: - What people are saying on X/Twitter about a topic - Trending discussions and social sentiment - Real-time reactions to events - Posts from specific X handles/users - Recent social media activity within date ranges
**Do NOT use for:** - Historical facts that won't change - General knowledge already available - Mathematical calculations - Code generation - Creative writing
## Setup
### Required Environment Variables
```bash 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:** - `query` (required): Search query string - `model` (optional): Model to use (default: "grok-4-1-fast-reasoning") - `allowed_domains` (optional): Array of domains to restrict search (max 5) - `excluded_domains` (optional): Array of domains to exclude (max 5) - `enable_image_understanding` (optional): Enable image analysis (default: false)
**Returns:** - `content`: The search response text - `citations`: Array of sources with url, title, and snippet - `usage`: Token usage statistics
### Function: search_x
Search X (Twitter) using xAI's Grok API.
**Parameters:** - `query` (required): Search query string - `model` (optional): Model to use (default: "grok-4-1-fast-reasoning") - `allowed_x_handles` (optional): Array of X handles to search (max 10, without @) - `excluded_x_handles` (optional): Array of X handles to exclude (max 10, without @) - `from_date` (optional): Start date in ISO8601 format (YYYY-MM-DD) - `to_date` (optional): End date in ISO8601 format (YYYY-MM-DD) - `enable_image_understanding` (optional): Enable image analysis (default: false) - `enable_video_understanding` (optional): Enable video analysis (default: false)
**Returns:** - `content`: The search response text - `citations`: Array of X posts with url, title, and snippet - `usage`: Token usage statistics
## Implementation
This skill uses the xAI Responses API (`/v1/responses` endpoint).
### Web Search
```javascript 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
```javascript 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 ```javascript const result = await search_web({ query: "latest AI regulation developments" }); ```
### Web Search - Specific Domains ```javascript const result = await search_web({ query: "UN climate summit latest", allowed_domains: ["un.org", "gov.uk", "grokipedia.com"] }); ```
### X Search - Social Sentiment ```javascript const result = await search_x({ query: "new iPhone reactions opinions" }); ```
### X Search - Specific Handles ```javascript const result = await search_x({ query: "AI thoughts", allowed_x_handles: ["elonmusk", "cstanley"], from_date: "2025-01-01" }); ```
### X Search - With Media ```javascript const result = await search_x({ query: "Mars landing images", enable_image_understanding: true, enable_video_understanding: true }); ```
## Best Practices
### Web Search - Use `allowed_domains` to limit to specific domains (max 5) - Use `excluded_domains` for known bad sources (max 5) - Cannot use both at same time - Enable image understanding only when needed
### X Search - Use `allowed_x_handles` to focus on specific accounts (max 10) - Use `excluded_x_handles` to filter noise (max 10) - Cannot use both at same time - Don't include @ symbol in handles - Use ISO8601 date format: YYYY-MM-DD - Media understanding adds API costs
## Troubleshooting
### "XAI_API_KEY not found" ```bash export XAI_API_KEY="your-key-here" ```
### Rate Limiting - Implement exponential backoff - Cache frequent queries
### Poor Results - Add domain/handle filters - Make queries more specific - Narrow date ranges
### 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
- Web Search: https://docs.x.ai/developers/tools/web-search - X Search: https://docs.x.ai/developers/tools/x-search