X/Twitter 公开数据 API | SandBase

X(Twitter)是突发新闻、产品发布和公众情绪最先冒头的地方,这让它的搜索、资料和趋势数据在监测、调研和 agent 工作流里格外有价值。但官方 X API 反复调整过它的访问档位和定价,只读的公开数据也可能卡在一个付费开发者套餐和 OAuth 配置后面——那些你并不想去管的东西。

SandBase 的 X/Twitter 公开数据 API 给你一条不依赖你自己 X 开发者档位的稳定读取路径。它通过普通 REST 端点搜索 X 并读取公开的推文、资料、粉丝和趋势——一把 SandBase API key、同步返回 JSON,不用 X OAuth,也不用客户端库。下面的示例用的是 user-profile 和 trending 端点;请把其中的字段名和数值当作示例结构,以一份真实响应为准核对具体 schema。

这不是 X 官方 API。 如果你需要已认证的发帖、账号操作,或一份授权的数据协议,请用 X 官方 API;当你的流程需要的是公开、只读的搜索和内容数据时,用 SandBase。如果你想要一套落地的 agent 打法——采集、核验、缓存、重试和安全工具边界——看我们的 X/Twitter AI Agent API 指南。想直接试?领取 SandBase API key,再浏览 X 端点。

先说结论

• 一个 API 搜索 X 并读取公开的推文、资料、粉丝、评论和趋势。
• 本文的 Model API 端点用 POST /v1/api/twitter/<path> 调用——只传该端点的参数,不用客户端库,一把 SANDBASE_API_KEY。
• 端点以自然标识为入参:screen_name、tweet_id、搜索 keyword,或趋势用的 country。
• 它只返回公开、只读数据。不能发帖、没有账号操作、你这边也没有 X OAuth;鉴权用 SandBase API key。

你到底需要哪个 X API?

你的需求	选择	原因
发帖、回复、私信,或对已认证账号操作	X 官方 API	对你自己 X 应用带 OAuth 权限的账号操作。
搜索并读取公开的推文、资料、粉丝或趋势	SandBase X 公开数据 API	普通 REST、一把 SandBase key、面向只读流程的结构化 JSON。
高量级或定制的商业数据访问	X 的企业数据产品	大规模商业访问由 X 直接处理。

从 X API 能拿到什么

整个目录建立在一个 web 面上,提供单资源读取和搜索。按用途归类:

• 搜索 —— 按关键词搜索时间线,带 Top/Latest 两种模式。
• 推文 —— 推文详情、某用户的推文和回复、媒体、评论,以及转推者。
• 资料 —— 按 screen name 或 rest id 读取公开用户资料。
• 社交图谱 —— 按 screen name 读取粉丝和关注。
• 趋势 —— 按国家读取热门话题。

动手前请以每个端点的在线 API 参考为准。

SandBase 上的 X API 页面——带标签的概览,加上端点列表,每个端点标有路径。

X 提供的 vs. SandBase 补上的

公开数据来自 X。SandBase 并不拥有或运营 X,它只是为符合条件的公开数据流程提供一个统一的 API 层。每一项能力变成一个稳定端点,鉴权收敛成一把 key,响应都是可预期的 JSON——于是 agent 可以沿着同一套约定串起”搜一个话题 → 打开一条推文 → 读作者的资料”,而不用追着 X 变来变去的访问档位跑。

快速上手:第一次调用

SandBase 有不止一个 API 面。目录里可能会展示 /apis/v1/... 下的 GET 路径;本文用的是每个端点 API 参考里带厂商前缀的 Model API 路径。不要替换 HTTP 方法或 URL——按你所选端点的参考文档来。

按 screen name 读取一个公开资料:

import os
import requests

resp = requests.post(
    "https://api.sandbase.ai/v1/api/twitter/web/user-profile",
    headers={
        "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"screen_name": "NASA"},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
    error = body.get("error", {})
    raise RuntimeError(error.get("message", "X request did not complete"))

# 下面的字段名是示例结构,不是保证的 schema——
# 用防御式 .get() 访问,并以一份真实响应为准核对真实路径。
profile = body["outputs"][0]["data"]
print(profile.get("name"), profile.get("rest_id"), profile.get("statuses_count"))

curl -X POST https://api.sandbase.ai/v1/api/twitter/web/user-profile \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"screen_name": "NASA"}'

每个响应都用同一个信封:一个 id、一个 status、model 名称,以及一个 outputs 数组,其中唯一一项在 data 下携带载荷。读 outputs[0].data 之前先判 status。下面是一次 user-profile 读取的示例响应结构——端点参考只保证信封,所以请把其中的字段名和数值当作示例结构、而非保证的 schema,并以一份真实响应为准核对具体字段(载荷会变、数值也会随时间变):

{
  "id": "13a394de-55e6-4c72-b0b1-604007a3757d",
  "status": "completed",
  "model": "twitter/web/user-profile",
  "outputs": [
    {
      "data": {
        "name": "NASA",
        "rest_id": "11348282",
        "blue_verified": true,
        "location": "Pale Blue Dot",
        "friends": 115,
        "statuses_count": 74334,
        "created_at": "Wed Dec 19 20:20:32 +0000 2007"
      }
    }
  ]
}

这个 rest_id 是一个稳定标识符,user-profile 接受它作为可选入参。其他端点用各自的标识——tweet-detail 需要 tweet_id,user-followers 需要 screen_name——所以查每个端点的参考,看它接受什么入参。failed 或 timeout 的请求会带上 error 而没有 outputs。不同端点的响应结构不一样——先看一份真实响应,再按端点逐一对准字段路径。

端点的 API 参考是每个参数名和响应路径的权威来源。

能力地图

能力簇	代表端点	典型用途
搜索	twitter/web/search-timeline	话题与关键词发现(Top/Latest)
用户资料	twitter/web/user-profile	公开资料和账号信号
推文详情	twitter/web/tweet-detail	按 id 读取单条推文
评论	twitter/web/post-comments	回复串与情感分析
社交图谱	twitter/web/user-followers	粉丝与关注调研
趋势	twitter/web/trending	按国家的热门话题
评论	twitter/web/post-comments	按 tweet id 读回复串

分页方式因端点而异——若干 web 端点(包括 search-timeline)接受一个可选的 cursor 请求参数,你从上一次请求里把它带过来。具体看每个端点的 schema。

X 端点列表的一部分,在 web 面上。

在 agent 工作流里串联调用

因为每个端点共用同一套鉴权和同一个响应信封,agent 可以从一次搜索走到一个作者资料,而不用为每个页面单独写特例。一个常见的监测模式是这样:

1. 发现。 用 keyword(Top 或 Latest)调 twitter/web/search-timeline 找相关推文,把上一次请求的可选 cursor 带过来翻页。
2. 读取推文。 用 tweet_id 调 twitter/web/tweet-detail,再调 twitter/web/post-comments 拉回复串。
3. 给作者建档。 用 screen_name 调 twitter/web/user-profile 附上账号上下文。

每一步都返回同样的 { id, status, model, outputs } 结构,所以你的 agent 只需判一次 status,读 JSON 的那段代码在每一步都能复用。

常见用例

用 X 搜索 API 做话题监测

用一个关键词以 Top 或 Latest 模式调 twitter/web/search-timeline 追踪一个话题,再把可选的 cursor 带过来翻页。输入:关键词。输出:匹配推文的时间线。端点:search-timeline。完整工作流看X/Twitter 实时监测:从搜索到作者。

用 X 资料 API 做账号调研

用 twitter/web/user-profile 读取公开资料,拿到像粉丝数、认证状态和账号年龄这样的字段。输入:screen name。输出:结构化的资料记录。端点:user-profile。

用 X 趋势 API 做实时发现

按国家拉 twitter/web/trending,看现在正在冒头的是什么。输入:国家(可选,默认 UnitedStates)。输出:趋势列表。端点:trending。

边界与限制

• 只读、公开数据。 不能发帖、回复、私信,也不能做需账号授权的操作。
• 速率与量级。 把响应当作尽力而为的读取;作为客户端韧性措施,遇到 HTTP 429 这类瞬时错误时用退避重试。
• 参数与结构随上游而定。 标识各异(screen_name、rest_id、tweet_id、keyword、country);分页通常是一个 cursor。先看真实响应、读 schema。
• 对照在线参考确认端点。 可用性和字段可能变化;在依赖某个具体端点之前先确认。
• 这不是 X 官方合作。 SandBase 只是提供对公开数据的统一访问;请遵守 X 的条款以及你使用场景下适用的规则。

常见问题

我需要 X 开发者账号或 OAuth 吗? 不需要。你用 SANDBASE_API_KEY 向 SandBase 鉴权。这些读取端点不需要你注册 X 开发者档位或管理 OAuth。

用什么来标识用户或推文? 用自然标识:用户用 screen_name 或 rest_id,推文用 tweet_id。搜索用 keyword;趋势用 country。

分页怎么做? 若干 web 端点(包括 search-timeline)接受一个可选的 cursor 请求参数,你从上一次请求里把它带过来。具体看每个端点的 schema。

能读受保护账号或私信吗? 不能。这个 API 只返回公开数据。受保护账号、私信和需账号授权的数据都不在范围内。

有落地的 agent 指南吗? 有——我们的 X/Twitter AI Agent API 指南 走了一遍采集、核验、缓存、重试和安全工具边界。

从一个资料请求开始

创建一把 SandBase API key,用 user-profile 请求一个公开账号,先看清返回的 schema,再扩展到搜索、推文、粉丝或趋势。准备好之后:

• 领取 SandBase API key
• 浏览 X 端点
• 打开 user-profile 的 API 参考