Instagram Followers List API

Instagram Followers List

主要特性

• 多账号粉丝采集一次异步任务可提交一个或多个 Instagram username，并分别请求每个来源账号的粉丝资料。
• 标准化粉丝身份每条粉丝记录返回可用的资料 ID、username、显示名称、推导的主页 URL 和公开头像。
• 可见性与来源信号在来源暴露字段时保留认证、私密账号标记，以及来源 username 和 follower 关系。
• 观测列表上下文字段可用时保留列表 position 和 Actor scrapedAt 时间，否则使用 SocQ 采集时间。
• 按 username 控制结果量results_limit 分别作用于每个提交的 username，默认 100，可接受 1 至 2,000 的整数。

参数

如何使用

提交公开 Instagram username，跟踪异步任务，并在采集成功后分页读取标准化粉丝资料记录。

1. 准备一个或多个公开 Instagram username；可保留前导 @，采集前会自动移除。
2. 向 /v1/instagram/followers-list POST usernames 和可选的 results_limit，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 data.results.items，并在 has_more 为 true 时继续传 next_cursor。

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

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

最佳使用场景

• 公开受众抽样： 为选定公开账号构建有界样本，保留粉丝 username、显示名称、主页链接、可见性标记和观测位置。
• 跨账号重合检查： 按 extra.source_username 分组，并比较粉丝 ID 或 username，识别同时出现在多个来源账号下的资料。
• 资料补全队列： 筛选返回的 username，并在需要 bio 或可见资料计数字段时传给 Instagram Profiles。
• 关系列表快照： 保存粉丝身份、来源 username、观测位置和 collected_at，区分不同时点的公开列表样本。

使用建议

• 提交多个 username 时，用 username 数量乘以 results_limit 估算请求深度，因为上限和积分预估均按来源账号计算。
• 来源 username 带 @ 时可直接提交；provider 映射会在 Actor 运行前移除前导 @。
• 比较账号时保留 extra.source_username，因为同一粉丝资料可能出现在多个来源列表中，且不保证跨来源去重。
• position 字段存在时，把它当作一次观测到的列表值，不要解释成稳定排名或关系强度。
• 公开来源返回数量少于请求值时，保留部分结果及 collected_at；隐私、账号可用性、来源分页和 Actor 限制都可能减少输出。

相关 API