Reddit Search API - Find Posts by Keyword

Posts matching a keyword — globally or within a subreddit

Search Reddit posts by keyword. Optionally narrow to a specific subreddit. Results include title, score, comment count, author, and permalink.

POST /search Search
https://api.fetchlayer.dev/reddit/search
OpenAPI JSON

Headers

Authorization string required

Bearer token — your FetchLayer API key.

Parameters

query string required

Search keyword or phrase.

subreddit string | null optional

Limit search to a specific subreddit.

sort string optional

Sort order: relevance, new, comments, top or hot. (default: relevance)

limit integer optional

Maximum number of results to return. With the default `pages: 1`, a request returns at most one page of results, which can be fewer than `limit`. (default: 25)

time string | null optional

Time filter: hour, day, week, month, year, or all.

pages integer optional

How many pages of results to return, at most. A page holds as many results as Reddit shows on it (often 7 to 25), so a larger `limit` needs `pages` above 1 to be filled. When the pages run out before `limit` and more results remain, `notes` says so and `nextCursor` continues. Each page is billed as one, so the credits a request costs equal the pages it actually returns (see `pagesScraped` in the response). (default: 1)

after string optional

Continue where a previous response stopped: pass its nextCursor. Use the same query, subreddit, sort and time.

include string[] optional

Extra fields per post: ["body"] adds the full body of each text post as bodyText, bodyHtml and bodyMarkdown. Off by default: it adds about 1–2 seconds when a few results are text posts, and up to about 20 when all of them are. ["media"] adds media[] to each post, in display order: images, gallery slides with captions, videos with a still (poster), link preview images, with sizes, plus blurredUrl for NSFW or spoiler media. Same price as without it.

Response Fields

search

Posts matching a keyword — globally or within a subreddit

requestedUrl string

The Reddit URL the request was for.

finalUrl string

Final URL after redirects.

listingType string

Always search for a successful response.

query string

Search query.

sort string

Applied sort order.

time string | null

Applied time filter.

subredditFilter string | null

Applied subreddit filter.

resultCountText string | null

Result count text displayed by Reddit.

items[].id string | null

Reddit post ID without the t3_ prefix.

items[].fullname string | null

Reddit post fullname, including the t3_ prefix.

items[].subreddit string | null

Subreddit name without the r/ prefix.

items[].subredditPrefixed string | null

Subreddit name with the r/ prefix.

items[].author string | null

Author username.

items[].title string | null

Post title.

items[].permalink string | null

Absolute URL of the Reddit comments page.

items[].shortlink string | null

Short redd.it URL for the post.

items[].url string | null

Absolute post content URL.

items[].domain string | null

Hostname or Reddit domain associated with the post.

items[].createdAt string | null

ISO 8601 creation timestamp.

items[].flair string | null

Post flair text, or null when absent.

items[].score number | null

Post score.

items[].scoreText string | null

Score text as displayed by Reddit.

items[].commentCount number | null

Comment count.

items[].commentCountText string | null

Comment count text as displayed by Reddit.

items[].previewText string | null

Text preview for self posts, or null when unavailable.

items[].thumbnailUrl string | null

Post thumbnail URL, or null when unavailable.

items[].nsfw boolean

Whether the post is marked NSFW.

items[].spoiler boolean

Whether the post is marked as a spoiler.

items[].locked boolean

Whether the post is locked.

items[].stickied boolean

Whether the post is stickied.

items[].removed boolean | null

true when the post has been removed or deleted, false when it is live, null when its status could not be read for this response (notes says how many). Reddit leaves removed posts out of this listing, so a listed post is false; null appears only when its status could not be read.

items[].removedByCategory string | null

Almost always null: Reddit leaves removed posts out of this listing. When removed is true (rare), the same values as the post route.

listingTitle string | null

Display title of the listing, or null when unavailable.

itemCount number

Number of entries returned in items.

nextPageUrl string | null

The next page’s address, or null at the end. On endpoints that take `after` it is an api.fetchlayer.dev address: POST it with your key to get the next page (a body is optional; fields you send override the address), or pass its `after` parameter as `after`.

prevPageUrl string | null

The previous page’s address (its `before` parameter is the cursor), or null.

pagesRequested number

Number of pages requested.

pagesScraped number

Pages of results returned. This is what the request is billed at: 1 credit per page actually returned, never per page requested.

scrapedAt string

ISO 8601 time the result was produced.

transport string

The data source: always the platform id, "reddit".

notes string[]

Caveats about this result, for example how many posts had a removal status that could not be checked.

items[].authorId string | null

The author’s account id (t2_…), which stays the same if the username changes.

items[].subredditId string | null

The subreddit’s id (t5_…).

items[].numCrossposts integer | null

Exact number of crossposts; null when it could not be checked.

items[].postType string | null

What kind of post it is: text, link, image, video or gallery; null when not known. Only text posts have a body.

items[].media object[] | null

Only with include ["media"]. The post's media, in display order. null for a text post, a removed post, or a post whose media could not be read on that request; notes says how many. Image and gallery originals (i.redd.it) are stable addresses. Preview and poster addresses (preview.redd.it, external-preview.redd.it) can expire or change, so **download them rather than linking to them long-term.**

items[].media[].kind string

image, gallery_item (one slide of a gallery, in Reddit's order), video, or link_preview (a link post's preview image).

items[].media[].url string

The real, unblurred media. Reddit-hosted video has no single MP4 with audio: url is the video's HLS streaming playlist (.m3u8, audio and video together, playable by HLS players such as ffmpeg, VLC or hls.js). Embedded videos (for example Streamable or YouTube) point to the provider's page.

items[].media[].width number | null

Width in pixels; null when not known.

items[].media[].height number | null

Height in pixels; null when not known.

items[].media[].caption string | null

gallery_item only: the slide's caption, null when it has none.

items[].media[].poster object | null

video only: a still image of the video, { url, width, height }.

items[].media[].blurredUrl string | null

Reddit's blurred version of an NSFW or spoiler post's media, when Reddit provides one; otherwise null. The post keeps its nsfw and spoiler flags; url is always the real media.

items[].linkUrl string | null

What a non-text post points to: the external site, the image, video or gallery, or a crosspost’s original. Null for a text post. url is unchanged.

nextCursor string | null

Pass as after to continue exactly where this response stopped, even partway through a page; null at the end.

items[].bodyText string | null

Only with include ["body"]: the full body of a text post as plain text. Null when postType is not text. For a text post, null means a title-only post with no body text, or — when a note says so — a body that could not be returned this time.

items[].bodyHtml string | null

Only with include ["body"]: the same body as HTML.

items[].bodyMarkdown string | null

Only with include ["body"]: the same body as Markdown, converted from the HTML — it renders the same, but is not byte-identical to what the author typed.

Request

curl -X POST "https://api.fetchlayer.dev/reddit/search" \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"query":"developer tools","subreddit":"webdev","sort":"top","time":"week","limit":10}'

Response

{
  "listingType": "search",
  "query": "developer tools",
  "sort": "top",
  "time": "week",
  "subredditFilter": "webdev",
  "items": [
    {
      "id": "1wi3mi5",
      "title": "Is vibe coding creating a hidden technical debt crisis?",
      "subreddit": "webdev",
      "author": "powleads",
      "score": 3241,
      "commentCount": 418,
      "url": "https://www.reddit.com/r/webdev/comments/1wi3mi5/",
      "createdAt": "2026-08-13T03:00:00.000Z",
      "nsfw": false,
      "spoiler": false,
      "locked": false,
      "stickied": false
    }
  ],
  "itemCount": 1,
  "pagesRequested": 1,
  "pagesScraped": 1,
  "transport": "reddit"
}
Product overview Reddit API: what it returns, pricing and use cases