Twitter 关键词搜索 API 教程 | SandBase

如果你在 Twitter/X 上追踪一个话题——一次产品发布、一个话题标签、一个竞品——你想要一个可复用的循环:按关键词搜时间线、翻页匹配、给值得关注的推文背后的账号建档。这篇 Twitter 关键词搜索 API 教程用两个 SandBase 端点把这个循环串起来,让 Agent 能端到端跑完。它建立在 Twitter 公开数据 API 汇总页之上;建议先读那篇了解全局。

这里的一切都是公开、只读数据。不需要登录 Twitter、不需要 SDK——但仍需要一个 SandBase API 密钥来鉴权。端点 API 参考是参数和响应信封的权威来源。参考只保证信封本身;下面的载荷字段名来自我实际跑的调用(测试于 2026-09-28,UTC),是示意性的、仅供观测——并非文档保证——请以真实响应为准核对。

先说结论

• 两个端点构成循环:search-timeline(找推文)→ user-profile(给作者建档)。
• 每次调用都是 POST /v1/api/twitter/web/<path>,只传该端点的参数,一个 SANDBASE_API_KEY。
• 以自然输入链式串联:一个 keyword 驱动搜索;一条推文的 screen_name 成为 profile 调用的 username。
• 用返回的 next_cursor 翻时间线。仅公开、只读数据。

SandBase vs. 官方 X API

你的需求	用
公开、只读的搜索和资料	SandBase Twitter 公开数据 API
发帖、私信,或以账号身份操作	X 官方 API
私有或仅账号可见的数据	两种公开方案都不适用

工作流一览

1. 用 twitter/web/search-timeline 以一个 keyword 搜时间线。
2. 用一条推文的 screen_name 调用 twitter/web/user-profile 给作者建档。

每个端点返回共享信封——一个 id、一个 status、model,以及在 completed 运行上的负载。参考记录负载在 outputs[0].data 下;防御式读取。

SandBase 上的 Twitter 端点——search-timeline 和 user-profile 驱动这个循环。

第 0 步:一个辅助函数管所有调用

import os
import requests

API = "https://api.sandbase.ai/v1/api"
HEADERS = {
    "Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
    "Content-Type": "application/json",
}

def call(path: str, payload: dict) -> dict:
    resp = requests.post(f"{API}/{path}", headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    body = resp.json()
    if body.get("status") != "completed":
        raise RuntimeError(body.get("error", {}).get("message", f"{path} 未完成"))
    # 信封可能不同:优先读顶层 output,否则 outputs[0].data。
    output = body.get("output")
    if output is None and body.get("outputs"):
        output = body["outputs"][0].get("data", {})
    return output or {}

第 1 步:搜时间线

data = call("twitter/web/search-timeline", {"keyword": "AI agents"})
tweets = data.get("timeline", [])
next_cursor = data.get("next_cursor")
print(len(tweets), "条推文,还有更多:", bool(next_cursor))

在我抓到的响应里(搜索 run id cad13e3a-5e0d-4aa7-b077-2e4883655ffc,测试于 2026-09-28,UTC),负载带一个 timeline 列表,加 next_cursor 和 prev_cursor。每条推文带 tweet_id、text、screen_name、created_at 和互动数(favorites、retweets、replies)。这些是示意性的、仅供观测的字段——请对照真实响应核对。

翻页时,用返回的 next_cursor 重发 search-timeline(确切参数名对照参考核对)。

search-timeline 参考——keyword 参数和翻页的事实来源。

第 2 步:给作者建档

screen_names = {t.get("screen_name") for t in tweets if isinstance(t, dict) and t.get("screen_name")}

for name in list(screen_names)[:5]:
    profile = call("twitter/web/user-profile", {"username": name})
    print(name, "-", profile.get("name"), "|", profile.get("friends"), "关注")

user-profile 端点接受一个 username——一条推文的 screen_name 可直接用。在我这次运行里(user-profile run id eb35152f-fa49-4c74-8b80-7e6957efc2b3),负载带 name、desc、friends、media_count、blue_verified 和 created_at——这些是示意性的、仅供观测的字段,参考并不保证。用 .get() 读每个。

user-profile 参考——传一个 username;一条推文的 screen_name 可作为该标识。

串起来

def research(keyword: str, max_authors: int = 5):
    data = call("twitter/web/search-timeline", {"keyword": keyword})
    tweets = data.get("timeline", [])
    seen, authors = set(), []
    for t in tweets:
        if not isinstance(t, dict):
            continue
        name = t.get("screen_name")
        if name and name not in seen:
            seen.add(name)
            profile = call("twitter/web/user-profile", {"username": name})
            authors.append({"screen_name": name, "profile": profile})
        if len(authors) >= max_authors:
            break
    return {"tweets": tweets, "authors": authors}

因为两个端点共享同一个信封,循环保持扁平:call(...) 里一次 status 检查、一套 .get() 模式,screen_name 从一条推文流向 profile 调用。

常见用例

品牌与发布监测

用 search-timeline 搜一个产品名或话题标签,用游标翻页,跨运行对推文集做 diff 以捕捉提及量的激增。给声量最大的账号建档,搞清楚是谁在带动对话。输入:一个关键词。输出:一条时间线加作者资料。端点:search-timeline、user-profile。

竞品与创作者研究

搜一个竞品名或垂类话题,收集反复出现的 screen_name,用 user-profile 给每个建档,做一个按粉丝数和活跃度排序的候选名单。输入:一个关键词。输出:排名的作者资料。端点:search-timeline、user-profile。

话题与情绪采样

按计划拉一个关键词的时间线,采样一个话题随时间是怎么被讨论的。因为每条推文带 text 和互动数,你可以把样本喂给模型做下游分类。输入:一个关键词。输出:一份时间线样本。端点:search-timeline。

实操要点

• 信封可能不同。 参考记录的是 outputs[0].data;两种结构都读(优先 output,回退 outputs[0].data)。
• 用游标翻页。 在还有更多结果时用 next_cursor 重发 search-timeline。
• 业务字段仅供观测。 把 timeline、screen_name、friends 之类当作观测到的、以真实响应核对。
• 仅公开、只读数据。 不发帖、不私信、不涉及私有/仅账号可见数据。用 SandBase API 密钥鉴权。
• 做个好客户端。 遇到 HTTP 429 等瞬时错误按退避重试;翻页而不是猛打。

常见问题

我需要 Twitter/X 开发者账号或登录吗? 不需要。你用自己的 SANDBASE_API_KEY 向 SandBase 鉴权。这些读取端点不需要你这边有 X 账号或 OAuth。

我怎么从一条推文找到它的作者? timeline 里每条推文带一个 screen_name;把它作为 username 传给 user-profile。

怎么翻更多推文? 搜索负载带一个 next_cursor;用它重发 search-timeline。确切参数对照参考核对。

我能读私有推文或私信吗? 不能。这套 API 只返回公开数据。私有和账号授权内容不在范围内。

小结

两个端点、一个信封、一个 screen_name 在步骤间流动——这就是整个关键词搜索循环。完整端点目录见 Twitter 公开数据 API 汇总页。准备好后:

• 获取 SandBase API 密钥
• 浏览 Twitter 端点
• 打开 search-timeline API 参考