Grok X 搜索 API：捕获 X (Twitter) 帖子数据为结构化 JSON

TL;DR:

• Grok 答案引用了 X 帖子，Scrapeless scraper.grok 参与者将这些帖子返回为一个单独的结构化数组。 x_search_results 和 web_search_results 在同一个负载中并排存在，因此一次请求可以返回开放网络引用和 X (Twitter) 引用，而无需任何 HTML 解析。
• 每个 X 引用携带十一把钥匙，其中七个在每次捕获中都有值。 post_id、user_name、name、text、create_time、view_count 和 profile_image_url 在本指南收集的所有 167 个帖子条目中都是非空的；citation_id、community_note、parent 和 quote 在所有这些帖子中都是空的。
• 提示是控制界面，而不是搜索参数。 一个简单的定义性问题返回了零个工具调用和两个空面板。指向 Grok 的 X 的提示返回了 3 到 35 条帖子之间的不同数量。
• tool_usages 显示了 Grok 执行的字面 X 查询。 该数组记录了工具名称及其参数，因此您可以回溯到生成您收到的帖子的确切搜索字符串 — 包括 from:、since:、until: 和 min_faves: 运算符。
• 面板不保证去重。 重叠的工具调用可能会重复帖子，并且重复的频率因捕获而异：在七次捕获中，重复比例从 0%（18 条目，18 个不同的 post_id 值）到 48%（25 条目，13 个不同的值）不等。在计数之前先去重：七个捕获中有两个没有重复，响应中没有信息告诉您收到的是什么类型。
• 推理模式并不控制 X 数据源深度。 在相同提示下，两个 MODEL_MODE_FAST / MODEL_MODE_EXPERT 对调转，因此将模式视为推理设置而不是音量拨轮。
• 自由开始。 新的 Scrapeless 账户包括免费试用积分 — 可在 app.scrapeless.com 注册。

问 Grok 人们在发射望远镜时发布了什么，答案将附带一份 X 帖子列表。那些帖子是模型选择的证据，Scrapeless scraper.grok 参与者将其作为 JSON 行返回，带有作者句柄、时间戳、浏览次数和帖子 ID，已经分隔到字段中。

这使得 Grok 成为获取 X 数据的不同途径，而不是通常的途径。常见的方法直接从平台拉取帖子，旨在完整性。本指南覆盖了相反的方向：捕获答案引擎选择引用的帖子，这是一个更小、更具过滤性的切片，以及模型用于查找它们的查询。

本指南涵盖请求形状、X 引用的确切字段架构、如何使面板填充而不是返回空以及 tool_usages 数组，显示 Grok 实际上搜索的内容。有关一般参与者合同 — 信封、模式、伴随参与者 — 请参见 Grok scraper API guide。

Grok X 搜索 API 给您带来的

一次请求返回 Grok 的答案以及其两个引用面板作为离散数组。X 面板是本指南讨论的部分。

• 帖子级行，而不是呈现的 Feed。 每个条目都是一个对象，具有稳定的 post_id、作者的句柄和显示名称、帖子正文、RFC 3339 时间戳，以及以整数表示的浏览次数。
• 模型自己的查询，被记录。 tool_usages 保留了 Grok 发送的搜索，因此捕获是可重现且可审计的，而不是黑箱。
• 一次调用的两个面板。 一个跨越社交反应和官方文档的提示返回 X 帖子和开放网络页面到同一个负载中，已经分开。
• 时间限制的切片。 因为 Grok 将日期运算符组成到其 X 搜索中，命名一个窗口的提示会生成该窗口内的帖子。
• 账户范围的捕获。 一个命名账户的提示通过 X 用户查找路由，返回该账户的最近帖子。

该面板是一个引用集，而不是完整的档案。它反映了一个答案所依赖的内容，这比全面收集更适合引用跟踪和情感采样。

端点、参与者和参数

• 同步端点： POST https://api.scrapeless.com/api/v2/scraper/execute — 阻塞并返回完成的结果。
• 异步端点： POST https://api.scrapeless.com/api/v2/scraper/request 返回一个 task_id；GET https://api.scrapeless.com/api/v2/scraper/result/{task_id} 一旦准备好就返回结果。
• 参与者： scraper.grok
• Auth 头： x-api-token: $SCRAPELESS_API_KEY

本指南的捕获花费了大约 16 到 60 秒。同步端点适合快速从命令行检查。对于任何脚本化的内容，更喜欢异步对：它用 HTTP 201 和 task_id 回应提交调用，然后在任务仍在运行时返回 HTTP 语义规范中定义的 202 Accepted 状态，一旦结果准备好则返回 200 和 status: "success"。轮询这个过渡使得客户端不确定，而不管给定提示需要多长时间。

将密钥保存在环境中，而不是代码中：

export SCRAPELESS_API_KEY="your_api_token_here"

您的第一次捕获

此请求命名了一个帐户，这是第一次尝试获取填充的 X 面板的最可靠方法。jq 过滤器打印了两个面板大小和 Grok 调用的工具。

curl -sS -X POST https://api.scrapeless.com/api/v2/scraper/execute \
  -H "Content-Type: application/json" \
  -H "x-api-token: ${SCRAPELESS_API_KEY}" \
  -d '{
    "actor": "scraper.grok",
    "input": {
      "prompt": "What has @NASA posted on X recently?",
      "country": "US",
      "mode": "MODEL_MODE_FAST"
    }
  }' | jq '{
    x_posts: (.task_result.x_search_results | length),
    web_pages: (.task_result.web_search_results | length),
    tools: [.task_result.tool_usages[].tool_name]
  }'

对此请求的一个捕获返回了 {"x_posts": 20, "web_pages": 0, "tools": ["x_keyword_search", "x_keyword_search"]} — 二十个 X 帖子，没有开放网络页面，以及两个关键词搜索。计数在不同运行之间变化，因此将形状视为契约，将数字视为样本。如果 x_posts 是 0 并且 tools 是空的，则 Grok 根据自己的知识回答并未进行搜索 — 请参见下面 填充 X 面板。

X 帖子模式，逐字段解析

x_search_results 中的每个条目都是一个具有相同 11 个键的扁平对象。这是上面 @NASA 请求的一个真实捕获：

// captured from a live scraper.grok run; a single x_search_results entry
{
  "citation_id": "",
  "community_note": "",
  "create_time": "2026-08-06T11:00:59Z",
  "name": "NASA",
  "parent": null,
  "post_id": "2085320225776427457",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg",
  "quote": null,
  "text": "LIVE: Time for a spacewalk! Watch as @Astro_Jessica and @Astro_Anil step outside the @Space_Station to prepare the orbiting lab for a new solar array.",
  "user_name": "NASA",
  "view_count": 714862
}

在本指南中捕获的 167 个帖子条目中，字段清晰地分为两组：

这四个从未填充的字段值得注意。它们在每个条目的模式中都存在，因此读取它们的代码不会引发错误，但在此捕获集中的内容并未填充它们。基于七个已填充的字段构建，并将其他四个视为保留，而不是可以依赖的回复线程或社区注释功能。

user_name 和 post_id 一起重建一个标准的帖子 URL，作为 https://x.com/<user_name>/status/<post_id>，这对于存储回源的链接非常有用。

在免费计划中获取您的 API 密钥：app.scrapeless.com

阅读 Grok 实际运行的查询

tool_usages 是将此捕获路由与普通 X 搜索区分开来的字段。每个条目名称都是一个工具，并将其参数作为 JSON 字符串传递，因此您可以准确回读所搜索的内容。

import json
import os
import time

import requests

BASE = "https://api.scrapeless.com/api/v2/scraper"
HEADERS = {
    "Content-Type": "application/json",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}


def capture(prompt, country="US", mode="MODEL_MODE_FAST"):
    """Submit a Grok capture, then poll until the task_result is ready."""
    submit = requests.post(
        f"{BASE}/request",
        headers=HEADERS,
        json={
            "actor": "scraper.grok",
            "input": {"prompt": prompt, "country": country, "mode": mode},
        },
        timeout=60,
    )
    submit.raise_for_status()
    task_id = submit.json()["task_id"]

    for _ in range(120):
        poll = requests.get(f"{BASE}/result/{task_id}", headers=HEADERS, timeout=60)
        poll.raise_for_status()
        body = poll.json()
        if body.get("status") == "success":
            return body["task_result"]
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in the allotted window")


result = capture("Search X for posts from:NASA about Artemis since:2026-07-01 and summarize them.")

for call in result.get("tool_usages") or []:
    print(call["tool_name"])
    for key, value in json.loads(call["tool_args"]).items():
        print(f"    {key}: {value}")

print(f"x_search_results: {len(result.get('x_search_results') or [])}")

该提示嵌入了两个 X 搜索操作符，它们原汁原味地保留到工具调用中：

x_keyword_search
    query: from:NASA Artemis since:2026-07-01
    limit: 10
    mode: Latest
x_search_results: 3

您在提示中编写的操作符成为查询中的操作符。在捕获中，Grok 组合了 from:、since:、until:、lang: 和 min_faves: 进行搜索，连同一个 mode 的 Top 或 Latest。其中一些与 平台发布的搜索操作符参考 匹配，该参考列出了 from: 和 lang: 以及参与度过滤器；日期边界的 since: 和 until: 形式来自搜索界面，而不是该参考。出现了三种不同的 X 工具：

| 工具 | 观察到的参数 | 它的功能 |
| x_keyword_search | query, limit, mode | 操作员驱动的关键词搜索; mode 选择 Top 或 Latest |
| x_semantic_search | query, limit, from_date, to_date, min_score_threshold | 在日期窗口内的基于意义的搜索 |
| x_user_search | query, count | 账号查找，当提示名为一个句柄时使用 |

两个非 X 工具共享数组: web_search 与 query 和 num_results, 以及 open_page 与 url 和 start_line, 用于填充 web_search_results。

在每次捕获时记录 tool_usages 会将存储结果转变为您可以后续解释的内容——您保存的帖子和找到它们的查询。

让 X 面板填充

一个空的 x_search_results 并不是错误条件。这意味着 Grok 在没有搜索 X 的情况下作出了回答。这一区别在同一负载中是可见的: 当面板因没有被搜索的内容而为空时，tool_usages 也为空。

一个普通的定义性提示——“无头浏览器是什么？”——返回零次工具调用、零个 X 帖子和零个网页。每个指出 X 的提示都返回帖子。在为本指南测量的捕获中：

三个提示模式始终可靠地填充面板：

1. 命名平台。 提示中的“在 X 上”是最强的单一信号。
2. 命名账户。 一个句柄通过 x_user_search 路由并返回该账户的帖子。
3. 询问反应、情感或讨论。 这些帖子从公开网络中提取，其中一个事实问题可以得到解决。

最后一行做了其他行没有做的事情。一个同时询问社会反应和官方来源的提示填充了两个面板，因此一次调用返回人们发布的内容以及主要来源所说的内容。

Python 中的结构化输出处理

在可用之前，面板需要一个转换：去重。重叠的工具调用可能会多次返回相同的帖子，因此数组长度是区分的帖子数量的上限，而不是其计数。一些捕获没有重复；而其他捕获几乎重复了一半的条目。由于您无法在检查之前知道您得到了哪个，所以无条件去重。

import json
import os
import time

import requests

BASE = "https://api.scrapeless.com/api/v2/scraper"
HEADERS = {
    "Content-Type": "application/json",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}


def capture(prompt, country="US", mode="MODEL_MODE_FAST"):
    """Submit a Grok capture, then poll until the task_result is ready."""
    submit = requests.post(
        f"{BASE}/request",
        headers=HEADERS,
        json={
            "actor": "scraper.grok",
            "input": {"prompt": prompt, "country": country, "mode": mode},
        },
        timeout=60,
    )
    submit.raise_for_status()
    task_id = submit.json()["task_id"]
    print(f"submitted task_id={task_id}")

    for _ in range(120):
        poll = requests.get(f"{BASE}/result/{task_id}", headers=HEADERS, timeout=60)
        poll.raise_for_status()
        body = poll.json()
        if body.get("status") == "success":
            return body["task_result"]
        time.sleep(5)
    raise TimeoutError(f"task {task_id} did not finish in the allotted window")


def x_rows(task_result):
    """Flatten x_search_results into unique rows keyed by post_id."""
    seen, rows = set(), []
    for post in task_result.get("x_search_results") or []:
        post_id = post.get("post_id")
        if not post_id or post_id in seen:
            continue
        seen.add(post_id)
        handle = post.get("user_name") or ""
        rows.append(
            {
                "post_id": post_id,
                "handle": handle,
                "display_name": post.get("name") or "",
                "posted_at": post.get("create_time") or "",
                "views": post.get("view_count") or 0,
                "text": " ".join((post.get("text") or "").split()),
                "url": f"https://x.com/{handle}/status/{post_id}",
            }
        )
    return rows


result = capture("What are people saying on X about the James Webb Space Telescope this week?")
rows = x_rows(result)

raw_count = len(result.get("x_search_results") or [])
print(f"raw={raw_count} unique={len(rows)}")

for row in sorted(rows, key=lambda r: r["views"], reverse=True)[:3]:
    print(f"@{row['handle']} · {row['posted_at']} · {row['views']:,} views")
    print(f"  {row['text'][:100]}")
    print(f"  {row['url']}")

print(json.dumps(rows[:1], ensure_ascii=False, indent=2))

x_rows 返回的正是表或仓库列集所需的形状：每个不同帖子的每一行，一个可解析的 URL，以及一个可以进行排序的整数查看计数。这个列表是普通的 JSON 可序列化字典，所以它可以直接放入 DataFrame 或插入语句中。

在您进行采样之前按 views 排序通常是正确的做法，因为面板将非常大的账户与非常小的账户混合在一起——在一个捕获集中观察到的范围从 0 到接近 700 万次查看。

常见数据形状问题

• 数组长度不是帖子计数。 在计数或绘图之前对 post_id 去重。在七个捕获中测量：15 个条目 / 13 个唯一，35 / 29，34 / 31，25 / 13，15 / 14，和两个没有重复的捕获（10 / 10 和 18 / 18）。重复的份额不够稳定以预测——无论如何在构建去重步骤时这样做，因为基于原始长度构建的语音份额会高估两个工具调用都呈现的每个账户。
• 四个字段在结构上存在但始终为空。 citation_id, community_note, parent, 和 quote 在每个条目中都出现，并且在所有 167 条中都是空的。在没有确认它们为您的提示填充的情况下，请不要围绕它们设计回复线程或社区备注功能。
• view_count 是一个整数，post_id 是一个字符串。 这里观察到的帖子标识符超过 2×10^18，超出了双精度浮点数准确表示的范围——这就是为什么 JSON 规格对数字互操作性的指导 警告不要依赖跨实现的数字精度。请将 post_id 保持为文本，端到端；将其转换为浮点数是帖子 ID 默默改变值的方式。
• 模式并不是音量旋钮。 在一个相同的提示上，两个 FAST / EXPERT 对返回了 15 和 20 条帖子，然后是 25 和 15 条——顺序颠倒。两个相同设置的两次运行之间的面板大小变化更大，而不是设置之间。为保持方法一致性，在追踪系列中保持模式不变，而不是因为它能保证更深的来源。
• 相同的提示每次返回不同的面板。 Grok 会在每次运行中重新编排其查询，因此措辞变化，结果集也随之变化。阅读一个系列而不是单次捕获，并存储 tool_usages 以便你可以看到哪些运行提出了不同的问题。
• 面板独立填充。 提示可以填充 X 面板并留 web_search_results 为空，也可以同时填充两个。分别检查每个数组的长度，而不是假设一个暗示另一个。

结论

Grok 捕获中的 X 面板是一个小而类型明确的数据集，位于答案有效载荷内部。一个 POST 到 scraper.grok 的提示返回帖子 ID、用户名、显示名称、帖子文本、UTC 时间戳和查看计数，以平坦的 JSON 形式呈现——这七个字段在本指南捕获的每个条目中都有填充。在 post_id 上去重，保持标识符为字符串，并记录 tool_usages 以便每一行存储的查询都带有找到它的查询。结果涵盖了平台的一小部分，而不是其档案：答案引擎认为值得引用的帖子，以及附带的搜索。

开始从 Grok 答案捕获 X 引用

加入我们的社区，获取免费计划，并与构建答案引擎管道的开发者交换笔记：Discord · Telegram。

在 app.scrapeless.com 注册以获取免费试用积分，然后将 scraper.grok 指向您的监控程序跟踪的帐户、主题和窗口。通用抓取 API 页面涵盖了更广泛的参与者家族，目前的使用层级在 定价 页面上。

常见问题

问：为什么 x_search_results 在我的请求中为空？

因为 Grok 没有搜索 X 而进行的回答。检查同一有效载荷中的 tool_usages：如果它也为空，则根本没有进行搜索。提到平台的提示（“在 X 上”）、提到特定帐户或询问反应和讨论的提示在本指南的每次捕获中都填充了面板，而普通的定义性问题返回零个工具和零个帖子。

问：每个 X 帖子实际包含什么字段？

十一项键，出现在每个条目中。在这里捕获的 167 个条目中，有七项在所有条目中都被填充：post_id、user_name、name、text、create_time、view_count 和 profile_image_url。剩余的四项——citation_id、community_note、parent 和 quote——在每一个条目中都是空的。

问：我可以控制 Grok 搜索哪些 X 帖子吗？

可以，通过提示。写入提示中的搜索运算符会传播到 Grok 发出的问题中：一个包含 from:NASA 和 since:2026-07-01 的提示生成了工具调用 query: from:NASA Artemis since:2026-07-01。在每次运行后阅读 tool_usages 以确认搜索了什么。

问：我如何重建指向原始帖子的链接？

组合两个始终填充的字段：https://x.com/<user_name>/status/<post_id>。保持 post_id 为字符串——如果 JSON 解析器将其读取为浮点数字，它的长度足以丢失精度。

问：MODEL_MODE_EXPERT 返回的 X 帖子比 MODEL_MODE_FAST 多吗？

不可靠。两个在相同提示下的配对运行在 FAST 下返回了 15 个帖子，而在 EXPERT 下返回了 20 个，然后在 FAST 下返回了 25 个，在 EXPERT 下返回了 15 个。运行间的变化大于模式之间的差异。选择一个模式并保持不变，以便追踪系列保持可比较性。

问：这与直接从平台收集帖子有什么不同？

范围和选择。此路径返回答案引用的帖子——一种经过编辑过滤的样本，通常为 3 到 35 个帖子，附带模型的查询。直接收集则以完整性为目标。当问题是答案引擎呈现并引用了什么时使用此途径；当你需要对某个标签或帐户进行全面覆盖时，使用专用收集途径。

问：关于帖子数据本身，我应该注意什么？
发布的文本和作者姓名是由真实人物创作的公开内容，因此将存储捕获视为关于个人的数据集。保持收集有界限且目的明确，仅保留分析所需的字段，并检查欧盟通用数据保护条例或类似法规是否适用于您的使用，特别是在重新发布帖子文本或头像之前。平台条款独立于数据保护法管理重用；请分别审查这两者并咨询律师以确定您的具体情况。

问：我需要代理吗？

不需要。国家固定的住宅出口已内置于该角色中，所需的country输入是整个配置。