Reddit Search API

Reddit Search

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

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.

1. Prepare one non-empty text query and choose an optional published_within window and results_limit.
2. POST the parameters to /v1/reddit/search and store the returned task_id.
3. Poll /v1/tasks/{task_id} until the task succeeds or returns a failure.
4. 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 true

Best 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