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

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

SDK 支持

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

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

基础用法

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 SpaceXSI on X?',
  tools: {
    x_search: xai.tools.xSearch(),
  },
});

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

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 SpaceXSI on X?",
        },
    ],
    tools=[
        {
            "type": "x_search",
        },
    ],
)

print(response)

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 SpaceXSI on X?"
    }
  ],
  "tools": [
    {
      "type": "x_search"
    }
  ]
}'

X Search 参数

参数	类型	说明
`allowed_x_handles`	字符串数组	仅考虑这些账号发布的帖子。填写账号名时省略 `@`（最多 20 个；Vercel AI SDK 最多 10 个）
`excluded_x_handles`	字符串数组	排除这些账号发布的帖子。填写账号名时省略 `@`（最多 20 个；Vercel AI SDK 最多 10 个）
`from_date`	字符串	起始日期，见日期范围（`YYYY-MM-DD`）
`to_date`	字符串	结束日期，见日期范围（`YYYY-MM-DD`）
`enable_image_understanding`	布尔值	允许模型查看所找到帖子中的图像。默认值为 `false`。
`enable_video_understanding`	布尔值	允许模型观看所找到帖子中的视频。默认值为 `false`。

仅考虑指定账号的帖子

使用 allowed_x_handles，以便只考虑指定 X 账号发布的帖子。

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What has SpaceX posted about Starship recently?',
  tools: {
    x_search: xai.tools.xSearch({
      allowedXHandles: ['SpaceX'],
    }),
  },
});

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "What has SpaceX posted about Starship recently?"}],
    tools=[
        {
            "type": "x_search",
            "allowed_x_handles": ["SpaceX"],
        },
    ],
)

排除指定账号的帖子

使用 excluded_x_handles，以便在所有 X 搜索工具调用中排除指定账号的帖子。

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'How are people reacting to the latest Tesla delivery numbers?',
  tools: {
    x_search: xai.tools.xSearch({
      excludedXHandles: ['Tesla'],
    }),
  },
});

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "How are people reacting to the latest Tesla delivery numbers?"}],
    tools=[
        {
            "type": "x_search",
            "excluded_x_handles": ["Tesla"],
        },
    ],
)

日期范围

如需限制搜索数据的日期范围，请指定 from_date 和 to_date。仅包含从 UTC 00:00 开始的帖子，开始日期为 from_date，结束日期为 to_date（不含当天）。如需搜索单日，请将 to_date 设为次日。

使用 YYYY-MM-DD 作为两个字段的格式，例如 "2026-09-28"。其他格式（包括完整的日期时间）均不会生效。

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'How did people react to the Starship launch?',
  tools: {
    x_search: xai.tools.xSearch({
      fromDate: '2026-09-28',
      toDate: '2026-10-01',
    }),
  },
});

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": "How did people react to the Starship launch?"}],
    tools=[
        {
            "type": "x_search",
            "from_date": "2026-09-28",
            "to_date": "2026-10-01",
        },
    ],
)

启用图像理解

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

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,
    }),
  },
});

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,
        },
    ],
)

启用视频理解

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

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,
    }),
  },
});

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,
        },
    ],
)

X 搜索的工作原理

添加 x_search 到 tools 后，由模型决定何时调用以下函数以及调用次数。模型读取获取的帖子，并在回答中引用来源。每次调用在响应输出中对应一项 custom_tool_call，其名称与函数相同。响应还会报告用量计数。

函数	模型用途	计费单位
`x_keyword_search`	使用 X 高级搜索运算符进行关键词搜索，排序方式为 `Top` 或 `Latest`	获取的帖子数
`x_semantic_search`	按含义检索，无需逐字匹配	获取的帖子数
`x_user_search`	按名称或描述查找用户	获取的用户资料数
`x_thread_fetch`	获取一条帖子及其上级帖子和回复	获取的帖子数

启用图像或视频理解后，模型还可以查看帖子中的图像和视频，按图像 token 计费。

无论模型编写什么查询，账号和日期参数都适用于每次关键词搜索和语义搜索，但不适用于获取消息串。

示例

以下仅展示部分输出。模型会自行选择查询，因此结果可能不同。

控制成本

要降低费用，可缩小账号和日期范围，减少模型需获取的内容；使用 max_turns 要求减少搜索轮次，并检查响应中的获取数量。

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

const { response } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'What did SpaceX post about Starship in September 2026?',
  tools: { x_search: xai.tools.xSearch({ allowedXHandles: ['SpaceX'], fromDate: '2026-09-01', toDate: '2026-10-01' }) },
  providerOptions: { xai: { maxTurns: 2 } },
  include: { responseBody: true },
});

// response.body is the raw Responses API JSON.
const usage = Object(response.body).usage;
console.log(`x_posts_fetched: ${usage.server_side_tool_usage_details.x_posts_fetched}`);
console.log(`x_users_fetched: ${usage.server_side_tool_usage_details.x_users_fetched}`);

import os

from openai import OpenAI

client = OpenAI(api_key=os.getenv("XAI_API_KEY"), base_url="https://api.x.ai/v1")
response = client.responses.create(
    model="grok-4.7",
    input="What did SpaceX post about Starship in September 2026?",
    tools=[{"type": "x_search", "allowed_x_handles": ["SpaceX"], "from_date": "2026-09-01", "to_date": "2026-10-01"}],
    extra_body={"max_turns": 2},
)

usage = response.usage.model_dump()
details = usage["server_side_tool_usage_details"]
print(f"x_posts_fetched: {details['x_posts_fetched']}")
print(f"x_users_fetched: {details['x_users_fetched']}")

curl -s https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
  "model": "grok-4.7",
  "input": "What did SpaceX post about Starship in September 2026?",
  "tools": [{"type": "x_search", "allowed_x_handles": ["SpaceX"], "from_date": "2026-09-01", "to_date": "2026-10-01"}],
  "max_turns": 2
}' | jq -r '.usage | "x_posts_fetched: \(.server_side_tool_usage_details.x_posts_fetched)", "x_users_fetched: \(.server_side_tool_usage_details.x_users_fetched)"'

x_posts_fetched: 19
x_users_fetched: 0

用量计数

每个运行了 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 年 10 月 10 日

从写代码，到创作下一幕

Agent Plan & Coding Plan

Seedance 2.5

工具

X Search

SDK 支持

基础用法

X Search 参数

仅考虑指定账号的帖子

排除指定账号的帖子

日期范围

启用图像理解

启用视频理解

X 搜索的工作原理

示例

控制成本

用量计数

引用