Instagram Tagged Posts API

Instagram Tagged Posts

主要特性

• 按主页标记发现帖子把公开 Instagram username 作为目标，返回标记这些主页的帖子，而不是目标账号自己发布的帖子。
• 帖子与作者身份返回帖子 ID、shortcode、来源 URL、caption 和标准化作者主页字段，形成可追溯的内容记录。
• 被标记用户与提及上下文同时保留结构化 tagged_users、hashtag 和 caption mention，便于区分帖子中的不同关系。
• 媒体与可见互动为每条公开帖子返回标准化图片或视频引用，以及来源提供的可见点赞、评论、观看和播放数。
• 发布时间上下文包含标准化发布时间、采集时间和 product_type 上下文，支持按时间审查和帖子格式分类。

参数

如何使用

把目标主页 username 作为异步任务提交，轮询返回的 task ID，再通过 cursor 分页读取标准化标记帖子。

1. 准备一个或多个不带 @ 前缀的公开 Instagram username。
2. 向 /v1/instagram/tagged-posts POST usernames，以及 1 到 2,000 之间的可选 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/instagram/tagged-posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["instagram"],"results_limit":20}'

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

最佳使用场景

• 主页标记监测： 结合 tagged_users、帖子 URL、caption、作者和时间，审查标记指定主页的公开帖子。
• 活动关联审查： 比较与活动主页标记相关帖子的 caption、媒体、被标记用户上下文和可见互动。
• 创作者内容研究： 利用标准化作者身份和主页标记关系，识别围绕指定账号发布公开内容的创作者。
• 标记内容归档： 把帖子 ID、shortcode、规范 URL、媒体引用、发布时间和采集时间保存为可审查的内容记录。

使用建议

• 提交前移除每个目标 username 的 @ 前缀，让请求使用清晰的主页标识。
• 使用 extra.tagged_users 判断帖子级主页标记，使用 mentions 读取返回的提及字符串，不要把两个字段混为一类。
• 跨批次采集时用帖子 ID 或 shortcode 去重，并保留返回的帖子 URL 以便审查和追溯。
• 允许媒体、互动计数、作者标记和时间为空，因为标准化公开记录会保留来源字段的可空性。
• 当 results.has_more 为 true 时继续传入 results.next_cursor，避免较大的标记帖子结果集在第一页后被截断。

相关 API