# Reddit Subreddit Scraper (`devilscrapes/reddit-subreddit-scraper`) Actor

Scrape posts from any subreddit — hot, new, top, rising, or controversial. We rotate Firefox / Safari TLS fingerprints, route through residential proxies, retry with backoff on Reddit's 429s, and return typed dataset rows ready to ship.

- **URL**: https://apify.com/devilscrapes/reddit-subreddit-scraper.md
- **Developed by:** [DevilScrapes](https://apify.com/devilscrapes) (community)
- **Categories:** Social media, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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

<div align="center">
  <img src=".actor/icon.svg" width="160" alt="Devil Scrapes mark" />

## Reddit Subreddit Scraper

**💰 $1.00 / 1 000 results** &nbsp;·&nbsp; pay only for results &nbsp;·&nbsp; no credit card to try

_We do the dirty work so your dataset stays clean._ 😈

Scrape posts from any subreddit — hot, new, top, rising, or controversial. We rotate Firefox / Safari TLS fingerprints, route through residential proxies, retry with backoff on Reddit's 429s, and return typed dataset rows: title, author, score, upvote ratio, comment count, NSFW flag, URL, selftext (markdown), and posted-at timestamp.

</div>

---

### 🎯 What this scrapes

Reddit blocks scrapers aggressively — 429s, fingerprint checks, IP throttling. This Actor handles all of that for you. We rotate Firefox + Safari TLS fingerprints (Chrome impersonation gets 403'd from datacenter IPs), rotate residential proxy sessions on every block, retry with exponential backoff, and walk the subreddits you pick to write one typed row per post. Self-text is preserved as Markdown so downstream pipelines don't have to re-parse anything.

### 🔥 What we handle for you

- 🛡️ **Browser fingerprint rotation** — `curl-cffi` impersonates real Chrome / Firefox / Safari TLS handshakes so the target sees a browser, not Python.
- 🌐 **Residential proxy rotation** via Apify Proxy — fresh session and exit IP on every block.
- 🔁 **Retries with exponential backoff** on `408 / 429 / 5xx` — up to 5 attempts per page, `Retry-After` honoured.
- 🧱 **Rate-limit-aware pacing** — when the target pushes back, we slow down instead of getting banned.
- 🧊 **Clean, typed dataset rows** — Pydantic-validated, ISO-8601 timestamps, stable IDs, JSON / CSV / Excel export straight from the Apify Console.
- 💰 **Pay-Per-Event pricing** — you only pay for results that hit your dataset. No data, no charge.

### 💡 Use cases

- **Community monitoring** — diff `r/<your-product>` daily and alert on hot threads.
- **Content discovery** — pull the top 100 posts from `r/MachineLearning` weekly to feed a research digest.
- **Brand mention scanning** — scrape `r/all` filtered by a flair or keyword.
- **Sentiment baselines** — store posts + comments counts to build a sentiment time-series for a topic.

### ⚙️ How to use it

1. Click **Try for free** at the top of the page.
2. Fill in the input form — most fields have sensible defaults.
3. Click **Start**. Output streams into the run's dataset.
4. Export from **Storage → Dataset** as JSON, CSV, or Excel — or fetch via the API.

### 📥 Input

| Field | Type | Required | Default | Notes |
|---|---|:--:|---|---|
| `subreddits` | `array` | **yes** | ['programming'] | List of subreddit names (without the <code>r/</code> prefix). One per line. Multiple subreddits are scraped in sequence. |
| `mode` | `string` | no | 'hot' | Which Reddit listing to read. |
| `timeFilter` | `string` | no | 'day' | Applies only to <code>top</code> and <code>controversial</code> modes. |
| `maxResults` | `integer` | no | 100 | Reddit caps a listing at 1000 items. <code>0</code> means scrape until exhausted (still capped at 1000). |
| `includeSelftext` | `boolean` | no | True | When true, the post body (Markdown) is included for text posts. |
| `proxyConfiguration` | `object` | no | {'useApifyProxy': True} | Reddit can soft-rate-limit hot IPs. Apify Proxy with sticky sessions smooths this out. |

#### Example input

```json
{
  "subreddits": [
    "programming"
  ],
  "mode": "hot",
  "maxResults": 3,
  "includeSelftext": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
````

### 📤 Output

Every row is one dataset item.

| Field | Type | Notes |
|---|---|---|
| `id` | `string` | Reddit post fullname (e.g. `t3_abc123`). |
| `post_id` | `string` | Short id (the `abc123` part). |
| `subreddit` | `string` | Subreddit name (without `r/`). |
| `title` | `string` | Post title. |
| `author` | `string` | Author username, or `[deleted]`. |
| `url` | `string` | Outbound URL (or the Reddit permalink for self-posts). |
| `permalink` | `string` | Canonical Reddit permalink (https://reddit.com/r/.../comments/...). |
| `selftext` | `['string', 'null']` | Self-post body (Markdown). Null when includeSelftext=false or post is a link post. |
| `score` | `integer` | Upvotes minus downvotes. |
| `upvote_ratio` | `number` | Approximate ratio (0.0 – 1.0). |
| `num_comments` | `integer` | Comment count. |
| `over_18` | `boolean` | NSFW flag. |
| `spoiler` | `boolean` | Marked as spoiler. |
| `stickied` | `boolean` | Pinned by mods. |
| `locked` | `boolean` | Comments locked. |
| `post_hint` | `['string', 'null']` | Reddit's content classification (`image`, `link`, `video`, `self`, etc.). |
| `flair` | `['string', 'null']` | Post flair text. |
| `created_utc` | `integer` | Unix timestamp (seconds) — when the post was created. |
| `posted_at` | `string` | ISO-8601 UTC timestamp derived from `created_utc`. |
| `scraped_at` | `string` | When this row was recorded. |

#### Example output

```json
{
  "id": "t3_1ab2c3d",
  "post_id": "1ab2c3d",
  "subreddit": "programming",
  "title": "An honest critique of the new Rust runtime",
  "author": "u_rustacean",
  "url": "https://example.com/blog/rust-runtime",
  "permalink": "https://reddit.com/r/programming/comments/1ab2c3d/an_honest_critique",
  "score": 1283,
  "upvote_ratio": 0.94,
  "num_comments": 312,
  "over_18": false,
  "created_utc": 1747353600,
  "posted_at": "2026-05-15T20:00:00+00:00"
}
```

### 💰 Pricing

Pay-Per-Event — you pay only when these events fire:

| Event | USD | What it is |
|---|---:|---|
| `actor-start` | $0.005 | One-off warm-up charge per run |
| `result` | $0.001 | Per dataset item |

Example: 1 000 results at the rates above ≈ **$1.00**. No subscription, no minimum, no card to start — Apify gives every new account $5 of free credit.

### 🚧 Limitations

The Reddit JSON endpoint caps any listing at 1000 items, including pagination. For deeper history, use the Pushshift API (separate Actor — request one).

### ❓ FAQ

**Is this against Reddit's TOS?**

Public read-only access via `.json` URLs has been the standard for over a decade. We do not impersonate users, vote, or comment. For commercial-scale crawling Reddit prefers their Data API — sign up at reddit.com/dev/api.

**Why am I getting 429s?**

Reddit aggressively rate-limits scrapers. Lower `maxResults` per run, or schedule multiple smaller runs.

**Do you scrape comments?**

Not in this Actor — comments fan out arbitrarily. See the `reddit-post-comments-scraper` sibling.

**Why is the URL the same as the permalink?**

For self-posts, Reddit's `url` field points to the post itself, not an outbound link.

### 💬 Your feedback

Spotted a bug, hit a weird edge case, or need a new field? Open an
issue on the Actor's **Issues** tab on Apify Console — we ship
fixes weekly and we read every report.

***

<div align="center">

Built by **[Devil Scrapes](https://apify.com/DevilScrapes)** 😈 — a small fleet of
opinionated public-data Actors. Honest pricing, real engineering, zero fine print.

</div>

# Actor input Schema

## `subreddits` (type: `array`):

List of subreddit names (without the <code>r/</code> prefix). One per line. Multiple subreddits are scraped in sequence.

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

Which Reddit listing to read.

## `timeFilter` (type: `string`):

Applies only to <code>top</code> and <code>controversial</code> modes.

## `maxResults` (type: `integer`):

Reddit caps a listing at 1000 items. <code>0</code> means scrape until exhausted (still capped at 1000).

## `includeSelftext` (type: `boolean`):

When true, the post body (Markdown) is included for text posts.

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

Reddit can soft-rate-limit hot IPs. Apify Proxy with sticky sessions smooths this out.

## Actor input object example

```json
{
  "subreddits": [
    "programming"
  ],
  "mode": "hot",
  "timeFilter": "day",
  "maxResults": 100,
  "includeSelftext": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

All dataset items as JSON.

## `datasetItemsCsv` (type: `string`):

Same data exported to CSV.

## `datasetView` (type: `string`):

Open the run dataset in the Console.

# 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 = {
    "subreddits": [
        "programming"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("devilscrapes/reddit-subreddit-scraper").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 = {
    "subreddits": ["programming"],
    "proxyConfiguration": { "useApifyProxy": True },
}

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

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

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

```

## CLI example

```bash
echo '{
  "subreddits": [
    "programming"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call devilscrapes/reddit-subreddit-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=devilscrapes/reddit-subreddit-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Reddit Subreddit Scraper",
        "description": "Scrape posts from any subreddit — hot, new, top, rising, or controversial. We rotate Firefox / Safari TLS fingerprints, route through residential proxies, retry with backoff on Reddit's 429s, and return typed dataset rows ready to ship.",
        "version": "0.4",
        "x-build-id": "u2R0ablhoH54BnfAI"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/devilscrapes~reddit-subreddit-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-devilscrapes-reddit-subreddit-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/devilscrapes~reddit-subreddit-scraper/runs": {
            "post": {
                "operationId": "runs-sync-devilscrapes-reddit-subreddit-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/devilscrapes~reddit-subreddit-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-devilscrapes-reddit-subreddit-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "subreddits"
                ],
                "properties": {
                    "subreddits": {
                        "title": "Subreddits",
                        "type": "array",
                        "description": "List of subreddit names (without the <code>r/</code> prefix). One per line. Multiple subreddits are scraped in sequence.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "mode": {
                        "title": "Listing mode",
                        "enum": [
                            "hot",
                            "new",
                            "top",
                            "rising",
                            "controversial"
                        ],
                        "type": "string",
                        "description": "Which Reddit listing to read.",
                        "default": "hot"
                    },
                    "timeFilter": {
                        "title": "Top/controversial time window",
                        "enum": [
                            "hour",
                            "day",
                            "week",
                            "month",
                            "year",
                            "all"
                        ],
                        "type": "string",
                        "description": "Applies only to <code>top</code> and <code>controversial</code> modes.",
                        "default": "day"
                    },
                    "maxResults": {
                        "title": "Max posts per subreddit",
                        "minimum": 0,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Reddit caps a listing at 1000 items. <code>0</code> means scrape until exhausted (still capped at 1000).",
                        "default": 100
                    },
                    "includeSelftext": {
                        "title": "Include self-post text",
                        "type": "boolean",
                        "description": "When true, the post body (Markdown) is included for text posts.",
                        "default": true
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Reddit can soft-rate-limit hot IPs. Apify Proxy with sticky sessions smooths this out.",
                        "default": {
                            "useApifyProxy": true
                        }
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```