Reddit Subreddit Search
Searching within a designated subreddit isolates relevant conversations from wider platform noise. Scoped community searches return normalized post titles, body text, author handles, comment counts, upvotes, and media links.
Features
- Scoped community queryLimit keyword queries to specific /r/{subreddit} communities rather than querying the entire platform.
- Granular sort optionsSort matched posts by relevance, hot, top, new, or comment count to suit research requirements.
- Flexible timeframe filtersFilter results by hour, day, week, month, year, or all-time publication windows.
- Rich post detailsReceive normalized post records with title, body, author, upvote count, comment count, and permalinks.
Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | Search keyword query to execute inside the specified subreddit community. |
urls | Required | Array of public Reddit /r/{subreddit} URLs defining the community scope for the search. |
results_limit | Optional | Maximum number of posts to return per community; defaults to 100 with an allowed range of 1 to 2,000. |
sort_by | Optional | Ordering mode for matched posts: relevance (default), hot, top, new, or comments. |
published_within | Optional | Publication timeframe filter: all (default), year, month, week, day, or hour. |
How to Use
Submit a search query alongside target community URLs as an asynchronous task, then retrieve matched posts.
- Specify your search query and provide one or more /r/{subreddit} community URLs in urls.
- Optionally select sort_by (relevance, hot, top, new, comments) and published_within (hour to all).
- Send a POST request to /v1/reddit/subreddit-search with your SocQ API key.
- Poll /v1/tasks/{task_id} and paginate through data.results.items using next_cursor.
curl -X POST "https://api.socq.ai/v1/reddit/subreddit-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"AI agents","urls":["https://www.reddit.com/r/technology/"],"results_limit":20,"sort_by":"relevance"}'
# Poll GET /v1/tasks/{task_id}, then fetch data.results.items.Best Use Cases
- Community sentiment tracking: Monitor what members of dedicated tech, finance, or gaming subreddits are saying about your brand or competitors.
- Customer problem discovery: Search troubleshooting and question keywords within specialized product subreddits to find user pain points.
- Archival niche research: Retrieve historical top discussions on specific technical or cultural topics confined to authoritative communities.
Pro Tips
- Always supply full /r/{subreddit} URLs in the urls array; the backend extracts the community name automatically.
- Use this endpoint instead of Reddit Search when you need to avoid cross-community noise and focus on one subreddit.
- Sorting by comments helps identify high-engagement debate threads where community opinion is deeply expressed.
- Pair with Reddit Comments to pull the full comment tree from the most relevant posts discovered.
Related APIs
Use these APIs when you need a different type of public Reddit data.
- Reddit Posts API — Collect public post text, authors, community context, media, timestamps, and visible engagement from supported Reddit URLs.
- Reddit Comments API — Collect public comment text, authors, post and parent-comment references, community context, timestamps, and visible engagement from supported post URLs.
- Reddit Subreddit Posts API — Discover public posts from subreddit URLs with new, top, or hot sorting, a per-subreddit result limit, and normalized community and engagement context.
- Reddit Search API — Search public Reddit posts by text query and publication window, returning normalized content, authors, community context, timestamps, media, and visible engagement.
- Reddit Subreddit Details API