Reddit Search
Reddit Search results are public posts matched to a text query, with titles, body text, authors, subreddit context, media, publication times, and visible voting and comment signals. These records support topic discovery, source review, time-window research, and engagement comparison across defined queries.
Features
- Query-driven post discoveryUse one non-empty text query to discover public Reddit posts without supplying post or subreddit URLs.
- Publication window filteringLimit discovery to the past hour, day, week, month, or year, or use all for the full supported time range.
- Bounded result requestsSet results_limit from 1 through 2,000 to control the maximum number of posts requested for the query.
- Normalized post and discovery contextReturn post content, author and community fields, media, timestamps, visible engagement, and the discovery input in a consistent record.
Parameters
| Parameters | Required | Description |
|---|---|---|
query | Required | Required non-empty text used to discover public Reddit posts. |
results_limit | Optional | Maximum posts to request. Defaults to 100 and accepts integers from 1 through 2,000. |
published_within | Optional | Publication window for matched posts. Defaults to all and supports hour, day, week, month, year, or all. |
How to Use
Submit a focused query with the desired time window and result cap, then read the normalized post records from the completed asynchronous task.
- Prepare one non-empty text query and choose an optional published_within window and results_limit.
- POST the parameters to /v1/reddit/search and store the returned task_id.
- Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
- Read data.results.items, then request the returned next_cursor while has_more remains true.
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"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueBest Use Cases
- Topic discussion discovery: Use post titles, body text, community names, and source URLs to find public discussions matching a defined subject.
- Source-traceable research datasets: Preserve post IDs, URLs, authors, publication times, and discovery_input so each collected record remains connected to its source and query.
- Time-window engagement comparison: Combine published_within with created_at, collected_at, upvotes_count, comments_count, and upvote_ratio to compare bounded result samples.
Pro Tips
- Use a focused query that represents one research question so matching post text and community context remain interpretable.
- Choose published_within for the period you need; leave it at all when a publication cutoff would remove relevant older posts.
- Treat results_limit as a request ceiling, then continue through task-result cursors until has_more is false to read every stored result.
- Deduplicate repeated searches by post ID while retaining extra.discovery_input and collected_at for query and observation context.
- Handle author, media, community, timestamp, and engagement fields as nullable because the public source may omit individual values.
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.