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" (Arctic Shift first, PullPush second; an unscoped keyword search goes through web_discovery first), "arctic_shift" (scoped searches and threads), "web_discovery" (unscoped Reddit-wide keyword search), or "pullpush" (the automatic second source; it has refused automated clients since August 2026) 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 Arctic Shift directly — it requires a scope — so it routes to web_discovery first: 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. Whenever Arctic Shift or web_discovery fails a posts or comments search, PullPush is tried second and the response reports fallback_used; PullPush has refused automated clients since August 2026, so that fallback usually reports its refusal as well. 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 (the automatic second source, or 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

data.commentsThread mode: the nested comment tree. A collapsed branch is a {more_count, more_ids} stub: more_count is how many comments it hides, replies included; more_ids lists only the hidden direct replies, so it can be shorter than more_count

data.comment_countThread mode: comments in data.comments at every depth, stubs excluded — at most limit

data.comments_collapsedThread mode: the sum of every stub's more_count — comments the archive holds for this thread that the response leaves out. comment_count + comments_collapsed is what the archive holds; post.num_comments is Reddit's own total from when the archive read the post, so it can be higher (deleted, removed, or not yet archived comments) or lower (comments made after that read)

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