X Post Retweeters API

X Post Retweeters

主要特性

• Status URL 解析接收公开 x.com 和 twitter.com status URL，并解析采集可见转发用户列表所需的数字帖子 ID。
• 标准化账号主页在字段可用时返回主页 ID、username、展示名称、规范主页 URL、简介、头像、封面和公开账号标记。
• 可见主页指标整理可用的粉丝数、关注数、帖子数、媒体数和点赞数，并附带账号创建时间与采集时间。
• 跨帖子唯一结果集按各自的数量上限遍历每个已提交帖子，再在完成的任务中仅保存一次相同的标准化主页。

参数

如何使用

将已知公开 status URL 提交为异步任务，轮询任务状态，再分页读取去重后的标准化主页结果。

1. 准备一个或多个公开 x.com 或 twitter.com URL，其路径需包含 /status/{数字帖子 ID}。
2. 向 /v1/x/post-retweeters POST urls，并设置 100 到 2,000 之间、以 100 为步进的 results_limit。
3. 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
4. 通过 /v1/tasks/{task_id}?limit=50 读取结果；results.has_more 为 true 时继续传入 results.next_cursor。

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

# 轮询 GET /v1/tasks/{task_id}
# 读取 GET /v1/tasks/{task_id}?limit=50，并继续使用 data.results.next_cursor

最佳使用场景

• 传播受众发现： 整理曾转发指定帖子的唯一公开账号目录，用于研究、审核或外联准备。
• 转发用户画像补全： 为传播数据集补充规范主页、简介、图片、公开账号标记、位置、网站和可见指标。
• 跨帖子受众重合分析： 当工作流需要按帖子归属或比较重合受众时，每个任务只提交一个来源帖子，再跨任务比较稳定的主页 ID。

使用建议

• 批量提交前先规范化 status URL，并按数字帖子 ID 去重；同一帖子使用不同 URL 形式时，输入校验不保证会将其合并。
• 将 results_limit 视为每个来源帖子的数量上限，而不是结果保证；公开可见性和实际分页范围都可能使结果更少。
• 需要来源归属时每个任务只提交一个 URL，因为标准化主页结果不会保留来源帖子 URL 或帖子 ID。
• 公开的 results.next_cursor 只用于翻阅已保存的标准化结果，应与采集过程中的内部分页分开处理。
• 跨任务合并数据时使用主页 ID 作为稳定键，并通过 collected_at 记录公开计数对应的观察时间。
• 客户端应允许主页字段为空并处理空结果，因为公开简介、图片、账号信号、计数或转发可见性可能不可用。

相关 API