xAI Grok Search

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

Security Scan

The skill's code and instructions implement a Grok-based web/X search and only need an XAI API key, but registry metadata and repository information are inconsistent and the published source is unclear — verify origin before installing.

Purpose & Capability

The name, description, SKILL.md, and search.mjs all consistently implement web and X (Twitter) searches via xAI's Responses API and require an XAI_API_KEY — that capability request is coherent with the claimed purpose. However, the registry metadata shown at the top states "Required env vars: none" while the SKILL.md and code both require XAI_API_KEY. The homepage field is a generic placeholder (github.com/yourusername/...), and the source is listed as unknown, which is inconsistent with the claimed author/owner and reduces trust in provenance.

Instruction Scope

SKILL.md and the included search.mjs confine runtime behavior to sending POSTs to https://api.x.ai/v1/responses with tools of type 'web_search' or 'x_search'. They only reference process.env.XAI_API_KEY and do not read arbitrary system files, other env vars, or send data to unexpected endpoints. The skill returns raw_response and server_side_tool_usage which may expose additional API-returned metadata but that is consistent with a search tool.

Install Mechanism

There is no install spec (instruction-only) and the code file is bundled directly. This minimizes installer risk — nothing is downloaded from external arbitrary URLs and no archives are extracted. The skill will run the included JS when invoked.

Credentials

The only runtime secret required by the code is XAI_API_KEY, which is proportionate for a third-party Grok API integration. However the registry metadata omitted this required env var, which is an inconsistency that could confuse users and automated installers. Ensure the API key is scoped and rotated appropriately; do not reuse high-privilege or long-lived keys.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide settings. It does not claim persistent privileges beyond using the provided API key at runtime.

What to consider before installing

What to consider before installing: - Provenance: The package's registry metadata and homepage are inconsistent/placeholder and the source author is 'unknown' — verify the repository and publisher (look for a real GitHub repo, commit history, and a trustworthy owner) before trusting the code or API key. - Required secret: The code requires XAI_API_KEY. Only provide a properly scoped, minimal-privilege API key. Do not reuse credentials that grant access to other services. - Data flow: Queries and any user-provided text/images will be sent to api.x.ai. If users will submit sensitive material, check x.ai's privacy policy and how the API handles retained data. - Returned metadata: The skill returns raw_response and server_side_tool_usage fields; review what those contain in practice to avoid unintentionally exposing internal metadata to end users. - Quick checks to perform: review the repository for additional files, ensure no hidden endpoints or obfuscated code exist, run the code with a test API key in a sandbox, and confirm the endpoint is the official x.ai domain (https://api.x.ai). If anything about the repo or publisher looks incomplete or wrong, prefer not to install until provenance is clarified. - If you want higher assurance: ask the publisher for a canonical repo URL and signed release, or request that the registry metadata be corrected to declare the XAI_API_KEY dependency explicitly.

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

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

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

• 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"

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