# Reddit API — subreddit posts, comments, search, user profiles, trending & community data from reddit.com (no account required)

> Posts in a subreddit, ranked by `sort`. Returns title/author/score/comment-count. Supports deep paging (`page`) and `flair` filtering.
> ReefAPI engine `reddit` · 11 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/reddit/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/reddit/v1/subreddit_posts — 1 credit
Posts in a subreddit, ranked by `sort`. Returns title/author/score/comment-count. Supports deep paging (`page`) and `flair` filtering.

**Parameters:**
- `subreddit` (string, required) — Subreddit name (without 'r/').
- `sort` (enum, optional, default "hot") — How posts are ranked. [one of: hot, new, top, rising, controversial]
- `time` (enum, optional, default "day") — Time window — applies ONLY when sort = top or controversial. [one of: hour, day, week, month, year, all]
- `limit` (integer, optional, default 10) — How many posts to return (1–100).
- `flair` (string, optional) — Filter to one post flair, e.g. 'Discussion' (case-insensitive, live source only). Matches flairs that CONTAIN the text ('Hiring' also keeps 'Hiring - Open'); set flair_exact=true for the whole flair only.
- `flair_exact` (boolean, optional, default false) — With `flair`: keep only posts whose flair is exactly that text (case-insensitive), not flairs that merely contain it.
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]
- `page` (integer, optional, default 1) — Deep paging: page 2 returns the NEXT batch after page 1 (server chains cursors for you, 1–20). Live source only — archive sources page via after_utc/before_utc.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).

**Returns:** posts[]{title, author, author_fullname, score, num_comments, created_utc, url, id, video{url, hls_url, dash_url, duration, width, height, has_audio}, gallery[]{url, width, height, type, caption}}

**Example request body:**
```json
{
  "subreddit": "python",
  "limit": 10
}
```

### POST https://api.reefapi.com/reddit/v1/multi_subreddit_posts — 5 credits
ONE merged newest-first feed across a whole watchlist of subreddits — pass up to 5000 names in a single call instead of polling each one. Built for near-real-time monitoring: posts show up seconds after they go live, `since_utc` returns only what is new since your last poll.

**Parameters:**
- `subreddits` (string, required) — Subreddit names to merge, comma-separated (no 'r/'). Up to 5000 — long lists are split across parallel fetches for you and returned as one feed.
- `sort` (enum, optional, default "new") — How posts are ranked. [one of: new, hot, rising, top, controversial]
- `time` (enum, optional, default "day") — Time window — applies ONLY when sort = top or controversial. [one of: hour, day, week, month, year, all]
- `limit` (integer, optional, default 100) — How many posts to return after merging (1–500).
- `since_utc` (integer, optional) — Polling mode: return ONLY posts created after this unix time. Pass the previous response's newest_utc to get just the new ones.
- `max_pages` (integer, optional, default 1) — Fetch this many pages per group (1–5) — raise it when a poll interval is long enough that 100 posts may not cover it.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).

**Returns:** posts[]{title, author, author_fullname, subreddit, score, num_comments, created_utc, url, id}, subreddits_requested, shards, newest_utc, oldest_utc

**Example request body:**
```json
{
  "subreddits": "python,rust,golang",
  "limit": 25
}
```

### POST https://api.reefapi.com/reddit/v1/post_comments — 1 credit
Threaded comments for a post. Returns author/body/score per comment.

**Parameters:**
- `post_id` (string, required) — Post ID or full Reddit URL.
- `sort` (enum, optional, default "best") — Comment ordering. [one of: best, top, new, controversial, old, qa]
- `limit` (integer, optional, default 50) — How many comments (1–500). Up to ~500 per call; the rest of a big thread comes back as more_ids.
- `depth` (integer, optional, default 10) — Comment-tree depth (1–50).
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** comments[]{author, author_fullname, body, score, created_utc, depth, id, replies[]}; more_ids[] (a token for EVERY collapsed branch and for the rest of the thread) + has_more: feed more_ids into load_more_comments for the full tree

**Example request body:**
```json
{
  "post_id": "f08dxb"
}
```

### POST https://api.reefapi.com/reddit/v1/search — 1 credit
Search posts, comments, or users by `q` and/or `subreddit`/`author`. Returns results[]. Comment search reads Reddit's own live comment index. Cursor pagination + `flair` filter apply on the live source. An empty result is confirmed before it is returned (meta.empty_retries). The post-search cursor is an opaque offset token (e.g. `OTk=`), not a `t3_` fullname: pass meta.pagination.next_cursor back unchanged, and de-duplicate by `id` when paging a fast-moving `sort=new` query (new posts shift the offsets).

**Parameters:**
- `q` (string, optional) — Search text. Provide `q` and/or `subreddit`/`author`.
- `subreddit` (string, optional) — Limit the search to one subreddit (optional).
- `author` (string, optional) — Limit to one author's content (optional).
- `type` (enum, optional, default "post") — What to search for. [one of: post, comment, user]
- `sort` (enum, optional, default "new") — Result ordering. Omitted = newest first (`new`), whether or not `q` is given; pass `relevance` for Reddit's relevance ranking. For type=comment, `relevance` uses Reddit's default comment ranking and `hot` is not applied; ignored for type=user. [one of: relevance, hot, new, top, comments]
- `time` (enum, optional, default "all") — Time window: only results from the past hour, day, week, month or year. Works with every sort. Omitted = all time. For type=comment Reddit's comment search has no window of its own, so it is applied to each comment's date (with sort=new the result is complete; with top/relevance it keeps the in-window part of Reddit's all-time ranking). Not applied to type=user. [one of: hour, day, week, month, year, all]
- `limit` (integer, optional, default 10) — How many results (1–100).
- `after_utc` (integer, optional) — Only results created AFTER this unix time (optional). For a rolling window prefer `time`; this bound is applied on top of it, so a page can hold fewer than `limit` results.
- `before_utc` (integer, optional) — Only results created BEFORE this unix time (optional; same note as after_utc).
- `include_nsfw` (boolean, optional, default false) — Include over-18 results. Off by default, as on Reddit: without it Reddit leaves every NSFW result out.
- `flair` (string, optional) — Filter to one post flair, e.g. 'Discussion' (case-insensitive, live source only). Matches flairs that CONTAIN the text ('Hiring' also keeps 'Hiring - Open'); set flair_exact=true for the whole flair only.
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]
- `page` (integer, optional, default 1) — Deep paging: page 2 returns the NEXT batch after page 1 (server chains cursors for you, 1–20). Live source only — archive sources page via after_utc/before_utc.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).

**Returns:** results[]{title, author, author_fullname, subreddit, score, created_utc, url, id, video{...}, gallery[]{...}}

**Example request body:**
```json
{
  "subreddit": "python",
  "limit": 10
}
```

### POST https://api.reefapi.com/reddit/v1/user — 1 credit
User profile or content. kind=about returns karma and the profile (display name, bio, banner, NSFW flag); submitted/comments list items (with deep paging), and each comment carries the title and link of the post it was left on. Reddit keeps about the last 1,000 items of a user's listing and leaves removed ones out, so a listing can end before that.

**Parameters:**
- `username` (string, required) — Reddit username (without 'u/').
- `kind` (enum, optional, default "about") — What to return. [one of: about, submitted, comments]
- `limit` (integer, optional, default 25) — How many items (for submitted/comments, 1–100).
- `sort` (enum, optional, default "new") — Ordering (for submitted/comments). [one of: new, top, hot, controversial]
- `time` (enum, optional, default "all") — Time window — applies ONLY when sort = top or controversial. [one of: hour, day, week, month, year, all]
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]
- `page` (integer, optional, default 1) — Deep paging: page 2 returns the NEXT batch after page 1 (server chains cursors for you, 1–20). Live source only — archive sources page via after_utc/before_utc.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).

**Returns:** user{name, id, link_karma, comment_karma, total_karma, created_utc, icon_img, display_name, bio, banner_img, over_18, ...} (kind=about) or items[] (posts, or comments with post_title / post_permalink / post_url / post_author)

**Example request body:**
```json
{
  "username": "spez",
  "kind": "about"
}
```

### POST https://api.reefapi.com/reddit/v1/subreddit_about — 1 credit
Subreddit metadata: subscribers, description, created date, banner, status, etc. A private, quarantined or banned subreddit is refused by Reddit: the answer is NOT_FOUND with error.detail.status = private | quarantined | banned (a name that never existed has no status).

**Parameters:**
- `subreddit` (string, required) — Subreddit name (without 'r/').
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** subreddit{subscribers, title, public_description, created_utc, over18, banner_img, quarantine, status}

**Example request body:**
```json
{
  "subreddit": "python"
}
```

### POST https://api.reefapi.com/reddit/v1/communities — 1 credit
Search subreddits by name/keyword — find communities matching a term, with each one's subscribers, title, description and over-18 flag.

**Parameters:**
- `q` (string, required) — Name or keyword to search subreddits for.
- `limit` (integer, optional, default 25) — Max communities to return (1–100).
- `include_nsfw` (boolean, optional, default false) — Include over-18 results. Off by default, as on Reddit: without it Reddit leaves every NSFW result out.

**Returns:** communities[]{name, title, subscribers, public_description, over18, created_utc, banner_img, status}

**Example request body:**
```json
{
  "q": "\"python\""
}
```

### POST https://api.reefapi.com/reddit/v1/trending — 2 credits
Site-wide discovery — hot/popular posts from r/popular or r/all (what's trending across Reddit right now), or the most-popular communities. No subreddit needed.

**Parameters:**
- `scope` (enum, optional, default "popular") — Which site-wide feed. [one of: popular, all]
- `kind` (enum, optional, default "posts") — Return trending posts or the most-popular communities. [one of: posts, communities]
- `sort` (enum, optional, default "hot") — How posts are ranked. [one of: hot, new, top, rising, controversial]
- `time` (enum, optional, default "day") — Time window — applies ONLY when sort = top or controversial. [one of: hour, day, week, month, year, all]
- `limit` (integer, optional, default 25) — How many to return (1–100).
- `geo` (string, optional) — r/popular for one country, as on reddit.com: a 2-letter code (US, GB, DE, CA, IN…) or GLOBAL for Reddit's 'Everywhere' feed. Reddit's r/popular is per country; omit it and the feed follows the country of the connection. scope=popular only.
- `flair` (string, optional) — Filter to one post flair, e.g. 'Discussion' (case-insensitive, live source only). Matches flairs that CONTAIN the text ('Hiring' also keeps 'Hiring - Open'); set flair_exact=true for the whole flair only.
- `flair_exact` (boolean, optional, default false) — With `flair`: keep only posts whose flair is exactly that text (case-insensitive), not flairs that merely contain it.
- `page` (integer, optional, default 1) — Deep paging: page 2 returns the NEXT batch after page 1 (server chains cursors for you, 1–20). Live source only — archive sources page via after_utc/before_utc.
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** posts[]{title, author, author_fullname, subreddit, score, num_comments, ...} (kind=posts) OR communities[]{name, title, subscribers, ...} (kind=communities)

**Example request body:**
```json
{
  "scope": "popular",
  "limit": 10
}
```

### POST https://api.reefapi.com/reddit/v1/user_search — 2 credits
Find Reddit users by name/keyword — people search. Returns matching profiles with karma, display name, bio, banner, NSFW flag and is_employee. (Same as search with type=user.)

**Parameters:**
- `q` (string, required) — Name or keyword to search users for.
- `limit` (integer, optional, default 25) — How many users to return (1–100).
- `cursor` (string, optional) — Next page: pass the previous response's meta.pagination.next_cursor (the 'Next' button does this automatically).
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** results[]{name, id, link_karma, comment_karma, total_karma, created_utc, display_name, bio, banner_img, over_18, is_employee, ...}

**Example request body:**
```json
{
  "q": "python",
  "limit": 10
}
```

### POST https://api.reefapi.com/reddit/v1/load_more_comments — 3 credits
Expand the collapsed 'more comments' nodes from a post_comments call — pass that response's more_ids to reveal the rest of the thread (build the FULL comment tree).

**Parameters:**
- `post_id` (string, required) — The post these comments belong to (ID or Reddit URL).
- `more_ids` (string, required) — Comma-separated more_ids from a post_comments response (its top-level more_ids, or a comment's comments[].more_ids). Each call expands the first few and returns the rest, plus any newly collapsed branches, in more_ids. Plain comment IDs also work: each returns that comment with its replies.
- `limit` (integer, optional, default 100) — Max more_ids to accept per call (1–100).
- `sort` (enum, optional, default "best") — Comment ordering. [one of: best, top, new, controversial, old, qa]
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** comments[]{author, author_fullname, body, score, depth, id, parent_id, ...}, more_ids[] (tokens still to expand: feed them back the same way)

**Example request body:**
```json
{
  "post_id": "f08dxb",
  "more_ids": "fh0xhez,fgsriwh,fj9b0aj,fgyfmaj,fgss3kw"
}
```

### POST https://api.reefapi.com/reddit/v1/subreddit_extras — 3 credits
Public subreddit extras: the community's rules and its wiki page index/content. (Moderator list is mod-only on Reddit and is not available logged-out.)

**Parameters:**
- `subreddit` (string, required) — Subreddit name (without 'r/').
- `include` (string, optional, default "rules,wiki") — Which extras to return: 'rules', 'wiki', or both (comma-separated).
- `wiki_page` (string, optional) — Fetch ONE wiki page's full content (e.g. 'index', 'faq'). Omit to list available page names.
- `source` (enum, optional, default "auto") — Which Reddit data source to use — 'auto' picks the best source automatically. [one of: auto, live, arctic, pullpush]

**Returns:** rules[]{short_name, description, kind, ...}, wiki_pages[] (names) OR wiki_page{page, content_md, revision_date, ...}

**Example request body:**
```json
{
  "subreddit": "python"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=reddit
- Human docs page: https://reefapi.com/docs/reddit
- Overview page: https://reefapi.com/reddit-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt
