Reddit Subreddit Posts API

Reddit Subreddit Posts

Features

• Subreddit listing discoveryDiscover public posts from accepted /r/{subreddit} URLs and choose the new, top, or hot listing for every subreddit in the request.
• Per-subreddit collection depthApply results_limit separately to each submitted subreddit URL, with a default of 100 and an accepted range from 1 through 2,000.
• Normalized post content and authorsReturn post identifiers, source URLs, titles, body text, available author fields, and media references in a consistent record shape.
• Community and engagement contextKeep flair, community details, publication and collection times, upvotes_count, comments_count, upvote_ratio, and discovery_input with each post.

Parameters

How to Use

Submit public subreddit URLs with one listing mode and a per-subreddit result limit, then read the asynchronous task results with cursor pagination.

1. Prepare one or more public Reddit URLs whose path is /r/{subreddit}.
2. POST urls, results_limit, and sort_by to /v1/reddit/subreddit-posts, then store the returned task_id.
3. Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
4. Read data.results.items and request the returned next_cursor while has_more remains true.

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"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

Best Use Cases

• Community post monitoring: Collect the new listing and retain post IDs, created_at, collected_at, titles, and text to review recent public submissions across selected subreddits.
• Subreddit topic research: Group titles, body text, flair, and community fields to examine recurring subjects and formats within defined public communities.
• Aligned listing comparison: Use the same sort_by across subreddit URLs and compare publication times, upvotes_count, comments_count, and upvote_ratio under one listing mode.

Pro Tips

• Submit the canonical /r/{subreddit} home URL rather than a subreddit name, post URL, or deeper path so the request passes URL validation.
• Calculate requested depth as the number of urls multiplied by results_limit because the limit and credit estimate apply separately to each subreddit.
• Run separate tasks when comparing new, top, and hot because one sort_by value is applied to every subreddit URL in a request.
• Retain discovery_input and collected_at with each record so downstream datasets preserve the source subreddit and observation time.
• Allow author, media, flair, community, timestamp, and engagement fields to be null or empty when a public listing does not expose them.

Related APIs