Search Reddit

Search Reddit by keyword, optionally scoped to a single subreddit. Results are returned in Reddit's relevance order.

GET /v1/reddit/search

Reddit search operators

Unlike Instagram/TikTok, Reddit search does support a few field operators — e.g. title:, selftext:, author:, subreddit:, and quoted "exact phrases". Plain keywords work too (e.g. teeth whitening).

Query parameters

Parameter	Type	Default	Description
query	string	—	Required. Keyword(s), e.g. teeth whitening or title:"electric car".
subreddit	string	(none)	Restrict to one subreddit (name without r/), e.g. Switzerland.
sort	string	relevance	Sort order: relevance, hot, top, new, comments.
time_filter	string	all	Time window for top/relevance: all, year, month, week, day, hour.
max_pages	integer	1	Number of Reddit listing pages to fetch. Maximum 100.

Pagination follows Reddit's after cursor: each page returns up to 100 posts, deduplicated across pages, in Reddit's own order. Fewer pages come back if Reddit has no more results.

Examples

Basic keyword search:

curl -G "$LISTENX_BASE/v1/reddit/search" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'query=teeth whitening'

Scoped to a subreddit, newest first, three pages:

curl -G "$LISTENX_BASE/v1/reddit/search" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'query=health insurance' \
  --data-urlencode 'subreddit=Switzerland' \
  --data-urlencode 'sort=new' \
  --data-urlencode 'max_pages=3'

Top posts of the past year using an operator:

curl -G "$LISTENX_BASE/v1/reddit/search" \
  -H "X-API-Key: $LISTENX_KEY" \
  --data-urlencode 'query=title:"electric car"' \
  --data-urlencode 'sort=top' \
  --data-urlencode 'time_filter=year'

Response

{
  "query": "health insurance",
  "subreddit": "Switzerland",
  "sort": "new",
  "time_filter": "all",
  "pages_requested": 3,
  "pages_fetched": 3,
  "returned": 247,
  "results": [
    {
      "id": "1n8xyz",
      "fullname": "t3_1n8xyz",
      "type": "text",
      "title": "Best health insurance for expats?",
      "selftext": "Just moved to Zurich and…",
      "url": "https://www.reddit.com/r/Switzerland/comments/1n8xyz/best_health_insurance_for_expats/",
      "permalink": "https://www.reddit.com/r/Switzerland/comments/1n8xyz/best_health_insurance_for_expats/",
      "subreddit": "Switzerland",
      "subreddit_prefixed": "r/Switzerland",
      "subreddit_subscribers": 512300,
      "author": "expat_zrh",
      "author_fullname": "t2_abc123",
      "author_flair_text": null,
      "link_flair_text": "Question",
      "created_at": "2025-09-10T08:14:03+00:00",
      "edited_at": null,
      "over_18": false,
      "spoiler": false,
      "stickied": false,
      "locked": false,
      "is_original_content": false,
      "domain": "self.Switzerland",
      "thumbnail": null,
      "engagement": {
        "score": 128,
        "ups": 128,
        "downs": 0,
        "upvote_ratio": 0.94,
        "num_comments": 73,
        "num_crossposts": 0,
        "total_awards_received": 1
      }
    }
  ],
  "billing": {
    "endpoint": "reddit.search",
    "units": 3,
    "unit_price": "0.002000",
    "amount": "0.006000",
    "balance_after": "97.240000",
    "request_id": "…"
  }
}

Fields

Field	Description
subreddit	The subreddit you scoped to, or null for a site-wide search.
sort	The sort order used.
time_filter	The time window used.
pages_requested	The max_pages you asked for.
pages_fetched	Reddit pages actually fetched (also the number of billed units).
returned	Number of posts in results (deduplicated across pages).
results[]	Post records, in Reddit's order.

Billing

Search is billed per page fetched — units = pages_fetched, minimum 1. So max_pages=3 costs up to 3 units (fewer if Reddit runs out of pages sooner). See Billing.

Notes

• To pull the full comment tree for a result, call the thread endpoint with its id.
• Reddit search is a discovery surface; results are not exhaustive and can shift over time.