Instagram Reels Search
Instagram Reels 是公开短视频，包含说明文字、创作者身份、媒体、发布时间、来源产品类型和可见互动指标。这些内容与表现信号可用于主题监测、按查询研究、创作者梳理和对比分析。
主要特性
- 按文本查询发现 Reel通过一个有实际含义的搜索短语查找公开 Reels，无需先提供已知个人资料、hashtag、audio ID 或内容 URL。
- 控制发布时间范围需要限定内容新鲜度时，可只查找最近一小时、一天、一周、一个月或一年发布的结果。
- 内容与创作者记录用统一结构返回 Reel 身份、标准 URL、说明文字、作者信息、媒体引用、发布时间和可见互动指标。
- 限定数量并自动去重可请求 20 到 2,000 条记录，服务按稳定 Reel 标识去重，并在每条保存结果中保留来源 query。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 必填的非空文本，用于搜索 Instagram 当前公开的 Reel 结果。 |
results_limit | 可选 | 当前 query 请求的最大记录数；默认为 100，接受 20 到 2,000 的整数。 |
published_within | 可选 | 可选发布时间范围：hour、day、week、month 或 year。 |
如何使用
把 Reel 搜索作为异步任务提交，轮询 task ID，完成后通过 cursor 分页读取标准记录。
- 准备非空文本 query，并按需选择发布时间范围；results_limit 可设置为 20 到 2,000。
- 向 /v1/instagram/reels-search POST query，以及可选的 results_limit 和 published_within。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
- 通过 /v1/tasks/{task_id}?limit=50 读取 data.results.items，并在 results.has_more 为 true 时继续传 results.next_cursor。
curl -X POST "https://api.socq.ai/v1/instagram/reels-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"query\":\"$INSTAGRAM_REELS_QUERY\",\"results_limit\":20,\"published_within\":\"week\"}"
# 轮询 GET /v1/tasks/{task_id}，再读取 data.results.items，并继续传 results.next_cursor。最佳使用场景
- 构建按查询归集的 Reel 数据集： 把 Reel ID、URL、说明文字、媒体、作者和 extra.search_query 组合成一个可追溯的主题内容集合。
- 监测近期主题内容： 结合发布时间范围、created_at 和可见互动指标，查看固定 query 最近出现的 Reels。
- 发现主题相关创作者： 利用标准化作者 ID、username、名称和头像，梳理匹配 Reel 集合中出现的创作者。
- 比较内容表现形式： 对比同一 query 下各条 Reel 的说明文字、媒体元数据、来源产品类型和可见指标。
使用建议
- 使用聚焦且不只含空白字符的 query，让输入去除首尾空格后仍是有效搜索词。
- 比较多次运行结果时固定 query、published_within 和 results_limit，因为当前公开搜索结果会随时间变化。
- 合并结果页或多个任务时保留 extra.search_query 和稳定 Reel ID，以明确查询来源并继续去重。
- 下游代码应把说明文字、创作者字段、媒体、时间、产品类型和可见计数按可空值处理。
相关 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 Tagged Posts API — 按 username 采集标记指定主页的公开帖子，返回作者、媒体、提及、被标记用户上下文和互动指标。
- 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 Story Highlights API — 按 username 列出公开快拍精选容器，返回标题、所属账号、媒体数量和可复用的 highlight ID。
- Instagram Trending Reels API — 采集趋势信息流当前展示的公开 Reel，返回说明文字、创作者、媒体、时间和可见互动指标。
还可以将 Instagram 数据与其他已支持社交平台的公开数据结合使用。