Reddit Search API

Reddit Search

主要特性

• 由 query 驱动的帖子发现使用一个非空文本 query 发现公开 Reddit 帖子，无需预先提供帖子或 subreddit URL。
• 发布时间窗口过滤可将发现范围限定为过去一小时、一天、一周、一个月或一年，也可使用 all 覆盖支持的完整时间范围。
• 可控的结果请求上限将 results_limit 设置为 1 至 2,000，控制本次 query 请求的最大帖子数量。
• 标准化帖子与发现上下文以一致结构返回帖子内容、作者与社区字段、媒体、时间、可见互动指标和发现输入。

参数

如何使用

提交聚焦的 query、所需时间窗口和结果上限，再从完成的异步任务中读取标准化帖子记录。

1. 准备一个非空文本 query，并按需选择 published_within 和 results_limit。
2. 将参数 POST 到 /v1/reddit/search，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或返回失败。
4. 读取 data.results.items；has_more 为 true 时继续使用返回的 next_cursor。

curl -X POST "https://api.socq.ai/v1/reddit/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"machine learning","results_limit":100,"published_within":"month"}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；has_more 为 true 时继续使用 next_cursor

最佳使用场景

• 发现主题讨论： 结合帖子标题、正文、社区名称和来源 URL，查找与明确主题匹配的公开讨论。
• 构建可追溯研究数据集： 保留帖子 ID、URL、作者、发布时间和 discovery_input，使每条采集记录都能关联到来源与 query。
• 比较时间窗口内的互动： 结合 published_within、created_at、collected_at、upvotes_count、comments_count 和 upvote_ratio，比较限定范围的结果样本。

使用建议

• 让一个 query 对应一个明确研究问题，便于解释匹配到的帖子正文和社区上下文。
• 按所需周期选择 published_within；如果发布时间限制会遗漏相关旧帖，则保留默认值 all。
• 将 results_limit 视为请求上限，并持续读取任务结果 cursor，直到 has_more 为 false，避免遗漏已保存结果。
• 重复搜索时按帖子 ID 去重，同时保留 extra.discovery_input 和 collected_at，记录 query 与观察时间。
• 按可空字段处理作者、媒体、社区、时间和互动指标，因为公开来源可能缺少个别值。

相关 API