# Reddit Search Scraper (`w3crawler/reddit-search-scraper`) Actor

Search Reddit by keyword and scrape matching posts with full metadata, images, videos, awards, and optional comments. Optionally restrict search to a single subreddit.

- **URL**: https://apify.com/w3crawler/reddit-search-scraper.md
- **Developed by:** [w3crawler](https://apify.com/w3crawler) (community)
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.99 / 1,000 search results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Reddit Search Scraper do?

**Reddit Search Scraper** searches public [Reddit](https://www.reddit.com/) posts by keyword and returns normalized post records with ranking context, community metadata, media, awards, and optional comments. It is a bounded Reddit search API alternative that uses public JSON responses first and never logs in, solves CAPTCHAs, or requests private content.

### Why use Reddit Search Scraper?

- Monitor public discussions, trends, brands, products, or research topics.
- Restrict a query to one public subreddit and choose Reddit's relevance, new, hot, top, or comments sort.
- Collect listing data quickly or enable detail enrichment for public post bodies, media, awards, and comments.
- Export results through Apify datasets and connect them to scheduling, API access, monitoring, and integrations.
- Stop at the requested `maxItems`, deduplicate by Reddit post ID, and fail closed on access barriers.

### What data can Reddit Search Scraper extract?

| Field | Type | Description |
|---|---|---|
| `postId`, `postFullname` | string | Bare post ID plus its `t3_<postId>` fullname. |
| `postTitle`, `selfText` | string | Public title and optional post body. |
| `permalink`, `contentUrl` | string | Canonical Reddit and linked-content URLs. |
| `author`, `subreddit` | string | Public author and community metadata. |
| `score`, `upvoteRatio`, `numComments` | number | Public engagement values. |
| `previewImages`, `videoData`, `mediaEmbed` | object | Public media metadata when present. |
| `comments` | array | Optional bounded public comments. |
| `searchQuery`, `position`, `sourceListingUrl` | mixed | Query, rank, and source provenance. |
| `scrapedAt` | string | ISO 8601 extraction timestamp. |

Unavailable optional values are omitted. The Actor does not emit empty strings, `N/A`, fabricated values, internal browser objects, duplicated raw response objects, or block pages as successful records.

### How to scrape Reddit search results

1. Open the Actor input tab.
2. Enter a non-empty `searchQuery`.
3. Optionally provide one subreddit name without `r/`.
4. Choose a sort and a small `maxItems` value.
5. Disable `deepScraping` for the fastest listing-only run, or enable it for richer post details.
6. Run the Actor and inspect the default dataset plus the `OUTPUT` run summary.

### Input

| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| `searchQuery` | string | — | yes | Query from 1 to 200 characters. |
| `subreddit` | string | empty | no | One public subreddit name. |
| `sortBy` | string | `relevance` | no | `relevance`, `new`, `hot`, `top`, or `comments`. |
| `topTime` | string | `all` | no | Time window for `top` sorting. |
| `maxItems` | integer | `50` | no | Exact upper result bound from 1 to 1000. |
| `deepScraping` | boolean | `true` | no | Fetch public post-detail JSON. |
| `includeComments` | boolean | `false` | no | Add up to 20 public comments per enriched post. |
| `headless` | boolean | `true` | no | Run Chromium without a visible window. |
| `proxyConfiguration` | object | Apify Proxy | no | Optional permitted proxy settings. |

Example bounded input:

```json
{
  "searchQuery": "nodejs tutorial",
  "sortBy": "relevance",
  "maxItems": 5,
  "deepScraping": false,
  "includeComments": false,
  "proxyConfiguration": { "useApifyProxy": false }
}
```

### Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

```json
{
  "recordType": "search_result",
  "position": 1,
  "postId": "example",
  "postFullname": "t3_example",
  "postTitle": "Example public post",
  "permalink": "https://www.reddit.com/r/example/comments/example/post/",
  "searchQuery": "nodejs tutorial",
  "subreddit": "example",
  "score": 42,
  "numComments": 7,
  "sourceListingUrl": "https://www.reddit.com/search/?q=nodejs%20tutorial&sort=relevance&t=all",
  "scrapedAt": "2026-08-30T10:00:00.000Z"
}
```

The `OUTPUT` key reports saved records, failed and blocked requests, normalized input, `status`, and `dataAvailable`. `status` is `SUCCESS` only when usable result rows were stored; `BLOCKED`, `FAILED`, and `NO_RESULTS` are diagnostic outcomes. A process that exits successfully with an empty dataset and blocked requests is still `BLOCKED`, not a successful search or a legitimate no-match result. If no usable results are available, the default dataset contains one four-field diagnostic record; access failures are never stored as successful post rows.

### How much does it cost to scrape Reddit?

Cost depends mainly on the item limit, detail pages, comments, browser runtime, and proxy choice. Listing-only searches are cheapest. Begin with 5–20 records, keep comments disabled unless needed, and consult the Actor pricing shown in Apify before production use.

### Local and cloud validation

Use `apify run --purge` inside the Actor directory for a clean local test, then run `npm run contract` and `node validate-datasets.js`. For cloud QA, deploy with `apify push`, call the exact mapped Actor with a bounded input and timeout, and retrieve its default dataset plus the `OUTPUT` key; a `SUCCEEDED` run alone is not proof of usable data.

### FAQ, disclaimer, and support

Reddit can return HTTP 403, login redirects, CAPTCHAs, or network-security blocks depending on location and proxy. The Actor detects those boundaries and does not bypass them.

Only publicly available content is requested. Results can contain personal data users chose to publish and may be protected by the GDPR or other laws. Use the data only with a legitimate basis and consult legal counsel when uncertain. Use the Actor's Issues tab for reproducible problems and the API tab for programmatic access.

# Changelog

This Actor's version history is a separate document: https://apify.com/w3crawler/reddit-search-scraper/changelog.md

# Actor input Schema

## `searchQuery` (type: `string`):

Keyword or phrase to search Reddit for

## `subreddit` (type: `string`):

Restrict results to a specific subreddit (without r/). Leave empty to search all of Reddit.

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

How to sort search results

## `topTime` (type: `string`):

Time period when sortBy is 'top'

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

Maximum number of posts to scrape

## `deepScraping` (type: `boolean`):

Open each post in a parallel browser tab to extract full details: complete selfText, images, videos, gallery, awards, metadata. Recommended for rich datasets.

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

Fetch top 20 comments with nested replies for each post (requires deepScraping=true)

## `headless` (type: `boolean`):

Run browser in headless mode (recommended for production)

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

Optional Apify proxy settings for public requests. The Actor never uses authentication or CAPTCHA solving.

## Actor input object example

```json
{
  "searchQuery": "nodejs tutorial",
  "sortBy": "relevance",
  "topTime": "all",
  "maxItems": 50,
  "deepScraping": true,
  "includeComments": false,
  "headless": true,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

URL of the dataset containing successful Reddit post records.

## `runSummary` (type: `string`):

Search context, enrichment settings, saved results, crawler failures, and availability.

# 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 = {
    "searchQuery": "nodejs tutorial",
    "subreddit": "",
    "maxItems": 50,
    "deepScraping": true,
    "includeComments": false,
    "headless": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("w3crawler/reddit-search-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 = {
    "searchQuery": "nodejs tutorial",
    "subreddit": "",
    "maxItems": 50,
    "deepScraping": True,
    "includeComments": False,
    "headless": True,
}

# Run the Actor and wait for it to finish
run = client.actor("w3crawler/reddit-search-scraper").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 '{
  "searchQuery": "nodejs tutorial",
  "subreddit": "",
  "maxItems": 50,
  "deepScraping": true,
  "includeComments": false,
  "headless": true
}' |
apify call w3crawler/reddit-search-scraper --silent --output-dataset

```

## MCP server setup

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

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/DcDTXQEj8WeyJGNvu/builds/uODX8B1Zs84tin9EG/openapi.json