Instagram Profiles API

Instagram Profiles

主要特性

• 已知 username 查询解析一个或多个已提交的公开 username，并为每个成功找到的账号最多生成一条标准化主页记录。
• 身份与主页链接返回账号 ID、username、显示名称、标准主页 URL、头像、简介、外部 URL 和公开简介链接。
• 账号分类与状态保留可见认证和隐私状态，以及公开分类、商业账号和专业账号标记。
• 可见主页计数在 metrics 中归集粉丝数、关注数和帖子数，并用 collected_at 标记标准化记录的采集时间。

参数

如何使用

把已知 username 作为异步任务提交，轮询 task ID，并使用 cursor 分页读取成功解析的公开主页记录。

1. 准备一个非空 usernames 数组，填入已经确认的公开账号名称。
2. 向 /v1/instagram/profiles POST usernames 数组，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到 status 变为 succeeded 或 failed。
4. 成功后读取 data.results.items；当 results.has_more 为 true 时继续传入 results.next_cursor。

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

# 轮询 GET /v1/tasks/{task_id}?limit=50
# 读取 data.results.items；results.has_more 为 true 时继续使用 results.next_cursor

最佳使用场景

• 已知账号资料补全： 为已有 Instagram username 的记录补充稳定 ID、显示名称、简介、头像、标准 URL 和公开链接。
• 指定账号对比： 在确定的 username 集合中比较可见认证、分类、账号类型标记以及粉丝数、关注数和帖子数。
• 主页快照监测： 重复采集时把 collected_at 与可见账号计数一并保存，用于比较不同时间点的主页记录。

使用建议

• 只提交 usernames，不要传主页 URL 或搜索短语，因为该接口仅接受 usernames 数组。
• 提交前移除前导 @ 并对结果 handle 去重，避免 name 和 @name 分别触发查询。
• 把返回 username 与输入列表核对；账号不存在、更名、不可用或无法访问时，可能不会生成主页记录。
• 保留缺失计数和账号标记的未知状态，不要擅自转换成 0 或 false。
• 比较重复采集的主页快照时，把 collected_at 与 metrics 一起保存。

相关 API