Back to Details

x-research

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

X Research (xAI/Grok)

X调研工具（xAI/Grok）

AI-powered research using xAI's Grok API. Returns AI summaries with citations, not raw tweet data.
Want raw tweets instead? Use these skills:
  • x-user-timeline
    - Raw tweets from a user
  • x-tweet-search
    - Raw search results
  • x-tweet-fetch
    - Raw single tweet
  • x-user-lookup
    - User profile data
These require 
X_BEARER_TOKEN
instead of 
XAI_API_KEY
.
依托xAI的Grok API实现的AI驱动调研工具。返回带引用的AI摘要，而非原始推文数据。
需要原始推文？ 请使用以下工具：
  • x-user-timeline
    - 获取用户的原始推文
  • x-tweet-search
    - 获取原始搜索结果
  • x-tweet-fetch
    - 获取单条原始推文
  • x-user-lookup
    - 获取用户资料数据
这些工具需要
X_BEARER_TOKEN
而非
XAI_API_KEY
。

When to Use

适用场景

USE THIS SKILL FOR:
  • Summarized research with AI analysis
  • Current events and breaking news
  • Social sentiment ("What are developers saying about Y?")
  • X/Twitter trending topics and viral posts
  • Emerging tools/frameworks not in documentation yet
  • Community opinions on best practices
DON'T USE FOR:
  • Raw tweet data (use x-user-timeline, x-tweet-search)
  • Specific user's posts verbatim (use x-user-timeline)
  • Well-documented APIs (use WebFetch instead)
推荐使用本工具的场景：
  • 带AI分析的调研摘要生成
  • 时事与突发新闻调研
  • 社交舆情分析（如“开发者们对Y的评价如何？”）
  • X/Twitter热门趋势与viral帖子分析
  • 文档未收录的新兴工具/框架调研
  • 社区最佳实践观点收集
不推荐使用的场景：
  • 获取原始推文数据（请使用x-user-timeline、x-tweet-search）
  • 获取特定用户的原文帖子（请使用x-user-timeline）
  • 已有完善文档的API调研（请使用WebFetch）

Setup Requirements

配置要求

Check if the API key is set:
bash
if [ -z "$XAI_API_KEY" ]; then
  echo "ERROR: XAI_API_KEY is not set"
  echo "1. Get API key from https://x.ai/api"
  echo "2. Add to profile: export XAI_API_KEY=\"your-key\""
  echo "3. Restart terminal and Claude Code"
  exit 1
else
  echo "XAI_API_KEY is configured"
fi
If unavailable, inform the user that XAI_API_KEY must be configured before using this skill.
检查API密钥是否已配置：
bash
if [ -z "$XAI_API_KEY" ]; then
  echo "ERROR: XAI_API_KEY is not set"
  echo "1. Get API key from https://x.ai/api"
  echo "2. Add to profile: export XAI_API_KEY=\\"your-key\\""
  echo "3. Restart terminal and Claude Code"
  exit 1
else
  echo "XAI_API_KEY is configured"
fi
若未配置，请告知用户必须先配置XAI_API_KEY才能使用本工具。

API Overview

API概览

Endpoint: 
https://api.x.ai/v1/responses
Recommended Model: 
grok-4-1-fast
(specifically trained for agentic search)
Available Models:
  • grok-4-1-fast
    - Recommended for agentic search (auto-selects reasoning mode)
  • grok-4-1-fast-reasoning
    - Explicit reasoning for complex research
  • grok-4-1-fast-non-reasoning
    - Faster responses, simpler queries
Available Search Tools:
  • web_search
    - Searches the internet and browses web pages
  • x_search
    - Semantic and keyword search across X posts
端点：
https://api.x.ai/v1/responses
推荐模型：
grok-4-1-fast
（专为智能代理搜索训练）
可用模型：
  • grok-4-1-fast
    - 推荐用于智能代理搜索（自动选择推理模式）
  • grok-4-1-fast-reasoning
    - 针对复杂调研的显式推理模式
  • grok-4-1-fast-non-reasoning
    - 响应更快，适用于简单查询
可用搜索工具：
  • web_search
    - 互联网搜索与网页内容解析
  • x_search
    - X平台帖子的语义与关键词搜索

Basic Usage

基础用法

Simple Query with Search Tools

带搜索工具的简单查询

bash
curl -s "https://api.x.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "[YOUR QUERY]"}],
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
  }' | jq -r '.output[-1].content[0].text'
bash
curl -s "https://api.x.ai/v1/responses" \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "[YOUR QUERY]"}],
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
  }' | jq -r '.output[-1].content[0].text'

Query with Usage Tracking (Recommended)

带使用追踪的查询（推荐）

bash
RESPONSE=$(curl -s "https://api.x.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "[YOUR QUERY]"}],
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
  }')
bash
RESPONSE=$(curl -s "https://api.x.ai/v1/responses" \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "[YOUR QUERY]"}],
    "tools": [{"type": "web_search"}, {"type": "x_search"}]
  }')

Extract usage stats

Extract usage stats

TOOL_CALLS=$(echo "$RESPONSE" | jq -r '.usage.num_server_side_tools_used // 0') COST_TICKS=$(echo "$RESPONSE" | jq -r '.usage.cost_in_usd_ticks // 0') COST_USD=$(echo "scale=4; $COST_TICKS / 1000000000" | bc) echo "Tool calls: $TOOL_CALLS | Estimated cost: $$COST_USD" echo "" echo "$RESPONSE" | jq -r '.output[-1].content[0].text'
undefined
TOOL_CALLS=$(echo "$RESPONSE" | jq -r '.usage.num_server_side_tools_used // 0') COST_TICKS=$(echo "$RESPONSE" | jq -r '.usage.cost_in_usd_ticks // 0') COST_USD=$(echo "scale=4; $COST_TICKS / 1000000000" | bc) echo "Tool calls: $TOOL_CALLS | Estimated cost: \$$COST_USD" echo "" echo "$RESPONSE" | jq -r '.output[-1].content[0].text'
undefined

Search Tool Parameters

搜索工具参数

Web Search Options

网页搜索选项

json
"tools": [{
  "type": "web_search",
  "allowed_domains": ["github.com", "stackoverflow.com"],
  "excluded_domains": ["pinterest.com"],
  "enable_image_understanding": true
}]
  • allowed_domains
    - Restrict to these domains only (max 5)
  • excluded_domains
    - Exclude these domains (max 5)
  • enable_image_understanding
    - Analyze images found during search
json
"tools": [{
  "type": "web_search",
  "allowed_domains": ["github.com", "stackoverflow.com"],
  "excluded_domains": ["pinterest.com"],
  "enable_image_understanding": true
}]
  • allowed_domains
    - 仅允许搜索这些域名（最多5个）
  • excluded_domains
    - 排除这些域名（最多5个）
  • enable_image_understanding
    - 分析搜索中发现的图片

X Search Options

X搜索选项

json
"tools": [{
  "type": "x_search",
  "allowed_x_handles": ["elikimonimus", "anthropaboris"],
  "excluded_x_handles": ["spambot"],
  "from_date": "2025-01-01",
  "to_date": "2025-01-16",
  "enable_image_understanding": true,
  "enable_video_understanding": true
}]
  • allowed_x_handles
    - Only include posts from these accounts (max 10)
  • excluded_x_handles
    - Exclude posts from these accounts (max 10)
  • from_date
    / 
    to_date
    - ISO8601 date range (YYYY-MM-DD)
  • enable_image_understanding
    - Analyze images in posts
  • enable_video_understanding
    - Analyze videos in posts
json
"tools": [{
  "type": "x_search",
  "allowed_x_handles": ["elikimonimus", "anthropaboris"],
  "excluded_x_handles": ["spambot"],
  "from_date": "2025-01-01",
  "to_date": "2025-01-16",
  "enable_image_understanding": true,
  "enable_video_understanding": true
}]
  • allowed_x_handles
    - 仅包含这些账号的帖子（最多10个）
  • excluded_x_handles
    - 排除这些账号的帖子（最多10个）
  • from_date
    / 
    to_date
    - ISO8601格式的日期范围（YYYY-MM-DD）
  • enable_image_understanding
    - 分析帖子中的图片
  • enable_video_understanding
    - 分析帖子中的视频

Examples

示例

X/Twitter Trending Topics

X/Twitter热门趋势查询

bash
curl -s "https://api.x.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "What is currently trending on X? Include viral posts and major discussions."}],
    "tools": [{"type": "x_search"}]
  }' | jq -r '.output[-1].content[0].text'
bash
curl -s "https://api.x.ai/v1/responses" \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "What is currently trending on X? Include viral posts and major discussions."}],
    "tools": [{"type": "x_search"}]
  }' | jq -r '.output[-1].content[0].text'

Developer Sentiment on a Topic

开发者主题舆情分析

bash
curl -s "https://api.x.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "What are developers saying about [TOPIC] on X? Include recent discussions and opinions."}],
    "tools": [{"type": "x_search"}, {"type": "web_search"}]
  }' | jq -r '.output[-1].content[0].text'
bash
curl -s "https://api.x.ai/v1/responses" \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "What are developers saying about [TOPIC] on X? Include recent discussions and opinions."}],
    "tools": [{"type": "x_search"}, {"type": "web_search"}]
  }' | jq -r '.output[-1].content[0].text'

News and Web Research

新闻与网页调研

bash
curl -s "https://api.x.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "Latest news and developments about [TOPIC]"}],
    "tools": [{"type": "web_search"}]
  }' | jq -r '.output[-1].content[0].text'
bash
curl -s "https://api.x.ai/v1/responses" \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "Latest news and developments about [TOPIC]"}],
    "tools": [{"type": "web_search"}]
  }' | jq -r '.output[-1].content[0].text'

Research with Date Range

带日期范围的调研

bash
curl -s "https://api.x.ai/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "What happened with [TOPIC] last week?"}],
    "tools": [{
      "type": "x_search",
      "from_date": "2025-01-09",
      "to_date": "2025-01-16"
    }, {
      "type": "web_search"
    }]
  }' | jq -r '.output[-1].content[0].text'
bash
curl -s "https://api.x.ai/v1/responses" \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
    "model": "grok-4-1-fast",
    "input": [{"role": "user", "content": "What happened with [TOPIC] last week?"}],
    "tools": [{
      "type": "x_search",
      "from_date": "2025-01-09",
      "to_date": "2025-01-16"
    }, {
      "type": "web_search"
    }]
  }' | jq -r '.output[-1].content[0].text'

Response Structure

响应结构

The response contains:
json
{
  "output": [
    {"type": "web_search_call", "status": "completed", ...},
    {"type": "custom_tool_call", "name": "x_semantic_search", ...},
    {
      "type": "message",
      "content": [{
        "type": "output_text",
        "text": "The actual response with [[1]](url) inline citations",
        "annotations": [{"type": "url_citation", "url": "...", ...}]
      }]
    }
  ],
  "citations": ["url1", "url2", ...],
  "usage": {
    "input_tokens": 11408,
    "output_tokens": 2846,
    "num_server_side_tools_used": 8,
    "cost_in_usd_ticks": 429052500
  }
}
Extracting content: 
jq -r '.output[-1].content[0].text'
Extracting citations: 
jq -r '.citations[]'
响应包含以下内容：
json
{
  "output": [
    {"type": "web_search_call", "status": "completed", ...},
    {"type": "custom_tool_call", "name": "x_semantic_search", ...},
    {
      "type": "message",
      "content": [{"type": "output_text", "text": "The actual response with [[1]](url) inline citations", "annotations": [{"type": "url_citation", "url": "...", ...}]
      }
    ]
  },
  "citations": ["url1", "url2", ...],
  "usage": {
    "input_tokens": 11408,
    "output_tokens": 2846,
    "num_server_side_tools_used": 8,
    "cost_in_usd_ticks": 429052500
  }
}
提取内容：
jq -r '.output[-1].content[0].text'
提取引用：
jq -r '.citations[]'

Pricing

定价说明

Search tools are currently FREE (promotional pricing).
Standard pricing when active:
  • Web Search, X Search: $5 per 1,000 tool invocations
  • Token costs: Varies by model (~$3-15 per 1M input tokens)
Track costs via 
response.usage.cost_in_usd_ticks
(divide by 1,000,000,000 for USD).
搜索工具目前免费（推广期定价）。
正式定价启用后：
  • 网页搜索、X搜索：每1000次工具调用收费5美元
  • Token费用：因模型而异（约每100万输入Token收费3-15美元）
可通过
response.usage.cost_in_usd_ticks
追踪费用（除以10亿转换为美元）。

Error Handling

错误处理

If the API returns an error:
  1. Check XAI_API_KEY is set and valid
  2. Verify model name is correct (use 
    grok-4-1-fast
    )
  3. Check rate limits haven't been exceeded
  4. Ensure 
    tools
    array is properly formatted
  5. Report the error to the user with the API response
Common errors:
  • "Internal error"
    - Usually wrong model name or malformed request
  • Timeout - Request took too long (rare with agentic API)
若API返回错误：
  1. 检查XAI_API_KEY是否已配置且有效
  2. 验证模型名称是否正确（推荐使用
    grok-4-1-fast
    ）
  3. 检查是否超出调用速率限制
  4. 确保
    tools
    数组格式正确
  5. 将API响应中的错误信息反馈给用户
常见错误：
  • "Internal error"
    - 通常是模型名称错误或请求格式有误
  • 超时 - 请求耗时过长（智能代理API中极少出现）

Migration Notes

迁移说明

DEPRECATED (January 12, 2026): The old Live Search API using 
search_parameters
is being deprecated. This skill uses the new agentic tool calling API which is faster and more capable.
Old format (deprecated):
json
{
  "model": "grok-4-latest",
  "messages": [...],
  "search_parameters": {"mode": "on"}
}
New format (use this):
json
{
  "model": "grok-4-1-fast",
  "input": [...],
  "tools": [{"type": "web_search"}, {"type": "x_search"}]
}
已弃用（2026年1月12日）：旧版使用
search_parameters
的实时搜索API将被弃用。本工具使用新版智能代理工具调用API，响应更快、功能更强。
旧版格式（已弃用）：
json
{
  "model": "grok-4-latest",
  "messages": [...],
  "search_parameters": {"mode": "on"}
}
新版格式（推荐使用）：
json
{
  "model": "grok-4-1-fast",
  "input": [...],
  "tools": [{"type": "web_search"}, {"type": "x_search"}]
}

References

参考资料