X Search 工具让 Grok 能够在 X（原 Twitter）上执行关键词搜索、语义搜索、用户搜索和帖子串获取。该工具允许模型访问实时社交媒体内容、分析帖子并从 X 的海量数据中获取洞察。

X Search 按每获取 1,000 条帖子 $5、每获取 1,000 个用户资料 $10 计费，另收 token 费用；请参阅工具调用成本了解获取帖子或资料的统计范围。

SDK 支持

SDK/API	工具名称
xAI SDK	`x_search`
OpenAI Responses API	`x_search`
Vercel AI SDK	`xai.tools.xSearch()`

所有与 Responses API 兼容的 SDK 也支持此工具。

基础用法

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",  # reasoning model
    tools=[x_search()],
    include=["verbose_streaming"],
)

chat.append(user("What are people saying about xAI on X?"))

is_thinking = True
for response, chunk in chat.stream():
    for tool_call in chunk.tool_calls:
        print(f"\\nCalling tool: {tool_call.function.name} with arguments: {tool_call.function.arguments}")
    if response.usage.reasoning_tokens and is_thinking:
        print(f"\\rThinking... ({response.usage.reasoning_tokens} tokens)", end="", flush=True)
    if chunk.content and is_thinking:
        print("\\n\\nFinal Response:")
        is_thinking = False
    if chunk.content and not is_thinking:
        print(chunk.content, end="", flush=True)

print("\\n\\nCitations:")
print(response.citations)

import os
from openai import OpenAI

api_key = os.getenv("XAI_API_KEY")
client = OpenAI(
    api_key=api_key,
    base_url="https://api.x.ai/v1",
)

response = client.responses.create(
    model="grok-4.7",
    input=[
        {
            "role": "user",
            "content": "What are people saying about xAI on X?",
        },
    ],
    tools=[
        {
            "type": "x_search",
        },
    ],
)

print(response)

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What are people saying about xAI on X?',
  tools: {
    x_search: xai.tools.xSearch(),
  },
});

console.log(text);
console.log('Citations:', sources);

curl https://api.x.ai/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -d '{
  "model": "grok-4.7",
  "input": [
    {
      "role": "user",
      "content": "What are people saying about xAI on X?"
    }
  ],
  "tools": [
    {
      "type": "x_search"
    }
  ]
}'

X Search 参数

参数	说明
`allowed_x_handles`	仅考虑来自指定 X handle 的帖子（最多 20 个）
`excluded_x_handles`	排除来自指定 X handle 的帖子（最多 20 个）
`from_date`	搜索范围开始日期（ISO8601 格式）
`to_date`	搜索范围结束日期（ISO8601 格式）
`enable_image_understanding`	启用对帖子中图像的分析
`enable_video_understanding`	启用对帖子中视频的分析

仅考虑指定账号的帖子

使用 allowed_x_handles，仅考虑来自给定 X handle 列表的帖子。最多可包含 20 个 handle。

import os

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",
    tools=[
        x_search(allowed_x_handles=["elonmusk"]),
    ],
)

chat.append(user("What is the current status of xAI?"))
# stream or sample the response...

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "allowed_x_handles": ["elonmusk"],
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      allowedXHandles: ['elonmusk'],
    }),
  },
});

排除指定账号的帖子

使用 excluded_x_handles，防止模型在任何 X search tool invocation 中包含来自指定 handle 的帖子。最多可排除 20 个 handle。

chat = client.chat.create(
    model="grok-4.7",
    tools=[
        x_search(excluded_x_handles=["elonmusk"]),
    ],
)

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "excluded_x_handles": ["elonmusk"],
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      excludedXHandles: ['elonmusk'],
    }),
  },
});

日期范围

可以通过指定 from_date 和 to_date 限制搜索数据的日期范围。数据会被限制在从 from_date 到 to_date 的时间段内，包含两个日期。

两个字段都必须使用 ISO8601 格式，例如 "YYYY-MM-DD"。如果使用 xAI Python SDK，from_date 和 to_date 字段可以通过 datetime.datetime object 传入。

import os
from datetime import datetime

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import x_search

client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(
    model="grok-4.7",
    tools=[
        x_search(
            from_date=datetime(2025, 10, 1),
            to_date=datetime(2025, 10, 10),
        ),
    ],
)

chat.append(user("What is the current status of xAI?"))
# stream or sample the response...

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "What is the current status of xAI?"}],
    tools=[
        {
            "type": "x_search",
            "from_date": "2025-10-01",
            "to_date": "2025-10-10",
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What is the current status of xAI?',
  tools: {
    x_search: xai.tools.xSearch({
      fromDate: '2025-10-01',
      toDate: '2025-10-10',
    }),
  },
});

启用图像理解

将 enable_image_understanding 设置为 true，允许 Agent 分析搜索过程中遇到的 X 帖子中的图像。

chat = client.chat.create(
    model="grok-4.7",
    tools=[
        x_search(enable_image_understanding=True),
    ],
)

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "Find X posts with images about AI"}],
    tools=[
        {
            "type": "x_search",
            "enable_image_understanding": True,
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'Find X posts with images about AI',
  tools: {
    x_search: xai.tools.xSearch({
      enableImageUnderstanding: true,
    }),
  },
});

启用视频理解

将 enable_video_understanding 设置为 true，允许 Agent 分析 X 帖子中的视频。该功能仅适用于 X Search，不适用于 Web Search。

chat = client.chat.create(
    model="grok-4.7",
    tools=[
        x_search(enable_video_understanding=True),
    ],
)

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "Find X posts with videos about AI"}],
    tools=[
        {
            "type": "x_search",
            "enable_video_understanding": True,
        },
    ],
)

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'Find X posts with videos about AI',
  tools: {
    x_search: xai.tools.xSearch({
      enableVideoUnderstanding: true,
    }),
  },
});

用量计数

每个运行了 X Search 的 Responses API 响应都会报告获取的条目数，便于根据 2026 年 9 月 21 日生效的按条目价格核对请求费用。这些计数位于 usage.server_side_tool_usage_details 下，与按调用次数统计的 x_search_calls 并列：

字段	统计内容
`x_posts_fetched`	由 `x_keyword_search`、`x_semantic_search` 和 `x_thread_fetch` 返回的帖子，包括上级帖子、引用帖子以及所获取帖子串中的每条帖子
`x_users_fetched`	由以下工具返回的用户资料：`x_user_search`

两个计数都会累加请求中所有 X Search 调用的结果，不会去重；同一条帖子被两次搜索返回，就计为两条。流式传输时，usage 字段在终止事件（response.completed，或 response.incomplete，用于响应被截断的情况）中表示整个请求的总计。

执行两次 X 搜索后，server_side_tool_usage_details 是 /v1/responses usage 对象中的一个块，示例如下：

"server_side_tool_usage_details": {
  "web_search_calls": 0,
  "x_search_calls": 2,
  "x_posts_fetched": 44,
  "x_users_fetched": 3,
  "code_interpreter_calls": 0,
  "file_search_calls": 0,
  "mcp_calls": 0,
  "document_search_calls": 0,
  "image_generation_calls": 0
}

引用

有关如何获取和使用搜索结果引用的详情，请参阅引用页面。

最后更新：2026 年 9 月 22 日