Reddit Read-Only
Overview
Browse and search Reddit programmatically using the public JSON API. Fetch posts from subreddits, search for topics, retrieve comment threads, and access trending content. No API key or authentication is needed. All access is read-only.
Instructions
When a user asks you to browse or search Reddit, follow these steps:
Step 1: Determine the request type
Identify what the user wants:
- Browse a subreddit: Fetch posts from a specific subreddit (hot, new, top, rising)
- Search Reddit: Find posts matching a query across Reddit or within a subreddit
- Read a thread: Fetch a specific post and its comments
- Get trending content: Check what is popular right now
Step 2: Use the public JSON API
Reddit exposes JSON data by appending .json to most URLs:
import requests
import time
from datetime import datetime
HEADERS = {"User-Agent": "reddit-readonly-bot/1.0.0"}
BASE_URL = "https://www.reddit.com"
def get_subreddit_posts(subreddit, sort="hot", time_filter="day", limit=25):
"""Fetch posts from a subreddit.
Args:
subreddit: Subreddit name without r/ prefix
sort: One of 'hot', 'new', 'top', 'rising'
time_filter: For 'top' sort: 'hour', 'day', 'week', 'month', 'year', 'all'
limit: Number of posts (max 100)
"""
url = f"{BASE_URL}/r/{subreddit}/{sort}.json"
params = {"limit": min(limit, 100), "t": time_filter}
response = requests.get(url, headers=HEADERS, params=params, timeout=30)
response.raise_for_status()
time.sleep(1)
posts = []
for child in response.json()["data"]["children"]:
p = child["data"]
posts.append({
"title": p["title"],
"author": p.get("author", "[deleted]"),
"score": p["score"],
"num_comments": p["num_comments"],
"selftext": p.get("selftext", "")[:500],
"url": p.get("url", ""),
"permalink": f"https://reddit.com{p['permalink']}",
"created": datetime.utcfromtimestamp(p["created_utc"]).isoformat(),
"subreddit": p["subreddit"],
})
return posts
def search_reddit(query, subreddit=None, sort="relevance", time_filter="year", limit=25):
"""Search for posts matching a query."""
if subreddit:
url = f"{BASE_URL}/r/{subreddit}/search.json"
params = {"q": query, "sort": sort, "t": time_filter,
"limit": min(limit, 100), "restrict_sr": "on"}
else:
url = f"{BASE_URL}/search.json"
params = {"q": query, "sort": sort, "t": time_filter,
"limit": min(limit, 100)}
response = requests.get(url, headers=HEADERS, params=params, timeout=30)
response.raise_for_status()
time.sleep(1)
posts = []
for child in response.json()["data"]["children"]:
p = child["data"]
posts.append({
"title": p["title"],
"score": p["score"],
"num_comments": p["num_comments"],
"subreddit": p["subreddit"],
"permalink": f"https://reddit.com{p['permalink']}",
"selftext": p.get("selftext", "")[:300],
})
return posts
def get_comments(permalink, sort="top", limit=100):
"""Fetch comments for a post given its permalink path."""
# permalink should be like /r/subreddit/comments/id/title/
url = f"{BASE_URL}{permalink}.json"
params = {"sort": sort, "limit": limit}
response = requests.get(url, headers=HEADERS, params=params, timeout=30)
response.raise_for_status()
time.sleep(1)
comments = []
data = response.json()
if len(data) > 1:
_extract_comments(data[1]["data"]["children"], comments, depth=0)
return comments
def _extract_comments(children, comments, depth):
"""Recursively extract comments from nested structure."""
for child in children:
if child["kind"] != "t1":
continue
c = child["data"]
comments.append({
"body": c["body"],
"author": c.get("author", "[deleted]"),
"score": c["score"],
"depth": depth,
})
# Extract replies
if c.get("replies") and isinstance(c["replies"], dict):
_extract_comments(
c["replies"]["data"]["children"], comments, depth + 1
)
Step 3: Format and present results
Format the output clearly for the user:
For subreddit browsing:
r/programming - Hot Posts
========================
1. [523 pts | 89 comments] "Why Rust is replacing C++ in embedded systems"
https://reddit.com/r/programming/comments/abc123/...
2. [312 pts | 45 comments] "SQLite internals: How the query planner works"
https://reddit.com/r/programming/comments/def456/...
3. [298 pts | 112 comments] "Ask r/programming: What's your unpopular tech opinion?"
Preview: "I'll start: ORMs cause more problems than they solve..."
https://reddit.com/r/programming/comments/ghi789/...
For comment threads:
Thread: "Why did you switch from VS Code to Neovim?"
r/neovim | 445 pts | 203 comments
Top Comments:
[189 pts] u/vimuser42: "Speed. My VS Code took 8 seconds to open a
large TypeScript project. Neovim opens instantly."
[67 pts] u/reply_user: "Same experience. The LSP integration in
Neovim has gotten so good there's no feature gap anymore."
[145 pts] u/pragmatic_dev: "Honestly, the keybindings. Once you learn
modal editing, going back to click-and-type feels slow."
Step 4: Handle pagination for large requests
def get_all_posts(subreddit, sort="new", limit=500):
"""Fetch multiple pages of posts using pagination."""
all_posts = []
after = None
while len(all_posts) < limit:
url = f"{BASE_URL}/r/{subreddit}/{sort}.json"
params = {"limit": 100}
if after:
params["after"] = after
response = requests.get(url, headers=HEADERS, params=params, timeout=30)
response.raise_for_status()
time.sleep(1)
data = response.json()["data"]
children = data["children"]
if not children:
break
for child in children:
all_posts.append(child["data"])
after = data.get("after")
if not after:
break
return all_posts[:limit]
Examples
Example 1: Browse top posts in a subreddit
User request: "Show me the top posts in r/machinelearning from this week."
Execution:
posts = get_subreddit_posts("machinelearning", sort="top", time_filter="week", limit=10)
for i, post in enumerate(posts, 1):
print(f"{i}. [{post['score']} pts] {post['title']}")
print(f" {post['permalink']}")
Example 2: Search for a specific topic
User request: "Find Reddit discussions about migrating from MongoDB to PostgreSQL."
Execution:
posts = search_reddit(
query="migrate MongoDB to PostgreSQL",
sort="relevance",
time_filter="year",
limit=20
)
Example 3: Read a full comment thread
User request: "Read the comments on this Reddit post: https://reddit.com/r/webdev/comments/xyz/..."
Execution:
permalink = "/r/webdev/comments/xyz/post_title/"
comments = get_comments(permalink, sort="top", limit=50)
for c in comments:
indent = " " * c["depth"]
print(f"{indent}[{c['score']} pts] u/{c['author']}: {c['body'][:200]}")
Guidelines
- Always include a 1-second delay between requests to avoid being rate-limited by Reddit.
- Set a descriptive User-Agent header. Reddit blocks requests without one and may return 429 errors.
- The public JSON API has a hard limit of 100 items per request. Use the
afterparameter for pagination. - All access is read-only. This skill cannot post, vote, or modify any Reddit content.
- Truncate long selftext and comment bodies when displaying summaries. Show full text only when the user requests a specific post.
- Handle deleted posts and comments gracefully. Check for
[deleted]or[removed]content. - Reddit may return 403 or 429 errors during high traffic. Implement retry logic with exponential backoff.
- Respect that some subreddits are private and will return 403 errors. Inform the user and suggest alternatives.
- Do not attempt to access quarantined or NSFW subreddits without the user explicitly requesting it.
- Always provide permalink URLs so the user can visit the original discussion in their browser.