# Reddit Search API (`truefetch/reddit-search-api`) Actor

Reddit search API for keyword queries across communities, returning 40 structured post fields with configurable sorting and time windows plus an optional bounded comment array. Requested limits depend on Reddit availability. $6.50 per 1,000 posts.

- **URL**: https://apify.com/truefetch/reddit-search-api.md
- **Developed by:** [TrueFetch](https://apify.com/truefetch) (community)
- **Categories:** Social media, Developer tools, Automation
- **Stats:** 24 total users, 3 monthly users, 100.0% runs succeeded, 3 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $5.20 / 1,000 posts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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 Search API is a Reddit search API that turns one keyword into structured Reddit post records from communities returned by Reddit search, with configurable sorting, a time window, source-reported engagement fields, moderation flags, media references, and an optional bounded comment sample.**

- **The input contract exposes five controls: one keyword, five sort modes, six time windows, a post cap, and an optional per-post comment cap.**
- **Each dataset row is documented with 40 top-level post fields, including the processor URL and a UTC processing timestamp.**
- **The same `battery recycling` scenario is shown for Console, API, MCP, and output inspection so the examples can be compared directly.**
- **All four referenced Apify schema types validate for this release: input, dataset, output, and key-value store.**

[**Run a one-post test**](https://apify.com/truefetch/reddit-search-api/input) · [**View API options**](https://apify.com/truefetch/reddit-search-api/api)

For the smallest useful FREE-tier check, request one post and set `max_comments` to `0`. One minimum start plus one returned post is configured at **$0.01650**. Search availability, rankings, visible fields, runtime, and live prices can change, so set a maximum total charge and inspect a small result before scaling.

### What does Reddit Search API do?

Reddit Search API submits a keyword to Reddit search and returns matching posts as structured dataset rows. It is designed for questions that begin with a topic, product, organization, event, or phrase rather than a known username or a single known community. The Actor can sort the source search by relevance, hot, top, new, or comments and apply an all-time, hour, day, week, month, or year window.

Each returned row combines post text with its community context and public source signals. That includes the title, body, author, subreddit, subscriber count, source link, flair, timestamps, score-like values, status flags, media references, duplicate links, and processing provenance. When comments are requested, a bounded nested comment sample is attached to the corresponding post row.

The Actor does not interpret the records. It does not label sentiment, verify an author's identity, prove that a score represents unique people, or guarantee a stable ranking. It returns source records for a downstream research, review, moderation, archiving, or approved automation workflow.

### How do I run Reddit Search API?

Open the [Actor input page](https://apify.com/truefetch/reddit-search-api/input), enter a keyword, choose the sort order and time window, set a small post limit, and decide whether comments are needed. A safe first run uses one post and no comments. Review that row before increasing either cap.

Use this input for the shared example:

```json
{
  "keyword": "battery recycling",
  "sort_by": "relevance",
  "time_filter": "month",
  "max_posts": 1,
  "max_comments": 1
}
```

All five fields are required. Set `max_comments` to `0` when post-level data is enough. A maximum is a request and billing boundary, not a promise that Reddit will expose that many matching records.

After the run finishes, open the default dataset and confirm the title, source link, subreddit, timestamps, flags, and any retained comments. Export only the fields and formats needed by the next step in your workflow.

### What data does Reddit Search API return?

Each returned post is one Dataset row with 40 documented top-level fields:

| Field group | Fields | What it answers |
| --- | --- | --- |
| Identity and text | `id`, `post_url`, `title`, `body`, `flair_text` | What was posted and where can it be reviewed? |
| Author and community | `author`, `author_flair`, `subreddit`, `subreddit_type`, `subreddit_subscribers` | Who posted it and in what community context? |
| Timing and engagement | `created_at`, `edited_at`, `score`, `upvote_ratio`, `comment_count`, `crossposts` | When did it appear and what public response does Reddit report? |
| Media | `media_type`, `media_url`, `domain`, `thumbnail`, `images`, `video_url`, `video_duration` | Does the post carry a link, image, gallery, or hosted video? |
| Type and state | `is_self`, `is_video`, `is_original`, `is_gallery`, `distinguished`, `removed_by`, `indexable`, `over_18`, `spoiler`, `locked`, `stickied`, `pinned`, `archived` | How is the post classified or moderated? |
| Relationships | `duplicates`, `comments` | Where was the link reposted and which bounded comments were retained? |
| Provenance | `processor`, `processed_at` | Which Actor processed the row and when? |

This abbreviated row uses the same `battery recycling` scenario. It contains only supported fields; omitted fields remain available in the full Dataset row:

```json
{
  "id": "1us0n5l",
  "post_url": "https://www.reddit.com/r/StartUpIndia/comments/1us0n5l/example/",
  "title": "Thinking about getting into lithium battery recycling in India",
  "body": "Post body as exposed by the source.",
  "author": "example_researcher",
  "subreddit": "StartUpIndia",
  "subreddit_type": "public",
  "subreddit_subscribers": 435738,
  "created_at": "2026-07-10T12:00:00+00:00",
  "score": 6,
  "upvote_ratio": 0.92,
  "comment_count": 12,
  "crossposts": 0,
  "over_18": false,
  "duplicates": [],
  "comments": [
    {
      "id": "example-comment",
      "comment_url": "https://www.reddit.com/r/StartUpIndia/comments/1us0n5l/example-comment/",
      "body": "Example comment text",
      "author": "example_user",
      "created_at": "2026-07-10T12:10:00+00:00",
      "score": 3,
      "is_root": true,
      "reply_level": 0
    }
  ],
  "processor": "https://apify.com/truefetch/reddit-search-api",
  "processed_at": "2026-07-24T05:49:12+00:00"
}
```

Reddit can approximate, hide, or change engagement values. Nulls and empty arrays are normal when a source field is unavailable, inapplicable, deleted, or not requested. Preserve those distinctions until your downstream rules explicitly decide how to handle them.

### What inputs can I configure?

All five inputs are required and follow this order:

| Input | Type and range | Effect |
| --- | --- | --- |
| `keyword` | Non-empty string, up to 512 characters | The term or phrase sent to Reddit search. Record it exactly when comparing runs. |
| `sort_by` | `relevance`, `hot`, `top`, `new`, or `comments` | Requests Reddit's ordering; it does not create a permanent ranking. |
| `time_filter` | `all`, `hour`, `day`, `week`, `month`, or `year` | Restricts the source search window. |
| `max_posts` | Integer from 1 to 250 | Caps returned post rows. Reddit search stops near 250 results for one query even when more are requested. |
| `max_comments` | Integer from 0 to 2000 per post | Caps retained comments; use `0` to skip comment collection. |

Both caps are upper bounds, not availability promises. Begin with one post and zero or one comment, inspect content and event cost, and then increase gradually.

### What platforms and markets does Reddit Search API cover?

This Actor covers public records exposed through Reddit search across the communities that Reddit returns for the keyword. There is no country input and no promise of complete geographic coverage. A post's language, author location, or community focus must not be inferred solely from the subreddit name.

The Actor is not a general web search engine, private-community access tool, deleted-content recovery service, live firehose, or single-subreddit crawler. For a known account or community, use a more specific related Actor and compare its input contract before running.

### Why use Reddit Search API?

The main advantage is a reviewable, repeatable interface around a topic search. A saved input records the keyword, ordering, time window, and caps used for a snapshot. Dataset exports make it easier to compare selected fields, retain provenance, or pass records to another approved system without parsing a visual Reddit page.

Optional comments keep post-only research inexpensive while allowing a small discussion sample when context matters. The schema also separates source content from processing provenance, which helps analysts distinguish when the record was processed from when Reddit says the post was created.

Use the Actor as one evidence source. Sampling bias, ranking changes, moderation, deletions, private communities, and source availability can all affect what appears. Conclusions should be reviewed against the exact input, run time, and original links.

### Who is Reddit Search API for?

- Researchers collecting a bounded topic sample for qualitative review.
- Product and support teams examining public discussions around a defined phrase.
- Journalists or analysts preserving source links and timestamps for follow-up.
- Developers building approved ingestion, classification, or alerting workflows.
- Trust and safety teams reviewing public posts under an appropriate policy and legal basis.

It is not designed for harassment, deanonymization, credential collection, evasion of access controls, or high-stakes decisions about individuals. Apply data minimization, retention limits, human review, and applicable platform and privacy rules.

### How can I use Reddit Search API through the API or MCP?

The Actor can be started from the Console, Apify API, schedules, webhooks, or an MCP-capable client. The verified Actor ID for this listing is `Xzx9cQ28OerGtBV3o`, and the full Actor name is `truefetch/reddit-search-api`.

For a synchronous API call, set `APIFY_TOKEN` in your environment and run:

```bash
curl -X POST "https://api.apify.com/v2/acts/truefetch~reddit-search-api/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"keyword":"battery recycling","sort_by":"relevance","time_filter":"month","max_posts":1,"max_comments":1}'
```

The equivalent API request body is:

```json
{
  "keyword": "battery recycling",
  "sort_by": "relevance",
  "time_filter": "month",
  "max_posts": 1,
  "max_comments": 1
}
```

For MCP, connect an authorized client to [Apify MCP](https://mcp.apify.com), fetch Actor details first, inspect the current input schema, and then call `truefetch/reddit-search-api` with a bounded charge and runtime. The Actor input remains:

```json
{
  "keyword": "battery recycling",
  "sort_by": "relevance",
  "time_filter": "month",
  "max_posts": 1,
  "max_comments": 1
}
```

Keep tokens in environment variables or a secret manager. Do not paste them into a README, dataset, issue, or shared prompt. A client plan can also restrict public Actor execution before a run starts; that host-level refusal is different from an Actor runtime failure.

### How much does Reddit Search API cost?

This release uses pay-per-event pricing. The start event depends on requested memory, with a minimum of one start event. A result event applies to each returned dataset post, and a comment event applies to each comment retained inside a post result. Confirm the [live pricing page](https://apify.com/truefetch/reddit-search-api/pricing) before production use.

| Event | FREE | BRONZE | SILVER | GOLD / PLATINUM / DIAMOND |
|---|---:|---:|---:|---:|
| Actor Start, minimum | $0.01000 | $0.01000 | $0.01000 | $0.01000 |
| Result, per returned post | $0.00650 | $0.00585 | $0.00520 | $0.00488 |
| Retained comment | $0.00125 | $0.00113 | $0.00100 | $0.00094 |

The bounded one-post, no-comment test described above combines one minimum start and one returned Result. A no-result run can still incur the start event. More memory can increase start charges, and requested caps can multiply Result and Comment events, so use `maxTotalChargeUsd` and small input caps.

### How does Reddit Search API compare with alternatives?

Manual Reddit search is convenient for reading a few results but is harder to reproduce or export consistently. A browser crawler can capture rendered pages, yet it usually requires more page-handling logic and may produce less stable field structure. A custom Reddit integration offers complete control but requires ongoing authentication, API, retry, storage, and schema maintenance.

Reddit Search API is the middle option: a defined input, documented dataset, optional comments, API and MCP access, and event-based billing. Choose it when those properties match the workflow. Choose a community-specific Actor when the subreddit is already known, and choose a user-profile Actor when the username is the primary key.

### What are the limits and troubleshooting steps?

- **No results:** broaden the keyword or time window and verify the same query at the source.
- **Fewer rows than requested:** the cap does not override Reddit availability, ranking, moderation, or access rules.
- **Slow comment runs:** retry with `max_comments` set to `0` or a small value; heavily discussed posts require more source work.
- **Missing or null fields:** inspect the original post because deleted authors, text-only posts, link posts, and moderation states expose different fields.
- **Different repeated results:** source rankings and visible activity can change between runs even with identical input.
- **Charge limit reached:** lower post and comment caps or raise the maximum total charge only after reviewing the live price.
- **Public Actor rejected before start:** confirm the MCP or Apify account plan permits public Actor runs.

Report a reproducible issue with the run ID, exact five-field input, expected behavior, and observed status. Remove tokens and unrelated personal information before sharing logs.

### Frequently asked questions

#### How do I scrape Reddit search results?

To scrape Reddit search results, pass one keyword with a sort mode and time window; the Actor queries Reddit's own search surface and writes each matching post as a 40-field dataset row.

#### Can I use this as a Reddit search API without API key registration?

Yes — it works as a Reddit search API without API key registration or app approval on your side: you supply only the keyword and caps, and results arrive as structured dataset rows.

#### Can I restrict the search to one subreddit?

There is no subreddit input in this Actor. Use a community-specific Actor when one known subreddit is the target.

#### Are comments required?

No. Set `max_comments` to `0` for post-only output. Comments are nested under each post when requested and available.

#### Does one post equal one unique topic?

No. Different posts can discuss the same subject, and the `duplicates` field can contain related source links. Deduplicate according to your research question.

#### Are scores exact vote counts?

Do not assume that. Reddit can obfuscate or change displayed engagement values. Treat them as source-reported signals at processing time.

#### Can I request one million posts?

The schema accepts that ceiling, but availability, cost, source behavior, runtime, and platform limits still apply. Start small and scale only after a successful bounded test.

### Related TrueFetch Actors

- [Reddit User Profile](https://apify.com/truefetch/reddit-user-profile) for one known username and optional activity samples.
- [Reddit Community Profile](https://apify.com/truefetch/reddit-community-profile) for metadata about one known subreddit.
- [Reddit Community Post](https://apify.com/truefetch/reddit-community-post) for post collection from a known subreddit.

### Support

Use the [Actor issue page](https://console.apify.com/actors/Xzx9cQ28OerGtBV3o/issues) for a reproducible technical problem. For general questions, contact [TrueFetch community support](https://t.me/TrueFetch). Review [Apify MCP documentation](https://docs.apify.com/integrations/mcp) for client setup and authentication.

[**Run a one-post test**](https://apify.com/truefetch/reddit-search-api/input) · [**View API options**](https://apify.com/truefetch/reddit-search-api/api)

# Actor input Schema

## `keyword` (type: `string`):

Search keyword to find Reddit posts across all subreddits

## `sort_by` (type: `string`):

Sort results by relevance, hot, top, new, or comment count

## `time_filter` (type: `string`):

Filter results to posts published within a set time period

## `max_posts` (type: `integer`):

Posts to return, minimum 1 and no upper limit. Reddit's search stops near 250 results whatever limit is asked for — measured on queries matching millions of posts — so asking for more returns everything it will serve.

## `max_comments` (type: `integer`):

Comments per post, minimum 0 and no upper limit. A comment tree returns about 450 in one read and names the rest, which this actor then resolves in bounded rounds. Set 0 to skip comments entirely.

## Actor input object example

```json
{
  "keyword": "battery recycling",
  "sort_by": "top",
  "time_filter": "year",
  "max_posts": 3,
  "max_comments": 4
}
```

# Actor output Schema

## `results` (type: `string`):

Reddit posts matching a keyword search, with community context, engagement metrics, media links, crosspost spread, status flags, and an optional bounded comment array.

# 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 = {
    "keyword": "battery recycling",
    "sort_by": "top",
    "time_filter": "year",
    "max_posts": 3,
    "max_comments": 4
};

// Run the Actor and wait for it to finish
const run = await client.actor("truefetch/reddit-search-api").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 = {
    "keyword": "battery recycling",
    "sort_by": "top",
    "time_filter": "year",
    "max_posts": 3,
    "max_comments": 4,
}

# Run the Actor and wait for it to finish
run = client.actor("truefetch/reddit-search-api").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 '{
  "keyword": "battery recycling",
  "sort_by": "top",
  "time_filter": "year",
  "max_posts": 3,
  "max_comments": 4
}' |
apify call truefetch/reddit-search-api --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

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