Instagram Search
Instagram Search 结果是与名称、关键词或主题匹配的公开主页，包含 username、简介、头像、认证与隐私状态以及可见账号信号。这些记录可用于创作者发现、品牌研究、受众筛选和主页资料补全。
主要特性
- 主页关键词搜索按关键词、handle、名称或账号短语搜索公开 Instagram 主页。
- 主页身份与计数在公开可见的前提下返回 username、显示名称、bio、主页 URL、头像、验证状态、隐私状态和可见计数。
- 一致的主页结构对宽泛关键词、名称和精确 handle 搜索返回一致的标准化主页结构。
- 请求结果上限使用 results_limit 设置每次搜索请求的主页记录上限。
- 公开数据边界响应范围不包含私密、受限、已删除或登录后才可见的主页数据。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 用于搜索的关键词、账号或资料短语。 |
results_limit | 可选 | 采集任务请求的最大记录数，必须为正整数。 |
如何使用
把主页搜索词作为异步任务提交，轮询 task ID，完成后再用 cursor 分页读取标准化主页结果。
- 准备一个非空的主页关键词、handle 或搜索短语。
- 向 /v1/instagram/search POST query 和可选的 results_limit。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded 或 failed。
- 通过 /v1/tasks/{task_id}?limit=50 读取 data.results，有更多主页时继续传 results.next_cursor。
curl -X POST "https://api.socq.ai/v1/instagram/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"sustainable travel","results_limit":25}'
# 轮询 GET /v1/tasks/{task_id}，再读取 /v1/tasks/{task_id}?limit=50，并使用 data.results。最佳使用场景
- 达人发现： 按关键词、handle、分类或活动短语查找相关公开主页，再做进一步补全。
- 账号补全： 为选中的搜索结果补全公开主页身份、bio、验证状态、隐私状态和可见计数字段。
- 品牌发现： 查找与名称、产品分类或市场短语相关的公开品牌和组织主页。
- 研究目录： 构建可审核的公开 Instagram 主页清单，用于研究、线索筛选或内部分析。
- 主页筛选流程： 选出相关主页后，再调用 Posts、Reels 或 Followers Count API 获取更深的公开记录。
使用建议
- 搜索流程里要把 429 当作常见压力信号处理，用 backoff 和更小的结果窗口，不要高频硬重试。
- 保存 task ID、稳定 profile ID、username 和标准 URL，方便搜索重放、追踪和审计。
- Search 适合发现主页；如果需要更深的帖子、Reels 或计数数据，再调用对应 API。
- 不要默认这个接口能读取私有、登录后可见或账号自有数据，除非公开 API 文档明确支持。
- 用户输入的搜索词进入生产管道前需要清洗和校验。
相关 API
需要其他类型的 Instagram 公开数据时，可以使用以下 API。
- Instagram Followers Count API — 获取公开账号身份以及可见粉丝数、关注数和帖子数。
- Instagram Posts API — 按 username 采集公开帖子、媒体、标签、提及、时间和互动指标。
- Instagram Reels API — 按 username 采集公开 Reels、媒体、音频、标签、提及和互动指标。
- 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 Reels Search API — 按文本 query 搜索公开 Reels，返回说明文字、创作者、媒体、时间、可见互动指标和查询上下文。
- Instagram Story Highlights API — 按 username 列出公开快拍精选容器，返回标题、所属账号、媒体数量和可复用的 highlight ID。
- Instagram Trending Reels API — 采集趋势信息流当前展示的公开 Reel，返回说明文字、创作者、媒体、时间和可见互动指标。