RedditCommunity Archives2 credits

reddit_search

Search Reddit posts and comments, or read a full comment thread — without touching reddit.com, which blocks scrapers. Queries the Arctic Shift and PullPush community archives: 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

2 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 archive backend: "auto" (routes and falls back), "arctic_shift", or "pullpush" Example: auto

reddit.com blocks direct scraping, so reddit_search never touches it. Subreddit- or author-scoped searches and thread mode use the Arctic Shift archive (near-real-time); keyword searches across all of Reddit route to PullPush, which has known gaps in its post-2023 archive. 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 archives capture content the moment it is posted.

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": 2,
  "credits_remaining": 998,
  "processing_time": 850
}

Field Descriptions

data.sourceWhich archive answered: arctic_shift (scoped, fresher) or pullpush (site-wide keyword search)

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 2 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 use source: "pullpush".

Thread Mode via PullPush (400 Bad Request)

Thread mode is Arctic Shift only — source: "pullpush" supports posts and comments search.

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 — scoped queries route to Arctic Shift, which is fresher and more reliable than the site-wide PullPush path. 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

2 credits

2 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 = 500 searches

Hobby Plan: 5,000 credits = 2,500 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 archive backend: "auto" (routes and falls back), "arctic_shift", or "pullpush" 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": 2,
  "credits_remaining": 998,
  "processing_time": 850
}

Field Descriptions

data.sourceWhich archive answered: arctic_shift (scoped, fresher) or pullpush (site-wide keyword search)

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 2 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 use source: "pullpush".

Thread Mode via PullPush (400 Bad Request)

Thread mode is Arctic Shift only — source: "pullpush" supports posts and comments search.

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

2 credits

2 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 = 500 searches

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

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