Instagram Hashtag Posts
Instagram Hashtag Posts 是与搜索标签相关联的公开图片或 Reels，包含 caption、创作者身份、媒体、发布时间和可见互动。这些内容与来源信号可用于主题发现、跨标签对比、创作者研究和限定时间范围的监测。
主要特性
- 多 Hashtag 采集一次提交一个或多个带或不带 # 的 hashtag，results_limit 分别作用于每个提交的 hashtag。
- 时间与媒体筛选可限定最近一小时、一天、一周、一个月或一年，并选择全部帖子或只返回 Reels。
- 标准化帖子记录通过统一结构返回帖子 ID、shortcode、标准 URL、caption、作者信息、媒体引用、hashtag、mention 和时间。
- 来源与互动上下文每条记录保留产生该结果的提交 hashtag，以及可用的点赞、评论、观看和播放计数。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
hashtags | 必填 | 一个或多个非空 hashtag，可带或不带 #，多个值使用逗号或换行分隔。 |
results_limit | 可选 | 每个 hashtag 请求的最大记录数；默认为 100，接受 10 到 2,000 的整数。 |
published_within | 可选 | 可选发布时间范围：hour、day、week、month 或 year。 |
media_type | 可选 | 内容类型筛选；all 包含受支持的帖子类型，reels 只返回 Reels。 |
如何使用
把 hashtag 作为异步任务提交，轮询 task ID，完成后再用 cursor 分页读取标准化帖子记录。
- 准备一个或多个不重复的 hashtag，可带或不带开头的 #。
- 向 /v1/instagram/hashtag-posts POST hashtags，以及可选的 results_limit、published_within 和 media_type。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
- 通过 /v1/tasks/{task_id}?limit=50 读取 results.items，在 results.has_more 为 true 时继续传 results.next_cursor。
curl -X POST "https://api.socq.ai/v1/instagram/hashtag-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"hashtags":["travel","photography"],"results_limit":20,"published_within":"week","media_type":"all"}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items，并在 has_more 为 true 时继续传 next_cursor最佳使用场景
- 主题内容发现： 围绕活动、事件、社区或行业 hashtag 构建可审核的公开帖子数据集。
- 跨 Hashtag 对比： 在保留每条记录来源 hashtag 的同时，对比不同标签下的可见互动和内容模式。
- 近期 Reels 监测： 组合发布时间范围和 Reels 筛选，查看选定 hashtag 下近期出现的短视频内容。
- 创作者与内容补全： 把帖子身份、作者上下文、caption、媒体和可见指标合并到研究、活动或审核记录中。
使用建议
- 先对输入 hashtag 去重，并为同一主题统一拼写；采集器会分别处理每个提交值。
- 按 hashtag 规划数据量，因为 results_limit 作用于每个 hashtag，而不是整次请求。
- 固定周期监测需要一致的时间范围和内容类型时，同时设置 published_within 与 media_type。
- 用稳定帖子 ID、shortcode 或标准 URL 合并重叠结果，同时保留 extra.hashtag 追溯来源。
- 把媒体、计数、发布时间等公开字段按可选值处理，因为不同帖子暴露的字段可能不同。
相关 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 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 Reels Search API — 按文本 query 搜索公开 Reels，返回说明文字、创作者、媒体、时间、可见互动指标和查询上下文。
- Instagram Story Highlights API — 按 username 列出公开快拍精选容器，返回标题、所属账号、媒体数量和可复用的 highlight ID。
- Instagram Trending Reels API — 采集趋势信息流当前展示的公开 Reel，返回说明文字、创作者、媒体、时间和可见互动指标。