Threads User Posts
Threads User Posts 是从选定公开主页发现的内容，包含帖子正文、作者身份、媒体引用、发布时间和可见互动数量。这些记录与采集时间可用于账号内容归档、形式研究和公开互动比较。
主要特性
- 按主页控制发现范围接受一个或多个公开 Threads 主页 URL，并对每个主页分别应用 results_limit；默认值为 100，可设置为 1 到 2,000。
- 标准化帖子、作者与媒体记录以一致结构返回帖子 ID、来源 URL、正文、可用作者身份和公开媒体引用。
- 互动与发现上下文在来源提供时保留可见点赞数、评论数、转发数、分享数、发布时间、collected_at 和提交的主页上下文。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 必填的公开 Threads 主页 URL 列表，域名为 threads.com 或 threads.net，路径必须为 /@username；裸 username、帖子 URL 和其它路径会被拒绝。 |
results_limit | 可选 | 每个主页 URL 最多请求的帖子数；默认值为 100，可设置为 1 到 2,000 的整数。 |
如何使用
提交公开 Threads 主页 URL 和每个主页的结果上限，跟踪异步任务，再通过 cursor 分页读取标准化帖子。
- 准备一个或多个位于 threads.com 或 threads.net、路径为 /@username 的公开 Threads 主页 URL。
- 将 urls 和可选 results_limit POST 到 /v1/threads/user-posts，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
- 读取 data.results.items；has_more 为 true 时，使用返回的 next_cursor 请求下一页。
curl -X POST "https://api.socq.ai/v1/threads/user-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.threads.com/@example"],"results_limit":100}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor最佳使用场景
- 选定主页帖子数据集： 为一组明确的公开主页保留帖子 ID、来源 URL、正文、作者字段、媒体引用、时间和提交的主页上下文。
- 内容与形式研究： 结合帖子正文、公开媒体引用、作者归属和发布时间，研究所选主页中反复出现的主题与内容形式。
- 公开互动比较： 比较不同主页集合中的可见点赞数、评论数、转发数和分享数，并用 collected_at 标记每次观察时间。
使用建议
- 提交前将每个输入校验为 threads.com 或 threads.net 上路径为 /@username 的主页 URL，避免裸 username、帖子链接和其它路径导致请求失败。
- 按 urls 数量乘以 results_limit 规划请求深度和请求前 credits 预估，因为结果上限分别应用于每个主页。
- 将 discovery_input、input_url 和 collected_at 与每条结果一同保存，使下游记录保留输入主页和观察时间。
- 将正文、作者字段、媒体、created_at 和单项指标作为可空字段处理；响应不提供帖子子类型，因此不要推断记录是原创、回复、引用还是转发。
相关 API
需要其他类型的 Threads 公开数据时，可以使用以下 API。
- Threads Posts API — 从受支持的 Threads 帖子 URL 采集公开正文、作者信息、媒体、时间和可见互动指标。
- Threads Profiles API — 从受支持的 Threads 主页 URL 采集公开身份、简介、图片、网站、可见账号数量和采集上下文。