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 密钥鉴权即可。
当前范围:资料或候选搜索
2026-11-08 本次修订通过免费 inspect 与当前公开参考样本,核对了 threads/web/user-info、threads/web/search-profiles,没有执行付费业务请求。后面的能力地图保留作导航;帖子、回复及其标识与分页不在本轮复验范围。
已知用户名就读取一个 user 对象;搜索词则返回 xdt_api__v1__users__search_connection.edges[].node 下的候选。当前两个请求 schema 都没有 page、cursor、end_cursor 或 limit。创作者研究教程提供完整的单次 Python helper,以及已有 Key、已连接 agent、新项目的接入方式,不自动选首条,也不把缺粉丝数补为零。
你需要哪种 Threads API?
| 你的需求 | 选择 | 原因 |
|---|---|---|
| 发帖、以会员身份操作,或使用账号授权数据 | Meta 官方 Threads API | 会员和账号级操作应通过 Meta 直接进行。 |
| 读取公开的资料、帖子、回复或搜索 | SandBase Threads 公开数据 API | 普通 REST、一个 SandBase 密钥、结构化 JSON,面向只读工作流。 |
| 私有或仅账号可见的数据 | 两种公开方案都不适用 | 这类数据不在本篇公开数据指南范围内。 |
Threads API 能取到什么
目录建立在一个 web 面上。按用途分组:
- 资料 — 按
username(或按 id)读取公开资料信息,含简介、粉丝数和认证状态。 - 帖子与回复 — 某用户的帖子、回复和转发,以及单条帖子的详情。
- 搜索 — 资料搜索,以及按关键词的热门和最新帖子搜索。
可用性因端点而异,某些上游读取可能不稳定——请以每个端点的线上 API 参考为准,并在依赖某个具体端点前先确认其可用性。
历史截图,2026-09-27。SandBase 上的 Threads API 页面——带标签的概览和端点列表,每个端点都标了路径。
Threads 提供什么,SandBase 补什么
公开数据来自 Threads,SandBase 不拥有或运营 Threads,而是为合资格的公开数据工作流提供统一鉴权入口。每追加一步,仍要分别检查参数、业务结构、可用性和预算。当前教程只核对了资料、候选搜索的独立首次请求契约,没有验证资料到帖子再到详情的链路。
快速上手:读取一个已知账号
本地配置 SANDBASE_API_KEY,使用 Model API POST 路由,不替换成目录 GET 路径。当前资料请求只有一个必填输入:username。
curl --fail-with-body --connect-timeout 10 --max-time 90 \
-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": "nasa"}'命令只打印响应,不检查业务是否完成。使用前必须确认 status: "completed"、outputs[0].data 是对象,且有非空 user 对象。资料缺失、为 null 或空对象都应报错,不跳过,也不转换成零粉丝。链接中的教程实现了这些检查、超时与 JSON 错误处理,不自动重试;可选字段保持原样,也不套参考中没有的 code0 或 success 标记规则。
2026-11-08 免费 inspect 显示,资料 $0.002/次、资料搜索 $0.003/次,均符合组织每天 100 次合资格数据 API 共享额度,00:00 UTC 重置。本次没查剩余额度,符合资格不代表下次一定免费。
历史资料响应:2026-09-27
下面保留原 zuck 查询、run 77059cb9-8616-4be1-abfe-96e82a12b54f 的完整原文 JSON,作为历史证据,不是今天的粉丝数或本次执行。旧 Python 示例已经归档,当前教程取代了静默处理缺失 user 的写法。
{
"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"
}
}
}
]
}一份成功的历史资料响应不能验证另一个端点。当前搜索是 connection/edges/node 结构,不是资料的 user 路径;运行状态与所选业务结构都要检查。
历史截图,2026-09-27。端点 API 参考是每个参数名和响应路径的事实来源。
能力地图
这张导航表保留自旧文(发布于 2026-09-27,上次更新于 2026-10-01)。下列帖子、回复和详情输入属于历史指导,不是 2026-11-08 资料/搜索修订中重新验证的参数。
| 能力簇 | 代表端点 | 典型用途 |
|---|---|---|
| 资料 | threads/web/user-info | 按 username 的公开资料信号 |
| 帖子 | threads/web/user-posts | 按 user_id 读取某用户的帖子(可选 end_cursor) |
| 回复 | threads/web/user-replies | 按 user_id 读取某用户的回复(可选 end_cursor) |
| 帖子详情 | threads/web/post-detail | 按数字 post_id 读取单条帖子 |
| 搜索 | threads/web/search-profiles | 按 query 做创作者与话题发现 |
分页方式因端点而异——若干端点接受每端点各自的游标请求参数。请查阅每个端点的结构,并在依赖某个端点前先确认它可用。
历史 user-posts 参数参考,2026-09-27。这是独立端点,不是端点列表截图;当前行为不在本次复验范围。
扩展任务前先确认对象
已经确认的 handle 与查询词是两种输入。搜索给的是候选,不是权威的账号选择;追加请求前先核对用户名与目标身份。本次流程只做所选的一条请求,资料接帖子需要单独检查契约和预算。共用鉴权不代表业务载荷、可用性都相同。
常见用例
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。
让观察值与未知值分开
结构化资料的前提是缺失信息仍然可见。没有粉丝数不等于零,没有认证标记不等于 false;即使给了粉丝数,也不能直接衡量帖子触达或受众质量。做比较表之前,先保留读取日期和未知字段。
当前搜索样本在每个 node 中给出身份字段,没有保证每个候选都提供粉丝数。不要把结果直接交给假设这些指标存在的排序函数,也不要自动逐个查资料填空。选择继续研究谁,应当是下一项独立任务。
局限与边界
- 仅公开、只读数据。 不发帖、不关注、不涉及私有或仅账号可见的数据。
- 速率与量级。 首次请求示例遇错就停止。先查鉴权、计费或限流上下文,再决定是否另行尝试;不包含自动重试或批量循环。
- 参数与结构随上游面而定。 标识各异:
user-info接一个username,user-posts/user-replies接一个user_id(即user-info返回的pk/id),post-detail接一个数字post_id,search-profiles接一个query;部分历史帖子/回复接口使用end_cursor,当前检查的资料与搜索 schema 没有分页字段。资料位于user,搜索则是 connection/edges/node 结构。先看一次真实响应、读一遍结构。 - 以线上参考核对端点。 可用性和字段可能变化,某些帖子/搜索读取可能不稳定;在依赖某个具体端点前先确认。
- 这不是 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-detail 使用;search-profiles 则接一个 query。
为什么资料嵌在 user 下?
user-info 的负载把资料包在一个 user 对象里,含 full_name、biography、follower_count、is_verified 等字段。防御式读取 data["user"],并以真实响应核对字段。
我能读私有或仅账号可见的数据吗? 不能。这套 API 只返回公开数据。私有和账号授权内容不在范围内。
从读一个资料开始
复用已有连接,选择一次已知账号查询或候选搜索。创作者研究教程提供带检查的实现。准备好后:
觉得有用?分享给更多人