Threads 公开数据 API | SandBase
用一个 REST API 读取 Threads 公开的资料、帖子、回复和搜索。无需 Threads 登录、无需 SDK——一个 SandBase 密钥,为 Agent 工作流而生。
Threads 是 Meta 增长迅猛的文字对话网络,它的公开资料、帖子和回复可以直接映射到品牌监测、创作者研究和社交聆听等场景。可要用程序去拿这些数据,通常意味着逆向 App、管理 token,而且 App 一变你就得重写一遍采集器。
SandBase 的 Threads 公开数据 API 免去了这些前置成本。它通过普通的 REST 端点读取 Threads 公开的资料、帖子、回复和搜索——只用一个 SandBase API 密钥,不需要登录 Threads、也不需要 SDK。端点 API 参考是每个参数和响应信封的权威来源;下面展示的业务载荷字段名只是一个示例结构、并非保证的 schema,请以你所调端点的一份真实响应为准核对。
这不是 Meta 官方的 Threads API。 当你需要已认证的会员操作、发帖,或需要有正式授权协议的数据时,请走 Meta 官方 API。当你的工作流需要用于研究和监测的公开、只读数据时,用 SandBase。想上手?获取 SandBase API 密钥,然后浏览 Threads 端点。
先说结论
- 一套 API 即可读取 Threads 公开的资料、帖子、回复、转发和搜索。
- 本文记录的 Model API 端点用
POST /v1/api/threads/<path>调用——只传该端点的参数,无 SDK,一个SANDBASE_API_KEY。- 端点以自然标识为入口:资料用
username,再用user-info返回的pk/id作为user_id去读帖子和回复,读评论则用post_id。- 只返回公开、只读数据。你这边无需发帖、无需平台登录、不涉及私有数据;用 SandBase API 密钥鉴权即可。
你需要哪种 Threads API?
| 你的需求 | 选择 | 原因 |
|---|---|---|
| 发帖、以会员身份操作,或使用账号授权数据 | Meta 官方 Threads API | 会员和账号级操作应通过 Meta 直接进行。 |
| 读取公开的资料、帖子、回复或搜索 | SandBase Threads 公开数据 API | 普通 REST、一个 SandBase 密钥、结构化 JSON,面向只读工作流。 |
| 私有或仅账号可见的数据 | 两种公开方案都不适用 | 这类数据不在本篇公开数据指南范围内。 |
Threads API 能取到什么
目录建立在一个 web 面上。按用途分组:
- 资料 — 按
username(或按 id)读取公开资料信息,含简介、粉丝数和认证状态。 - 帖子与回复 — 某用户的帖子、回复和转发,以及单条帖子的详情和它的评论。
- 搜索 — 资料搜索,以及按关键词的热门和最新帖子搜索。
可用性因端点而异,某些上游读取可能不稳定——请以每个端点的线上 API 参考为准,并在依赖某个具体端点前先确认其可用性。
SandBase 上的 Threads API 页面——带标签的概览和端点列表,每个端点都标了路径。
Threads 提供什么,SandBase 补什么
公开数据来自 Threads。SandBase 并不拥有或运营 Threads,它为符合条件的公开数据工作流提供一层统一的 API。每个能力都成为一个文档记录的端点,鉴权收敛为单个密钥,响应回来是可预测的 JSON——于是 Agent 可以沿着”读资料 → 读帖子 → 读某条帖子的评论”这一条约定链式调用,而不用维护采集器。
快速上手:第一次调用
SandBase 暴露不止一个 API 面。目录里可能显示 /apis/v1/... 下的 GET 路径;本文使用每个端点 API 参考上标注的带厂商前缀的 Model API 路径。不要擅自改动 HTTP 方法或 URL——以你所选端点的参考为准。
按用户名读取一个公开资料:
import os
import requests
resp = requests.post(
"https://api.sandbase.ai/v1/api/threads/web/user-info",
headers={
"Authorization": f"Bearer {os.environ['SANDBASE_API_KEY']}",
"Content-Type": "application/json",
},
json={"username": "zuck"},
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "completed":
error = body.get("error", {})
raise RuntimeError(error.get("message", "Threads 请求未完成"))
# 参考保证的是信封(id/status/model/outputs[0].data);
# 业务字段随端点而定,用防御式读取,
# 并以一份真实响应核对确切路径。
data = body["outputs"][0]["data"]
user = data.get("user", {})
print(user.get("full_name"), user.get("follower_count"), user.get("is_verified"))curl -X POST https://api.sandbase.ai/v1/api/threads/web/user-info \
-H "Authorization: Bearer $SANDBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username": "zuck"}'响应共用同一个信封:一个 id、一个 status、model 名称,以及——对 completed 运行而言——一个 outputs 数组,其唯一元素在 data 下承载数据。completed 运行才有 outputs;failed 或 timeout 的运行带 error、不含 outputs。这个信封才是端点参考所保证的;这里资料对象嵌在一个 user 键下,其中的操作字段按端点各自记录。读取 outputs[0].data 前先根据 status 分支判断,并查阅每个端点参考确认其运行模式(run mode)。下面是我实测的真实响应(测试于 2026-09-27(UTC))——字段名和取值会随时间变化,请对照真实响应核对:
{
"id": "77059cb9-8616-4be1-abfe-96e82a12b54f",
"status": "completed",
"model": "threads/web/user-info",
"outputs": [
{
"data": {
"user": {
"full_name": "Mark Zuckerberg",
"biography": "Mostly superintelligence and MMA takes",
"follower_count": 5744972,
"is_verified": true,
"bio_links": [],
"id": "63055343223",
"pk": "63055343223"
}
}
}
]
}failed 或 timeout 的运行会带 error,且不含 outputs。响应结构因端点而异——请检查一次真实响应,并逐端点确定精确的字段路径。
端点 API 参考是每个参数名和响应路径的事实来源。
能力地图
| 能力簇 | 代表端点 | 典型用途 |
|---|---|---|
| 资料 | threads/web/user-info | 按 username 的公开资料信号 |
| 帖子 | threads/web/user-posts | 按 user_id 读取某用户的帖子(可选 end_cursor) |
| 回复 | threads/web/user-replies | 按 user_id 读取某用户的回复(可选 end_cursor) |
| 帖子评论 | threads/web/post-comments | 按 post_id 获取互动与情感分析输入(可选 end_cursor) |
| 搜索 | threads/web/search-profiles | 按 query 做创作者与话题发现 |
分页方式因端点而异——若干端点接受每端点各自的游标请求参数。请查阅每个端点的结构,并在依赖某个端点前先确认它可用。
Threads 端点列表的一角,在 web 面上。
在 Agent 工作流中链式调用
因为本文记录的这些端点共享同一套鉴权和同一个响应信封,Agent 可以从一个资料一路走到一条帖子的评论,而不用为每个面单独写特例。一个常见的社交聆听模式是这样:
- 读资料。 用一个
username调用threads/web/user-info拿到简介、粉丝数、认证状态,以及该资料的pk/id。 - 读帖子。 把第 1 步拿到的
pk/id作为user_id(可选end_cursor分页)传给threads/web/user-posts,读该用户的近期帖子。先对照参考确认可用性——这个上游读取可能间歇不可用。 - 读评论。 用一个
post_id(可选end_cursor)调用threads/web/post-comments拿某条帖子的回复,收集互动输入。
每一步都返回相同的信封,所以你的 Agent 只需按 status 分支一次,并在每一步复用同一段读 JSON 的代码。completed 运行才有 outputs;failed 或 timeout 的运行带 error、不含 outputs。
常见用例
Threads 资料 API 做创作者研究
用一个 username 调用 threads/web/user-info 读取简介、粉丝数、认证状态和 bio 链接。输入:一个 username。输出:一条嵌在 user 下的资料记录。端点:user-info。
Threads 帖子 API 做内容监测
先用 threads/web/user-info(一个 username)解析资料拿到它的 pk/id,再读取 threads/web/user-posts 拿某用户的近期帖子。输入:一个 user_id(即 user-info 返回的 pk/id),外加可选的 end_cursor 分页。输出:一组帖子。端点:user-posts。在依赖它之前先对照参考确认可用性——这个上游读取可能间歇不可用。
Threads 搜索 API 做发现
用一个关键词调用 threads/web/search-profiles 浮现某垂类的创作者。输入:一个关键词。输出:匹配的资料。端点:search-profiles。
为什么放在 API 层来做
你当然可以用无头浏览器指向 Threads、解析 App 的负载,但这条路很脆:App 会变,token 会轮换,你维护的是采集器而不是在做产品。通过一层统一 API 来读,意味着你的代码依赖的是有名字的 JSON 字段和单个响应信封,而不是某个 App 内部实现。鉴权是一个密钥,而且因为本文记录的这些端点都返回相同的信封——completed 运行才有 outputs,而 failed 或 timeout 的运行带 error、不含 outputs——重试、日志和错误处理都可以收进一个你写一次、处处复用的辅助函数里。
正是这种一致性让工作流对 Agent 而言可组合。把一个 username 换成另一个,代码路径完全一样。再加第二个读取——比如某用户的回复——它也照样接在同一个判 status 的辅助函数后面。实际的收益是:你的时间花在”数据对你的研究意味着什么”上,而不是花在维持一个采集器去追一个移动靶。当你需要的不止是单次读取时,在线上列表里查到合适的端点,并在接入前确认它的参数——以及它当前的可用性。
局限与边界
- 仅公开、只读数据。 不发帖、不关注、不涉及私有或仅账号可见的数据。
- 速率与量级。 把响应当作尽力而为的读取;作为客户端侧的韧性措施,遇到 HTTP 429 或偶发的上游错误时按退避策略重试。
- 参数与结构随上游面而定。 标识各异:
user-info接一个username,user-posts/user-replies接一个user_id(即user-info返回的pk/id),post-comments接一个post_id,search-profiles接一个query;分页是每端点各自的end_cursor。资料负载嵌在user下。先看一次真实响应、读一遍结构。 - 以线上参考核对端点。 可用性和字段可能变化,某些帖子/搜索读取可能不稳定;在依赖某个具体端点前先确认。
- 这不是 Meta 官方合作。 SandBase 提供对公开数据的统一访问;请就你的使用场景遵守 Threads 条款和适用规则。
常见问题
我需要 Threads 或 Meta 登录吗?
不需要。你用自己的 SANDBASE_API_KEY 向 SandBase 鉴权。这些读取端点不需要你这边有 Threads 账号或 OAuth。
什么标识一个资料或一条帖子?
username 标识一个资料,供 user-info 使用,它会返回该资料的 pk/id。把这个值作为 user_id 传给 user-posts 和 user-replies。post_id 标识单条帖子的评论,供 post-comments 使用;search-profiles 则接一个 query。
为什么资料嵌在 user 下?
user-info 的负载把资料包在一个 user 对象里,含 full_name、biography、follower_count、is_verified 等字段。防御式读取 data["user"],并以真实响应核对字段。
我能读私有或仅账号可见的数据吗? 不能。这套 API 只返回公开数据。私有和账号授权内容不在范围内。
从读一个资料开始
创建一个 SandBase API 密钥,调用 user-info,在扩展到帖子、回复或搜索之前先检查返回的结构。准备好后: