X Post Replies API

X Post Replies

主要特性

• 按已知帖子限定会话范围接收一个或多个 X 公开 status URL，提取每个数字帖子 ID，并在返回回复时排除提交的父帖本身。
• 回复与作者标准化记录为每条保存的回应返回回复 ID、规范 URL、正文、语言、发布时间和标准化公开作者身份。
• 公开回应信号将可见点赞、回复、转帖、引用、浏览和书签计数，与媒体、标签和提及放在同一条记录中。
• 可选择的时间线排序为所有提交帖子选择 relevance、latest 或 likes 排序，并分别对每个会话应用结果数量上限。
• 可追溯的会话信息在标准化信息中保留提交 URL、父帖 ID、会话 ID、回复目标、来源、引用、转帖和受限回复状态。

参数

如何使用

把已知公开帖子 URL 作为异步任务提交，再从完成的任务中读取标准化回复记录。

1. 准备一个或多个包含数字 /status/{id} 的公开 x.com 或 twitter.com URL，再选择 relevance、latest 或 likes 排序。
2. 将 urls、每帖 20 到 2000 且以 20 为步长的 results_limit 和 sort_by POST 到 /v1/x/post-replies。
3. 保留返回的 task_id，并在任务处于 queued、running 或 retrying 时轮询 GET /v1/tasks/{task_id}。
4. 任务成功后读取 data.results.items；当 data.results.has_more 为 true 时，把 data.results.next_cursor 作为 cursor 继续请求同一任务。

curl -X POST "https://api.socq.ai/v1/x/post-replies" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://x.com/OpenAI/status/1950240351547248941"],"results_limit":100,"sort_by":"relevance"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时把 data.results.next_cursor 作为 cursor 继续请求

最佳使用场景

• 公开回应分析： 结合选定父帖下的回复正文、语言、作者和可见互动，比较不同公开会话中的回应差异。
• 回复链还原： 使用 parent_post_id、conversation_id、in_reply_to 字段、回复 ID 和规范 URL，把保存的回应重新连接到可见会话关系。
• 跨次采集的回复监测： 针对一组稳定的帖子 URL，按不同采集批次记录回复发布时间、collected_at、作者和公开计数。
• 人工分流数据准备： 组合回复正文、作者身份、时间、URL 和可见互动，为下游人工查看队列准备回应记录。

使用建议

• 提交前检查每条 URL 是否使用受支持的 X 或 Twitter 主机名并包含数字 /status/ ID，避免把个人主页或搜索链接送入任务。
• 从 x.com 和 twitter.com 的不同 URL 写法中提取数字 status ID 并据此去重，因为不同链接字符串可能指向同一个父帖。
• 按每个父帖的需要以 20 为步长设置 results_limit；在会话结束和任务级去重前，总候选数可能接近 urls 数量乘以 results_limit。
• 根据采集目标选择 sort_by，但不要把 relevance、latest 与 likes 模式中的位置当作可横向比较的统一排名分数。
• 还原多个父帖会话时，应考虑任务级回复去重，因为同一条保存回复只会保留一组提交 URL 和父帖信息。
• 将较短或空结果视为公开可见性结果，并允许作者、媒体、指标和关系字段为空，不要自行补造占位值。

相关 API