reddit_search
Use this to search Reddit posts or comments, or read a full comment thread - reddit.com blocks direct scraping, so this reads the Arctic Shift community archive instead (free, no Reddit credentials).
Instructions
Use this to search Reddit posts or comments, or read a full comment thread - reddit.com blocks direct scraping, so this reads the Arctic Shift community archive instead (free, no Reddit credentials). Modes: 'posts' (default) and 'comments' search; 'thread' returns a post plus its nested comment tree by link_id. A subreddit/author-scoped search queries the archive directly. A keyword search across ALL of Reddit finds posts with a site-restricted web search and then reads those posts from the archive, because Arctic Shift can only keyword-search within a scope; results come back as real archive rows, ordered by search relevance. An unscoped COMMENT search discovers posts the same way and then searches each post's comments for the keywords. A scoped comment search Arctic Shift times out on is retried over narrower windows (7d, 3d, 1d) and reports window_applied. Arctic Shift is tried first and the PullPush archive second for posts/comments searches (fallback_used says so; PullPush has refused automated clients since August 2026). Not for reddit.com URLs via scrape or fetch_url (blocked) - use mode:'thread' with the post's link_id. Cost: 5 credits. Example: reddit_search({query: "best mechanical keyboard", subreddit: "MechanicalKeyboards", limit: 10})
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | What to search: posts (default), comments, or thread (full comment tree — requires link_id) | |
| sort | No | Sort by post date (default desc = newest first) | |
| after | No | Only content posted after this date — ISO 8601, epoch seconds, or an offset like '7d' | |
| limit | No | Max results (default 25; thread mode: max comments returned) | |
| query | No | Keyword search. Posts: matches title+selftext; comments: matches body. Supports "quoted phrases", OR, -exclusion | |
| author | No | Limit to one author (with or without the u/ prefix) | |
| before | No | Only content posted before this date — same formats as after | |
| source | No | Backend: auto routes + falls back (default). web_discovery serves only unscoped keyword searches (web search finds the posts, the archive supplies the rows). reddit_api uses the official Reddit Data API — only when REDDIT_CLIENT_ID/REDDIT_CLIENT_SECRET are set; serves posts/thread, not comment search | |
| link_id | No | Post ID (e.g. '1twm1zh' or 't3_1twm1zh') — required for thread mode, optional filter for comments mode | |
| subreddit | No | Limit to one subreddit (with or without the r/ prefix) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| post | No | thread mode: the post itself | |
| _cost | No | Cost-transparency metadata (D3.5): what this call was projected to cost and what it was charged | |
| cache | No | Page cache: whether this call reused a copy of the page fetched earlier in the session | |
| count | No | ||
| notes | No | Data-provenance caveats (archive freshness, coverage gaps) | |
| query | No | ||
| author | No | ||
| source | No | Which backend served this result — an archive, or web discovery (site-restricted web search hydrated from the archive) for Reddit-wide keyword search | |
| link_id | No | Present in thread mode | |
| results | No | posts/comments modes | |
| comments | No | thread mode: nested comment tree ({...comment, replies:[...]}); a collapsed branch appears as a {more_count, more_ids} stub, where more_count is how many comments it hides, replies included, and more_ids lists only the hidden direct replies, so more_ids can be shorter than more_count | |
| checkedAt | No | ||
| next_step | No | Failed calls only: the tool or fix to try next | |
| subreddit | No | ||
| discovered | No | web_discovery: how many post ids the site-restricted web search surfaced before archive hydration | |
| comment_count | No | thread mode: comments in `comments` at every depth, stubs excluded; at most limit | |
| fallback_used | No | Present when the primary archive failed and the fallback served the result | |
| posts_searched | No | web_discovery comments mode: how many discovered posts had their comments searched before limit was reached | |
| window_applied | No | arctic_shift comments mode: the after-window ("7d"/"3d"/"1d") the search was narrowed to after the full-history search timed out; absent when the caller set after or no narrowing was needed | |
| comments_collapsed | No | thread mode: the sum of every stub's more_count, i.e. comments the source holds for this thread that the response leaves out. comment_count + comments_collapsed is what the source holds; post.num_comments is Reddit's own total from when the post was read, so it can be higher (deleted, removed or not yet archived comments) or lower (comments made after that read) |