Skip to main content

​
Prerequisites

Before starting, ensure you’ve completed the installation steps and have:
  • ✅ Node.js 18+ installed
  • ✅ xAI API key configured
  • ✅ Claude Desktop setup with Grok Search server
  • ✅ Server health check passing
Let’s start with a simple web search using basic mode.
1

Open Claude Desktop

Launch Claude Desktop and ensure the Grok Search tools are available.
2

Run a basic search

Try this simple search:
{
  "tool": "grok_search",
  "parameters": {
    "query": "latest AI developments",
    "search_type": "web",
    "max_results": 5
  }
}
3

Review results

You’ll receive structured results with titles, snippets, URLs, and citations.
Start with max_results of 3-5 for faster responses and to understand the result format.

​
Understanding the response

A basic search returns structured JSON data: 
{
  "query": "latest AI developments",
  "analysis_mode": "basic",
  "results": [
    {
      "title": "Article Title",
      "snippet": "Brief summary of the content...",
      "url": "https://example.com/article",
      "source": "example.com",
      "published_date": "2025-03-04",
      "citation_url": "https://example.com/article",
      "citation_metadata": {
        "domain": "example.com",
        "is_secure": true
      }
    }
  ],
  "summary": "Brief overview of findings",
  "total_results": 5,
  "search_time": "2025-03-04T12:00:00.000Z",
  "source": "grok-live-search"
}

results

Array of search results with title, snippet, URL, and metadata

summary

AI-generated overview of the search findings

citations

Source URLs with validation and metadata

search_time

ISO8601 timestamp of when the search was performed

​
Common search patterns

Search general web content: 
{
  "tool": "grok_web_search",
  "parameters": {
    "query": "quantum computing basics",
    "max_results": 5
  }
}
Search for recent news and current events: 
{
  "tool": "grok_news_search",
  "parameters": {
    "query": "technology industry news",
    "max_results": 5
  }
}
Search social media posts: 
{
  "tool": "grok_twitter",
  "parameters": {
    "query": "artificial intelligence trends",
    "max_results": 10
  }
}
Twitter handles should be provided without the @ symbol. Use "elonmusk" not "@elonmusk".

​
Comprehensive analysis mode

For detailed analysis with timelines, quotes, and multiple perspectives, use comprehensive mode: 
{
  "tool": "grok_news_search",
  "parameters": {
    "query": "US economic policy 2025",
    "analysis_mode": "comprehensive",
    "max_results": 10,
    "from_date": "2025-01-01"
  }
}

​
Comprehensive response structure

A detailed 500+ word analysis providing deep context, background, and implications with specific details, dates, and numbers.
Array of categorized findings (main_story, development, context, impact) with content, sources, and confidence levels.
Chronological events with dates, descriptions, sources, and significance explanations.
Exact quotes with speaker attribution, context, source URLs, and significance.
Different viewpoints (supporters, critics, experts) with content, sources, and reasoning.
Short-term and long-term consequences with affected stakeholders.
Confirmed facts, unconfirmed claims, and contradictory information tracking.
Comprehensive mode uses more API tokens (~4000 vs ~2000 for basic) and takes longer to process. Use it when you need detailed analysis, not for simple queries.

​
Date filtering

All search tools support date range filtering using ISO8601 format: 
{
  "tool": "grok_search",
  "parameters": {
    "query": "space exploration missions",
    "search_type": "news",
    "from_date": "2025-02-01",
    "to_date": "2025-03-04",
    "max_results": 10
  }
}

​
Date format requirements

Format

YYYY-MM-DD (ISO8601)

Example

2025-03-04 ✓

Invalid

03/04/2025 ✗

Rule

from_date ≤ to_date

​
Health check

Monitor server status and performance: 
{
  "tool": "health_check",
  "parameters": {}
}
Response: 
{
  "server_healthy": true,
  "api_healthy": true,
  "uptime_ms": 3600000,
  "total_requests": 150,
  "error_count": 3,
  "success_rate": "98.00%",
  "api_details": {
    "hasApiKey": true,
    "cacheSize": 12,
    "lastError": null
  }
}
Run health checks regularly to monitor server performance and diagnose issues early.

​
Best practices

​
Query optimization

1

Be specific

Use clear, specific queries rather than vague terms.✓ “SpaceX Starship launch March 2025”✗ “rocket news”
2

Choose the right search type

  • web: General information, articles, guides
  • news: Current events, breaking news
  • twitter: Social media sentiment, influencer opinions
3

Use date filters wisely

For time-sensitive topics, use date ranges to narrow results to relevant time periods.
4

Start with basic mode

Test queries in basic mode first, then use comprehensive for detailed analysis when needed.

​
Performance optimization

Limit results

Use 5-10 results for most queries. More results = longer processing time.

Basic vs comprehensive

Basic mode: Fast, 2000 tokensComprehensive: Slow, 4000 tokens

Caching

Comprehensive analyses are cached for 30 minutes to reduce API usage.

Date ranges

Narrow date ranges return more focused, relevant results faster.

​
Example workflows

​
Research workflow

1

Initial broad search

{
  "tool": "grok_web_search",
  "parameters": {
    "query": "renewable energy technologies",
    "max_results": 5
  }
}
2

Deep dive with comprehensive analysis

{
  "tool": "grok_web_search",
  "parameters": {
    "query": "solar panel efficiency breakthroughs 2025",
    "analysis_mode": "comprehensive",
    "from_date": "2025-01-01",
    "max_results": 10
  }
}
3

Check social sentiment

{
  "tool": "grok_twitter",
  "parameters": {
    "query": "solar energy adoption",
    "max_results": 10
  }
}

​
News monitoring workflow

1

Recent headlines

{
  "tool": "grok_news_search",
  "parameters": {
    "query": "tech industry layoffs",
    "from_date": "2025-03-01",
    "max_results": 5
  }
}
2

Comprehensive timeline

{
  "tool": "grok_news_search",
  "parameters": {
    "query": "tech industry layoffs 2025",
    "analysis_mode": "comprehensive",
    "from_date": "2025-01-01",
    "max_results": 15
  }
}

​
Common issues and solutions

Try these solutions:
  1. Rephrase your query to be more specific
  2. Try a different search type (web vs news vs twitter)
  3. Expand your date range or remove date filters
  4. Check if the topic has sufficient online coverage
  5. Use basic mode if comprehensive mode returns limited results
Solutions:
  1. Reduce max_results parameter
  2. Use basic mode instead of comprehensive
  3. Increase GROK_TIMEOUT in configuration
  4. Check your internet connection
  5. Verify API service status with health_check
Verify:
  1. API key starts with xai-
  2. No extra spaces or quotes in configuration
  3. Key is active in xAI Developer Portal
  4. Environment variable name is exactly XAI_API_KEY
Run health_check to diagnose API connectivity.
Requirements:
  • Format: YYYY-MM-DD exactly
  • Valid dates only (no 2025-02-30)
  • from_date must be ≤ to_date
Examples:✓ "2025-03-04"✗ "03/04/2025", "2025-3-4", "2025-02-30"

​
Next steps

API reference

Explore detailed documentation for all tools and parameters

Analysis modes

Learn about basic and comprehensive analysis modes

Configuration

Learn about advanced configuration options

Error handling

Get help with common issues and error messages
For questions or issues, visit the GitHub repository to create an issue.

Build docs developers (and LLMs) love

Get started for freeTalk to us