# Reddit Scraper Plus (`ctrlaltwin/reddit-scraper-plus`) Actor

- **URL**: https://apify.com/ctrlaltwin/reddit-scraper-plus.md
- **Developed by:** [CtrlAltWin](https://apify.com/ctrlaltwin) (community)
- **Categories:** Social media, News, Other
- **Stats:** 11 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$30.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period. You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#rental-actors

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Reddit Advanced Scraper (Apify Actor)

Pull posts, comments, users, and subreddit metadata from Reddit at scale — fast, resilient, and configurable.

This actor uses Reddit’s public JSON endpoints, smart session handling, and targeted rate limits to minimize blocks while giving you clean, normalized output ready for analytics or downstream processing.

### Why this actor

- Auto-detects mode from any Reddit URL (subreddit, post, user, or search)
- Deep comment expansion with max depth and "more" replies handling
- Global item limit to control dataset size and cost
- Time range and sorting for listings and search
- Optional user and subreddit metadata enrichment (about, moderators, rules)
- Pluggable extendOutputFunction to enrich items without changing the code
- Built-in proxy support (defaults to Apify Proxy)
- Clean, consistent output across item types (CSV/JSON)
- Verbose logging with an optional debug mode

### What you can extract

- Posts: titles, scores, ratios, permalinks, flairs, media, crosspost info, etc.
- Comments: full tree traversal, depth, scores, replies (including expanded "more" nodes)
- Users (optional): public profile metadata
- Subreddit metadata (optional): about, moderators, rules

### Inputs

- startUrls: array of Reddit URLs. Mode will be auto-detected unless overridden by `mode`.
- mode: one of `auto`, `subreddit`, `post`, `user`, `search`.
- searchQueries: array of strings to run Reddit-wide search (used if `mode` is `search` or `auto` and `startUrls` is empty).
- timeRange: one of `hour`, `day`, `week`, `month`, `year`, `all`.
- sortBy: for listings and search (e.g., `hot`, `new`, `top`, `rising`, or for search: `relevance`, `new`, `top`, `comments`).
- maxItems: global cap on how many items to output (posts, comments, users, rules, etc. combined).
- includePosts: boolean, default true.
- includeComments: boolean, default true.
- maxCommentsPerPost: cap comments per post, default 50.
- expandCommentReplies: boolean, default true (expand "more" nodes where possible).
- maxCommentDepth: maximum depth for comments (default 5).
- includeUsers: boolean, default false (queues user profiles and outputs public user metadata).
- includeSubredditMeta: boolean, default true (about, moderators, rules when a subreddit appears).
- proxyConfiguration: standard Apify proxy configuration; defaults to `{ useApifyProxy: true }`.
- extendOutputFunction: stringified async function to enrich each item.
- debugLog: boolean; set true for verbose logs.

### Example inputs

Minimal (subreddit listing):

```json
{
  "startUrls": [{ "url": "https://www.reddit.com/r/apify/" }],
  "timeRange": "week",
  "sortBy": "top",
  "maxItems": 100,
  "maxCommentsPerPost": 25,
  "includeComments": true,
  "includePosts": true,
  "includeSubredditMeta": true,
  "proxyConfiguration": { "useApifyProxy": true }
}
```

Reddit-wide search:

```json
{
    "debugLog": false,
    "expandCommentReplies": true,
    "includeComments": true,
    "includePosts": true,
    "includeSubredditMeta": true,
    "includeUsers": false,
    "maxCommentsPerPost": 15,
    "maxItems": 50,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "GB"
    },
    "startUrls": [
        {
            "url": "https://www.reddit.com/r/worldnews/",
            "method": "GET"
        }
    ]
}
```

### Output

Items are pushed to the default dataset. Types you can expect:

- type: `post` — fields include: id, name, title, author, subreddit, url, permalink, created\_utc, upvote\_ratio, score, num\_comments, over\_18, flair, awards, media, preview, crosspost\_parent, etc.
- type: `comment` — fields include: id, name, parent\_id, link\_id, permalink, author, body, score, created\_utc, depth, stickied, gilded, etc.
- type: `user` — fields include: id, name, created\_utc, link\_karma, comment\_karma, total\_karma, is\_gold, is\_mod, verified, icon\_img, subreddit (public profile sub).
- type: `subreddit` — fields include: id, name, title, subscribers, active\_user\_count, public\_description, description, over18, url, created\_utc, lang, quarantine.
- type: `subreddit_moderator` — subreddit+moderator info.
- type: `subreddit_rule` or `subreddit_rules_raw` — subreddit rules in normalized or raw form.

Export as JSON, JSONL, or CSV from the dataset tab in Apify.

3. Run in Apify Console.

### Extend the output

Enrich every item without forking the code using `extendOutputFunction`. Provide an async function (as a string) that receives `{ data, request, helpers }` and returns extra fields to merge:

```js
async ({ data, request, helpers }) => {
  // Add your own logic, e.g., language detection or custom tagging
  const isNSFW = data.over_18 === true;
  return { custom_tag: isNSFW ? 'nsfw' : 'safe' };
}
```

### How it works under the hood

- Uses Reddit’s public JSON endpoints and normalizes responses.
- Auto-detects mode from URL, or constructs listing/search/user endpoints directly.
- Employs a session pool with randomized headers and device IDs to reduce blocks.
- Warms up each session and respects moderate RPM and concurrency.
- Expands comment trees including "more" nodes (configurable depth and limits).

### Safety, compliance, and care when using this actor

- Respect Reddit’s Terms of Service and robots directives. Ensure your use case is allowed in your jurisdiction and by Reddit’s policies.
- Rate limiting and access: Although this actor uses conservative defaults (e.g., requests per minute and concurrency), Reddit can still block with 403/429. If that happens, reduce `maxRequestsPerMinute`/`maxConcurrency` in the code or run fewer concurrent tasks.
- Proxies: Use reliable proxies for higher volumes. The actor defaults to Apify Proxy; configure residential/geolocation as needed for your use case.
- Sensitive content: The actor sets a cookie `over18=1` to avoid age gates in some endpoints. Be mindful of NSFW content and handle it responsibly.
- Personal data: Public user metadata can still be sensitive. Avoid building profiles or making decisions that might infringe on privacy or local regulations.
- Legal and ethical use: Do not circumvent technical protection measures. Do not scrape private data or content requiring authentication.
- Load management: Large comment trees and subreddit meta expansion can generate very big datasets. Use `maxItems`, `maxCommentsPerPost`, and `maxCommentDepth` to keep runs predictable.
- Stability: Endpoints and response formats can change without notice. Pin versions and monitor runs with `debugLog` for troubleshooting.

### Troubleshooting

- Many 403/429 responses: Lower request rate, switch to residential proxies, or retry later. Ensure headers and sessions are not reused too aggressively.
- Empty or partial results: Check that your URLs are valid and the target subreddit/post exists and is public. Try different `timeRange`/`sortBy` for listings.
- Duplicates or limits hit early: Remember that `maxItems` is global across all item types produced during the run.
- Need raw data: Some endpoints (e.g., rules) may be pushed as `subreddit_rules_raw` if normalization isn't possible.

Build powerful datasets without the hassle of brittle HTML scraping — and do it responsibly.

# Actor input Schema

## `startUrls` (type: `array`):

List of Reddit URLs to start with. Accepts subreddit, post, user or search URLs.

## `mode` (type: `string`):

Forces a specific mode. Auto detects based on the provided URL(s).

## `searchQueries` (type: `array`):

Queries to search on Reddit when using search mode.

## `timeRange` (type: `string`):

Filter posts by time range (used for subreddits and search).

## `sortBy` (type: `string`):

Sorting for listings and search.

## `maxItems` (type: `integer`):

Maximum number of results (posts/comments/users/meta) to output.

## `maxCommentsPerPost` (type: `integer`):

Limit comments scraped per post. Use 0 to skip comment scraping.

## `expandCommentReplies` (type: `boolean`):

When true, recursively expands 'more' replies to the specified depth.

## `maxCommentDepth` (type: `integer`):

Maximum depth for nested comment replies expansion.

## `includePosts` (type: `boolean`):

Include post records in the output.

## `includeComments` (type: `boolean`):

Include comments for posts. Set to false to skip comments.

## `includeUsers` (type: `boolean`):

Include user profiles (about) for encountered authors and commenters.

## `includeSubredditMeta` (type: `boolean`):

Include subreddit metadata (about, moderators, rules).

## `proxyConfiguration` (type: `object`):

Configuration of proxy servers. Use Apify proxy for reliability when scraping Reddit.

## `extendOutputFunction` (type: `string`):

A function that takes ({ data, request, helpers }) and returns a modified or additional object to merge into the output.

## `debugLog` (type: `boolean`):

Enable verbose logging for debugging.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.reddit.com/r/apify/"
    }
  ],
  "mode": "auto",
  "timeRange": "all",
  "sortBy": "hot",
  "maxItems": 200,
  "maxCommentsPerPost": 50,
  "expandCommentReplies": true,
  "maxCommentDepth": 5,
  "includePosts": true,
  "includeComments": true,
  "includeUsers": false,
  "includeSubredditMeta": true,
  "extendOutputFunction": "async ({ data, request, helpers }) => { return data; }",
  "debugLog": false
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://www.reddit.com/r/apify/"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ctrlaltwin/reddit-scraper-plus").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "startUrls": [{ "url": "https://www.reddit.com/r/apify/" }] }

# Run the Actor and wait for it to finish
run = client.actor("ctrlaltwin/reddit-scraper-plus").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.reddit.com/r/apify/"
    }
  ]
}' |
apify call ctrlaltwin/reddit-scraper-plus --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ctrlaltwin/reddit-scraper-plus"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/BpWYqcBdTk45zORBr/builds/PAiAy3tYeeL9WaSsh/openapi.json