Listings & Search

Search Posts

Full-text post search, optionally scoped to a subreddit. Advanced filters (score, comments, media, flags) are applied to the returned page and add a meta block (fetched / returned / filtered_out); paginate with after to filter more. Cost: $0.0015 per call.

get/api/reddit/search

Request

  • Base URL: https://api.redditapis.com
  • URL: https://api.redditapis.com/api/reddit/search
  • Auth: HTTP bearer

Query parameters

qstring required

Search query

subredditstring

Restrict to a subreddit

sortstring

relevance | new | hot | top | comments

tstring

hour | day | week | month | year | all

nsfwboolean

true = include NSFW results (Safe Search off)

limitinteger

Number of results to return, 1-100 (default 25)

afterstring

Pagination cursor. Pass back the after value from the previous response exactly as it was sent; it is opaque and carries your paging depth. When after comes back null there is no next page to request, but that does not always mean you have every item: Reddit often stops serving a busy listing long before it runs out, and it also caps any single listing at roughly 1000 items. The response says which happened in listing_status (complete, truncated, or unknown). Only complete means you have everything.

min_scoreinteger

Keep only posts with score >= this (applied to the returned page)

max_scoreinteger

Keep only posts with score <= this

min_commentsinteger

Keep only posts with comment count >= this

max_commentsinteger

Keep only posts with comment count <= this

is_videoboolean

true = only video posts, false = only non-video

is_selfboolean

true = only self/text posts, false = only link posts

over_18boolean

Filter the page by NSFW flag (distinct from nsfw, which controls inclusion in the search)

lockedboolean

Filter by the locked flag (true/false)

stickiedboolean

Filter by the stickied flag (true/false)

spoilerboolean

Filter by the spoiler flag (true/false)

contest_modeboolean

Filter by the contest_mode flag (true/false)

sort_typestring

Re-sort the filtered page (desc): score | num_comments | created

Response

Successful response.

afterstring nullable

Opaque pagination cursor; null when no next page is offered.

exhausted_reasonstring nullable

Present only when after is null: why the listing stopped.

listing_statusstring nullable

complete | truncated | unknown. Only complete means you have every item.

items_returnedinteger nullable

Running item count across the pages walked so far.

final_page_itemsinteger nullable

Items on the last page served.

hintstring nullable

Human-readable next step for this exhausted_reason.

metaobject nullable

Changes

No recorded changes to this operation across all 1 revision of this API.