Instagram Tagged Posts
Instagram Tagged Posts 是通过帖子内标记指向其他主页、并可能包含 mention username 的公开内容，包含 caption、作者、媒体、hashtag、发布时间和可见互动。内容字段与关系信号可以支持主页标记监测、关联审查、创作者研究和结构化内容归档。
主要特性
- 按主页标记发现帖子把公开 Instagram username 作为目标，返回标记这些主页的帖子，而不是目标账号自己发布的帖子。
- 帖子与作者身份返回帖子 ID、shortcode、来源 URL、caption 和标准化作者主页字段，形成可追溯的内容记录。
- 被标记用户与提及上下文同时保留结构化 tagged_users、hashtag 和 caption mention，便于区分帖子中的不同关系。
- 媒体与可见互动为每条公开帖子返回标准化图片或视频引用，以及来源提供的可见点赞、评论、观看和播放数。
- 发布时间上下文包含标准化发布时间、采集时间和 product_type 上下文，支持按时间审查和帖子格式分类。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
usernames | 必填 | 一个或多个不带 @ 的公开 Instagram 主页 username，多个值使用逗号或换行分隔。 |
results_limit | 可选 | 任务请求的最大标记帖子记录数，取值为 1 到 2,000 的整数，默认 100。 |
如何使用
把目标主页 username 作为异步任务提交，轮询返回的 task ID，再通过 cursor 分页读取标准化标记帖子。
- 准备一个或多个不带 @ 前缀的公开 Instagram username。
- 向 /v1/instagram/tagged-posts POST usernames，以及 1 到 2,000 之间的可选 results_limit。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
- 通过 /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
需要其他类型的 Instagram 公开数据时，可以使用以下 API。
- Instagram Followers Count API — 获取公开账号身份以及可见粉丝数、关注数和帖子数。
- Instagram Posts API — 按 username 采集公开帖子、媒体、标签、提及、时间和互动指标。
- Instagram Reels API — 按 username 采集公开 Reels、媒体、音频、标签、提及和互动指标。
- Instagram Search API — 按关键词或账号名称搜索公开主页及可见账号信息。
- Instagram Comments API — 从帖子 URL 采集公开评论、作者、时间、点赞数和回复数。
- Instagram Profiles API — 按 username 获取公开主页身份、简介、链接、账号标记、分类和可见计数。
- Instagram Followers List API — 采集公开粉丝资料记录，并保留来源账号和关注关系上下文。
- Instagram Following List API — 采集 Instagram 账号公开可见的关注主页，返回身份、关注关系上下文和可见账号计数。
- Instagram Hashtag Posts API — 按 hashtag 发现公开帖子，返回来源标签、媒体、创作者、时间和可见互动指标。
- Instagram Transcript API — 从公开 Post 或 Reel URL 提取字幕文本、语言、格式、来源 URL 和 shortcode。
- Instagram Audio Reels API — 按已知数字 audio ID 采集公开 Reels，返回说明文字、创作者、媒体、时间、可见互动和来源音频上下文。
- Instagram Highlight Items API — 通过已知 highlight ID 获取保存的公开 Story 内容，返回文本、作者身份、媒体、时间、可见指标和来源上下文。
- Instagram Post Info API — 通过已知公开帖子、Reel 或旧版 IGTV URL 查询说明文字、作者身份、媒体、时间、可见互动和输入上下文。
- Instagram Reels Search API — 按文本 query 搜索公开 Reels，返回说明文字、创作者、媒体、时间、可见互动指标和查询上下文。
- Instagram Story Highlights API — 按 username 列出公开快拍精选容器，返回标题、所属账号、媒体数量和可复用的 highlight ID。
- Instagram Trending Reels API — 采集趋势信息流当前展示的公开 Reel，返回说明文字、创作者、媒体、时间和可见互动指标。