Instagram Hashtag Posts API

Instagram Hashtag Posts

主要特性

• 多 Hashtag 采集一次提交一个或多个带或不带 # 的 hashtag，results_limit 分别作用于每个提交的 hashtag。
• 时间与媒体筛选可限定最近一小时、一天、一周、一个月或一年，并选择全部帖子或只返回 Reels。
• 标准化帖子记录通过统一结构返回帖子 ID、shortcode、标准 URL、caption、作者信息、媒体引用、hashtag、mention 和时间。
• 来源与互动上下文每条记录保留产生该结果的提交 hashtag，以及可用的点赞、评论、观看和播放计数。

参数

如何使用

把 hashtag 作为异步任务提交，轮询 task ID，完成后再用 cursor 分页读取标准化帖子记录。

1. 准备一个或多个不重复的 hashtag，可带或不带开头的 #。
2. 向 /v1/instagram/hashtag-posts POST hashtags，以及可选的 results_limit、published_within 和 media_type。
3. 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
4. 通过 /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