TikTok Followers List API

TikTok Followers List

主要特性

• 多账号采集一次提交一个或多个公开 username，并对每个账号分别应用 results_limit。
• 有界列表翻页在内部连续读取受支持的粉丝列表页面，直至达到单账号上限、下一页不可用或采集边界。
• 标准化资料记录以一致的 profile 结构返回粉丝 ID、username、显示名称、简介、头像引用、主页链接和支持的公开指标。
• 保留来源上下文在保留的粉丝记录中通过 extra.input_username 保存标准化后的提交账号。
• 任务级重复控制在保存和结果分页之前，按标准化 ID 或主页 URL 去除任务内重复的粉丝身份。

参数

如何使用

提交已知的公开账号，等待异步任务完成，再逐页读取已保存的资料记录。

1. 清理首尾空白，并在客户端去重前移除可选的 @ 前缀，选定公开 TikTok username。
2. 向 /v1/tiktok/followers-list POST usernames，以及 20 到 2,000 的单 username results_limit。
3. 保存 task_id 并轮询 /v1/tasks/{task_id}；queued、running 和 retrying 都是正常中间状态。
4. 任务成功后读取 data.results.items；当 has_more 为 true 时，向同一任务接口继续传入 next_cursor。

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

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

最佳使用场景

• 公开受众抽样： 构建有界的公开粉丝资料样本，用于定性受众研究。
• 创作者发现队列： 收集粉丝 username 和主页链接，作为人工筛选或后续 TikTok Profiles 资料补充任务的输入。
• 周期性列表研究： 按固定周期保存同一公开账号的时间戳样本，观察每次采集时可见身份的变化。
• 资料目录输入： 把公开粉丝列表条目转换为一致的身份、简介、头像和指标字段，供内部目录使用。

使用建议

• 先统一大小写并移除 @ 前缀再在客户端去重，否则 @name 和 name 可能触发等价的来源查询。
• 把 results_limit 视为单 username 上限；两个 username 使用默认值 100 时，预估结果是 200 条而不是 100 条。
• 保留 extra.input_username，但不要用此接口做精确共同粉丝分析，因为任务级去重只为每个粉丝身份保留一个来源上下文。
• 把返回账号传给接受 TikTok username 的接口时使用 username，而不是数字 id。
• 不要在新采集请求中提交 next_cursor；它只用于分页读取同一成功任务已保存的结果。
• 按可空字段处理 metrics，并把 created_at 视为 null，因为上游粉丝条目不一定提供这些数据。
• 私密、受限、不可用或超大账号可能返回少于上限的记录；头像引用也是可能失效的来源 URL。

相关 API