RedditCommunity Archives5 credits

reddit_search

Search Reddit posts and comments, or read a full comment thread — without touching reddit.com, which blocks scrapers. Reads the Arctic Shift community archive: free, near-real-time, and no Reddit API credentials required.

Use Cases

Brand & Product Monitoring

Find every mention of your product or company across Reddit, scoped to relevant subreddits or site-wide

Market & Sentiment Research

Mine what real users say about a category, competitor, or pain point in the communities where they discuss it

Thread Reading for AI Agents

Pull a post plus its full nested comment tree in one call — ready for summarization or analysis

Community Trend Tracking

Watch what a subreddit is talking about over a date range using after/before filters

User Research

Retrieve a specific author's posts or comments to understand expert opinions and recurring themes

Endpoint

POST/api/v1/tools/reddit_search

Auth Required

1 req/s on Free plan

5 credits

Parameters

Name	Type	Required	Default	Description
query	string	Optional	-	Keyword search. Posts mode matches title + selftext; comments mode matches body. Supports "quoted phrases", OR, and -exclusion Example: best mechanical keyboard
subreddit	string	Optional	-	Limit results to one subreddit (with or without the r/ prefix) Example: MechanicalKeyboards
author	string	Optional	-	Limit results to one author (with or without the u/ prefix) Example: spez
mode	string	Optional	posts	What to search: "posts" (default), "comments", or "thread" (a post plus its nested comment tree — requires link_id) Example: thread
link_id	string	Optional	-	Post ID (e.g. "1twm1zh" or "t3_1twm1zh") — required for thread mode, optional filter for comments mode Example: 1twm1zh
after	string	Optional	-	Only content posted after this date — ISO 8601, epoch seconds, or an offset like "7d" Example: 7d
before	string	Optional	-	Only content posted before this date — same formats as after Example: 2026-08-01
limit	number	Optional	25	Max results, 1-100 (thread mode: max comments returned) Example: 10
sort	string	Optional	desc	Sort by post date: "desc" (newest first) or "asc" Example: desc
source	string	Optional	auto	Force a specific backend: "auto" (routes and falls back), "arctic_shift" (scoped searches and threads), "web_discovery" (unscoped Reddit-wide keyword search), or "pullpush" (legacy — no longer serves automated clients) Example: auto

reddit.com blocks direct scraping, so reddit_search never touches it. Subreddit- or author-scoped searches and thread mode read the Arctic Shift archive (near-real-time). A keyword search across all of Reddit cannot be served by any archive directly — Arctic Shift requires a scope, and PullPush stopped serving automated clients in August 2026 — so it routes to web_discovery instead: a site-restricted web search finds matching posts, then those post IDs are read from Arctic Shift. That path returns real archive rows, but it caps at 10 posts per call, orders them by web-search relevance rather than score or date, and cannot apply after/before; the response says so in its notes. Every search must include at least one of query, subreddit, or author. Scores and comment counts of content less than ~36 hours old may read 0/1 — the archive captures content the moment it is posted.

One backend is MCP-only. The self-hosted crawlforge-mcp-server package can also read Reddit's official Data API (source: "reddit_api") when you set REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET to your own Reddit app credentials — it returns live scores and complete comment trees on your own quota, and falls back to the archives. This REST endpoint deliberately does not offer it: a shared server-side Reddit key would be commercial use under Reddit's API terms. Note also that Reddit closed self-service API signup in November 2025, so new credentials go through an approval process. Comment full-text search and after/before filters always use the archives, because Reddit's API supports neither.

Request Examples

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/reddit_search \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best mechanical keyboard",
    "subreddit": "MechanicalKeyboards",
    "mode": "posts",
    "limit": 10
  }'

Response Example

200 OK850ms

{
  "success": true,
  "data": {
    "source": "arctic_shift",
    "mode": "posts",
    "query": "best mechanical keyboard",
    "subreddit": "MechanicalKeyboards",
    "author": null,
    "count": 2,
    "results": [
      {
        "id": "1x2y3z4",
        "title": "What's the best mechanical keyboard for programming in 2026?",
        "author": "keeb_enthusiast",
        "subreddit": "MechanicalKeyboards",
        "created_utc": 1755993600,
        "created_iso": "2026-08-24T00:00:00.000Z",
        "score": 142,
        "num_comments": 87,
        "upvote_ratio": 0.96,
        "flair": "Discussion",
        "over_18": false,
        "selftext": "After five years on membrane boards I finally want to switch...",
        "selftext_truncated": false,
        "url": "https://www.reddit.com/r/MechanicalKeyboards/comments/1x2y3z4/",
        "permalink": "https://www.reddit.com/r/MechanicalKeyboards/comments/1x2y3z4/whats_the_best_mechanical_keyboard/"
      }
    ],
    "notes": [
      "Data from the Arctic Shift community archive (arctic-shift.photon-reddit.com), not reddit.com (which blocks scrapers).",
      "Scores and comment counts of content less than ~36h old may read 0/1 — the archive captures content the moment it is posted."
    ],
    "checkedAt": "2026-08-24T14:30:00.000Z"
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 850
}

Field Descriptions

data.sourceWhich backend answered: arctic_shift (scoped, fresher), web_discovery (unscoped Reddit-wide keyword search), or pullpush (legacy, only on explicit request)

data.resultsNormalized posts or comments with full reddit.com permalinks and ISO dates

data.results.selftext_truncatedPost/comment text is capped at 2,000 characters; true when trimmed

data.notesProvenance and freshness caveats for the archive that answered

credits_usedFixed 5 credits per search or thread read

processing_timeArchive searches typically complete in under 2 seconds

Error Handling

Missing Search Scope (400 Bad Request)

Posts and comments modes need at least one of query, subreddit, or author. Thread mode requires link_id.

Unscoped Arctic Shift Search (400 Bad Request)

Arctic Shift cannot keyword-search across all of Reddit. Add a subreddit or author scope, or drop source and let auto route the query to web_discovery.

Thread Mode on a Non-Arctic Backend (400 Bad Request)

Thread mode is Arctic Shift only. source: "pullpush" supports posts and comments search, and source: "web_discovery" only serves unscoped keyword searches.

Invalid Date Filter (400 Bad Request)

after/before must be ISO 8601, epoch seconds, or an offset like "7d".

Archives Unavailable (502 Bad Gateway)

Both community archives failed or are rate limiting. The error message includes each archive's reason. No credits are charged — retry shortly.

Pro Tip: Scope searches to a subreddit or author whenever you can. A scoped query goes straight to Arctic Shift, where limit reaches 100 and after/before work; an unscoped one runs web_discovery, which returns at most 10 posts and ignores date filters. To read a discussion end-to-end, take a post's id from a search result and pass it as link_id with mode: "thread".

Credit Cost

5 credits

5 credits per search

Fixed cost for a search or a full thread read. Credits are charged only for successful requests.

What's Included:

Posts, comments, and full-thread modes

Subreddit, author, and date-range filters

Nested comment trees with reddit-style collapse markers

Full reddit.com permalinks and ISO dates on every result

No Reddit API credentials required

Plan Recommendations:

Free Plan: 1,000 one-time trial credits = 200 searches

Hobby Plan: 5,000 credits = 1,000 searches ($19/mo)

Professional Plan: 50,000 credits = 25,000 searches ($99/mo)

Related Tools

search_web

Search the whole web via Google or DuckDuckGo (5 credits)

summarize_content

Summarize long threads into key points (4 credits)

analyze_content

Sentiment, entities, and keywords from thread text (3 credits)

deep_research

Multi-source research with AI analysis (10 credits)

Ready to try reddit_search? Sign up for free and get 1,000 credits to start mining Reddit discussions.

Use Cases

Brand & Product Monitoring

Find every mention of your product or company across Reddit, scoped to relevant subreddits or site-wide

Market & Sentiment Research

Mine what real users say about a category, competitor, or pain point in the communities where they discuss it

Thread Reading for AI Agents

Pull a post plus its full nested comment tree in one call — ready for summarization or analysis

Community Trend Tracking

Watch what a subreddit is talking about over a date range using after/before filters

User Research

Retrieve a specific author's posts or comments to understand expert opinions and recurring themes

Parameters

Name	Type	Required	Default	Description
query	string	Optional	-	Keyword search. Posts mode matches title + selftext; comments mode matches body. Supports "quoted phrases", OR, and -exclusion Example: best mechanical keyboard
subreddit	string	Optional	-	Limit results to one subreddit (with or without the r/ prefix) Example: MechanicalKeyboards
author	string	Optional	-	Limit results to one author (with or without the u/ prefix) Example: spez
mode	string	Optional	posts	What to search: "posts" (default), "comments", or "thread" (a post plus its nested comment tree — requires link_id) Example: thread
link_id	string	Optional	-	Post ID (e.g. "1twm1zh" or "t3_1twm1zh") — required for thread mode, optional filter for comments mode Example: 1twm1zh
after	string	Optional	-	Only content posted after this date — ISO 8601, epoch seconds, or an offset like "7d" Example: 7d
before	string	Optional	-	Only content posted before this date — same formats as after Example: 2026-08-01
limit	number	Optional	25	Max results, 1-100 (thread mode: max comments returned) Example: 10
sort	string	Optional	desc	Sort by post date: "desc" (newest first) or "asc" Example: desc
source	string	Optional	auto	Force a specific backend: "auto" (routes and falls back), "arctic_shift" (scoped searches and threads), "web_discovery" (unscoped Reddit-wide keyword search), or "pullpush" (legacy — no longer serves automated clients) Example: auto

Request Examples

terminalBash

curl -X POST https://crawlforge.dev/api/v1/tools/reddit_search \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best mechanical keyboard",
    "subreddit": "MechanicalKeyboards",
    "mode": "posts",
    "limit": 10
  }'

Response Example

200 OK850ms

{
  "success": true,
  "data": {
    "source": "arctic_shift",
    "mode": "posts",
    "query": "best mechanical keyboard",
    "subreddit": "MechanicalKeyboards",
    "author": null,
    "count": 2,
    "results": [
      {
        "id": "1x2y3z4",
        "title": "What's the best mechanical keyboard for programming in 2026?",
        "author": "keeb_enthusiast",
        "subreddit": "MechanicalKeyboards",
        "created_utc": 1755993600,
        "created_iso": "2026-08-24T00:00:00.000Z",
        "score": 142,
        "num_comments": 87,
        "upvote_ratio": 0.96,
        "flair": "Discussion",
        "over_18": false,
        "selftext": "After five years on membrane boards I finally want to switch...",
        "selftext_truncated": false,
        "url": "https://www.reddit.com/r/MechanicalKeyboards/comments/1x2y3z4/",
        "permalink": "https://www.reddit.com/r/MechanicalKeyboards/comments/1x2y3z4/whats_the_best_mechanical_keyboard/"
      }
    ],
    "notes": [
      "Data from the Arctic Shift community archive (arctic-shift.photon-reddit.com), not reddit.com (which blocks scrapers).",
      "Scores and comment counts of content less than ~36h old may read 0/1 — the archive captures content the moment it is posted."
    ],
    "checkedAt": "2026-08-24T14:30:00.000Z"
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 850
}

Field Descriptions

data.sourceWhich backend answered: arctic_shift (scoped, fresher), web_discovery (unscoped Reddit-wide keyword search), or pullpush (legacy, only on explicit request)

data.resultsNormalized posts or comments with full reddit.com permalinks and ISO dates

data.results.selftext_truncatedPost/comment text is capped at 2,000 characters; true when trimmed

data.notesProvenance and freshness caveats for the archive that answered

credits_usedFixed 5 credits per search or thread read

processing_timeArchive searches typically complete in under 2 seconds

Error Handling

Missing Search Scope (400 Bad Request)

Posts and comments modes need at least one of query, subreddit, or author. Thread mode requires link_id.

Unscoped Arctic Shift Search (400 Bad Request)

Arctic Shift cannot keyword-search across all of Reddit. Add a subreddit or author scope, or drop source and let auto route the query to web_discovery.

Thread Mode on a Non-Arctic Backend (400 Bad Request)

Thread mode is Arctic Shift only. source: "pullpush" supports posts and comments search, and source: "web_discovery" only serves unscoped keyword searches.

Invalid Date Filter (400 Bad Request)

after/before must be ISO 8601, epoch seconds, or an offset like "7d".

Archives Unavailable (502 Bad Gateway)

Both community archives failed or are rate limiting. The error message includes each archive's reason. No credits are charged — retry shortly.

Credit Cost

5 credits

5 credits per search

Fixed cost for a search or a full thread read. Credits are charged only for successful requests.

What's Included:

Posts, comments, and full-thread modes

Subreddit, author, and date-range filters

Nested comment trees with reddit-style collapse markers

Full reddit.com permalinks and ISO dates on every result

No Reddit API credentials required

Plan Recommendations:

Free Plan: 1,000 one-time trial credits = 200 searches

Hobby Plan: 5,000 credits = 1,000 searches ($19/mo)

Professional Plan: 50,000 credits = 25,000 searches ($99/mo)