# Reddit Posts Search Scraper (`outspoken_strategy/reddit-posts-search-scraper`) Actor

Search Reddit posts by keyword. Multiple keywords, sort by relevance/hot/top/new/comments, time and date filters, optional subreddit restriction, auto-pagination. Returns title, text, author, subreddit, score, comments and media.

- **URL**: https://apify.com/outspoken\_strategy/reddit-posts-search-scraper.md
- **Developed by:** [code craker](https://apify.com/outspoken_strategy) (community)
- **Categories:** News, Social media, Developer tools
- **Stats:** 4 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $15.00 / 1,000 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/platform/actors/running/actors-in-store#pay-per-event

## 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 Posts Search Scraper

Apify actor that searches Reddit posts by keyword and exports them as structured data.
It scrapes the classic old.reddit.com search pages over plain HTTP — no browser, no
login, no cookies — which keeps runs fast and cheap (256 MB of memory is enough).
(Reddit hard-blocks its public `.json` listing endpoints for unauthenticated clients,
but the old.reddit HTML search is served normally and its markup has been stable for
a decade.)

### Features

- One keyword (`query`) or many (`queries`) — each searched separately, results
  combined and de-duplicated by post.
- Sort by `new` (chronological), `relevance`, `hot`, `top` or `comments`.
- Reddit's own time window (`timeFilter`: hour/day/week/month/year/all) plus exact
  `timeSince` / `timeUntil` date bounds enforced actor-side.
- Optional restriction to a single subreddit.
- Cursor-based auto-pagination up to Reddit's ~1000-results-per-listing cap.
- Results are pushed page by page, so an abort or timeout keeps everything
  collected so far.
- Automatic block recovery: on HTTP 403/429 the actor retries with a fresh proxy IP.
- When a run ends with 0 results, the last page fetched is saved as `DEBUG_HTML`
  in the run's key-value store.

### Input

```json
{
    "queries": ["econet", "delta corporation"],
    "sort": "new",
    "numberOfPosts": 100,
    "timeSince": "2026-01-01",
    "subreddit": "zimbabwe",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US"
    }
}
```

`numberOfPosts` applies **per keyword**. Reddit search operators
(`subreddit:`, `author:`, `self:yes`, `OR`, quoted phrases, ...) typed into a
query are passed through as-is.

Reddit blocks most datacenter IPs on its public JSON API, so keep the
RESIDENTIAL proxy default.

### Output

One dataset item per post:

```json
{
    "id": "1abcd2",
    "name": "t3_1abcd2",
    "url": "https://www.reddit.com/r/zimbabwe/comments/1abcd2/econet_results/",
    "title": "Econet posts strong half-year results",
    "text": "Rendered selftext of the post (empty for link posts)...",
    "author": "some_user",
    "authorProfileUrl": "https://www.reddit.com/user/some_user",
    "subreddit": "zimbabwe",
    "subredditUrl": "https://www.reddit.com/r/zimbabwe",
    "score": 42,
    "numComments": 17,
    "linkFlairText": "Business",
    "isSelf": true,
    "over18": false,
    "externalUrl": null,
    "domain": "self.zimbabwe",
    "thumbnail": null,
    "created_at": "2026-07-01T09:30:12.000Z",
    "createdUtc": 1782898212,
    "searchQuery": "econet",
    "sort": "new",
    "timeFilter": "all"
}
```

`score` is `null` while Reddit still hides the vote count of a very fresh post
(typically the first hour or two).

### Integration (scraping-tool)

Call it like the other `outspoken_strategy/*` search actors:

```js
const res = await this.scrapingService.scrape({
    url: `https://www.reddit.com/search/?q=${encodeURIComponent(keyword)}`,
    resultsLimit: requestCount,
    actor: 'outspoken_strategy/reddit-posts-search-scraper',
    timeout,
    additionalInput: {
        query: keyword,
        numberOfPosts: requestCount,
        sort: 'new',
        proxyConfiguration: { useApifyProxy: true, apifyProxyGroups: ['RESIDENTIAL'], apifyProxyCountry: 'US' }
    },
    scrapeType: 'reddit-keyword-search'
});
```

Normalization hints: `url` and `id` are ready to use; `text` holds the selftext
only, so index `title + text` for relevance matching; `likesCount` → `score`,
`commentsCount` → `numComments`, `createdTime` → `created_at`.

### Local development

```bash
npm install
echo '{ "query": "artificial intelligence", "numberOfPosts": 25, "proxyConfiguration": { "useApifyProxy": false } }' > storage/key_value_stores/default/INPUT.json
npm start
```

Deploy with `apify push`.

# Actor input Schema

## `query` (type: `string`):

One keyword/phrase to search for. Wrap in double quotes for an exact phrase match, e.g. "econet revenue". Reddit search operators (subreddit:, author:, self:, OR, AND, ...) are passed through as-is. You can also paste several keywords, one per line, to search them all. For a clean list use the "queries" field below instead. Leave empty if you use "queries".

## `queries` (type: `array`):

Multiple keywords/phrases to search — each is searched separately and results are combined and de-duplicated by post. Takes precedence over/adds to "query". numberOfPosts applies PER keyword.

## `sort` (type: `string`):

How Reddit orders the search results: "new" (chronological), "relevance", "hot", "top" or "comments" (most commented).

## `numberOfPosts` (type: `integer`):

Maximum number of posts to fetch per keyword. Reddit caps any single search listing at roughly 1000 results, older posts beyond that are unreachable.

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

Reddit's own time window for the search (the "past hour/day/week/..." dropdown). Applies to the "relevance", "top" and "comments" sorts; "new" and "hot" ignore it.

## `timeSince` (type: `string`):

Only return posts published on or after this date (format: yyyy-mm-dd). Enforced on our side after fetching — combine with sort "new" for the most complete coverage of a date range.

## `timeUntil` (type: `string`):

Only return posts published before this date (format: yyyy-mm-dd). Enforced on our side after fetching.

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

Only search within this subreddit (e.g. "zimbabwe" or "r/zimbabwe"). Leave empty to search all of Reddit.

## `includeNsfw` (type: `boolean`):

Include posts marked as adult content in the results.

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

Proxy to route traffic through. Reddit blocks most datacenter IPs on its public JSON API, so residential proxies are strongly recommended.

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

The actor fetches over plain HTTP and only falls back to a Chrome browser when Reddit blocks it. Uncheck to run that fallback browser headed (useful only for local debugging).

## Actor input object example

```json
{
  "query": "artificial intelligence",
  "queries": [],
  "sort": "new",
  "numberOfPosts": 100,
  "timeFilter": "all",
  "includeNsfw": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  },
  "headless": true
}
```

# 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 = {
    "query": "artificial intelligence",
    "queries": [],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("outspoken_strategy/reddit-posts-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 = {
    "query": "artificial intelligence",
    "queries": [],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("outspoken_strategy/reddit-posts-search-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 '{
  "query": "artificial intelligence",
  "queries": [],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call outspoken_strategy/reddit-posts-search-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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