X Followers List API

X Followers List

主要特性

• 多账号关注者采集在同一任务中提交一个或多个公开 X 用户名，每个值都可以带或不带开头的 @。
• 按用户名控制结果上限为每个用户名请求 200 到 2,000 条记录，步长为 200，默认值为 200。
• 标准化公开账号记录通过公开任务结果获得账号 ID、规范主页地址、作者身份、可见资料计数和标准化时间。
• 异步交付方式使用不透明游标轮询任务结果，或提供可选回调 URL 接收任务完成通知。

参数

如何使用

先启动关注者采集任务，等待任务完成，再分页读取已保存的公开账号记录。

1. 准备一个或多个公开 X 用户名，开头的 @ 可选。
2. 向 /v1/x/followers-list POST usernames 与有效的 results_limit，并保留返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务进入 succeeded 或 failed。
4. 任务成功后读取 data.results.items；has_more 为 true 时，把 next_cursor 继续传给任务端点。

curl -X POST "https://api.socq.ai/v1/x/followers-list" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["@X"],"results_limit":200}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor

最佳使用场景

• 建立受众研究样本： 采集所选 X 账号的公开关注者，并分析返回样本中的可见账号规模。
• 补全已知账号名录： 为下游账号记录补充规范 X 主页地址、显示身份、账号 ID 和可见计数。
• 创建可重复的关注者快照： 按相同上限定期执行采集，并保留任务时间，用于比较不同时点保存的公开账号集合。

使用建议

• 提交前先去重用户名，因为临时积分预估使用提交数组长度，而实际采集会规范化重复用户名。
• 把 results_limit 视为每个用户名的上限，而不是每个账号都一定能返回相同数量公开记录的保证。
• 使用每条结果的 id 作为稳定键；同一关注者即使出现在多个输入账号下，在同一任务内也只保存一次。
• 区分上游分页与结果读取；公开客户端只应使用 /v1/tasks/{task_id} 返回的不透明 next_cursor。
• 允许空结果和部分结果继续进入下游流程，因为账号不可用、访问受限或上游数据耗尽都可能缩短采集结果。

相关 API