Reddit Subreddit Posts API

Reddit Subreddit Posts

主要特性

• 发现 subreddit 列表帖子从受支持的 /r/{subreddit} URL 发现公开帖子，并为请求中的所有社区选择 new、top 或 hot 列表。
• 控制每个社区的采集深度results_limit 分别应用于每个提交的 subreddit URL，默认值为 100，可设置为 1 到 2,000。
• 标准化帖子内容与作者以一致结构返回帖子 ID、来源 URL、标题、正文、可用作者字段和媒体引用。
• 社区与互动上下文为每条帖子保留 flair、社区信息、发布时间、采集时间、upvotes_count、comments_count、upvote_ratio 和 discovery_input。

参数

如何使用

提交公开 subreddit URL，并指定一种列表排序和每个社区的结果上限，再通过 cursor 分页读取异步任务结果。

1. 准备一个或多个路径为 /r/{subreddit} 的公开 Reddit URL。
2. 将 urls、results_limit 和 sort_by POST 到 /v1/reddit/subreddit-posts，并保存返回的 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/subreddit-posts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.reddit.com/r/learnpython/"],"results_limit":100,"sort_by":"new"}'

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

最佳使用场景

• 监测社区新帖： 采集 new 列表并保留帖子 ID、created_at、collected_at、标题和正文，用于复核所选 subreddit 的近期公开投稿。
• 研究 subreddit 主题： 结合标题、正文、flair 和社区字段，分析明确公开社区中反复出现的主题与内容形式。
• 对齐比较社区列表： 对多个 subreddit URL 使用相同 sort_by，再结合发布时间、upvotes_count、comments_count 和 upvote_ratio 进行同排序比较。

使用建议

• 提交规范的 /r/{subreddit} 社区主页 URL，不要只填写社区名称、帖子 URL 或更深层路径，以免 URL 校验失败。
• 按 urls 数量乘以 results_limit 计算请求深度，因为结果上限和 credits 预估分别应用于每个 subreddit。
• 比较 new、top 和 hot 时分别提交任务，因为一次请求中的所有 subreddit URL 共用同一个 sort_by。
• 将 discovery_input 和 collected_at 与每条记录一同保存，以保留来源社区和观察时间。
• 公开列表未提供可用值时，作者、媒体、flair、社区、时间和互动字段可能为空，下游处理应允许缺失。

相关 API