The Official API, Rate Limits, JSON Endpoints, and PRAW

Learning objectives

• State the free-tier rate limits for OAuth vs. unauthenticated Reddit API access.
• Explain the correct pattern for handling Reddit's rate-limit headers.
• Describe the Responsible Builder Policy's approval-before-token requirement.
• Explain PRAW's read-only vs. authorized instance model.
• Explain why the .json endpoint trick is unsuitable for production.

Prerequisites: Stage 1 in full, especially the ethics-line lesson; Stage 4 Lesson 4.4.2 (red-line document).

Core concepts

Every automation this stage builds sits on one API with hard limits. Reddit's free tier allows roughly 100 queries per minute (QPM), averaged over a 10-minute window, for an OAuth-authenticated client, but only about 10 QPM for unauthenticated access, and non-OAuth traffic is now blocked outright under the Responsible Builder Policy (support.reddithelp.com; painonsocial.com). Every request needs a unique User-Agent formatted platform:app_id:version (by /u/username), a generic one gets throttled hard. Reddit also enforces a hard ~1,000-item listing cap on every endpoint (hot, new, top, search): you cannot paginate past 1,000 results, which is why high-volume monitoring needs a rolling stream, not deep pagination (roundproxies; thunderbit). Every response carries X-Ratelimit-Used/Remaining/Reset headers, read them continuously and back off exponentially; never blind-sleep a fixed interval.

Getting a token changed materially in late 2025: every app now requires approval before any token is issued, and commercial use, brand monitoring, lead gen, competitor tracking, reselling, requires a signed contract at roughly $0.24/1,000 requests with a 2-4 week review (octolens.com). Budget for that lead time explicitly.

Don't write raw HTTP calls by hand. PRAW (praw-dev/praw) is the canonical Python wrapper, a 2024 r/redditdev survey found roughly 80% of bot builders use it over raw requests, since it handles OAuth refresh, pagination, and backoff automatically (praw.readthedocs.io). A PRAW instance has two states: read-only (public data only) and authorized (full account actions), keep monitoring scripts read-only by design. Real-time monitoring uses subreddit.stream.submissions()/stream.comments(); pass skip_existing=True or it replays ~100 historical items on startup, and know high-volume streams (r/all especially) can silently drop comments under load.

import praw

reddit = praw.Reddit(
    client_id="{{client_id}}",
    client_secret="{{client_secret}}",
    user_agent="webapp:mybrand-monitor:v1.0 (by /u/{{your_reddit_username}})",
)  # read-only by default

for comment in reddit.subreddit("SaaS+devops+sysadmin").stream.comments(skip_existing=True):
    if "{{brand_or_competitor_keyword}}" in comment.body.lower():
        print(f"Mention found: {comment.permalink}")  # log, do NOT auto-reply here

For JavaScript/TypeScript builds, relevant heading into MCP servers later, snoowrap (not-an-aardvark/snoowrap) is the equivalent: async, Promise-based, auto-refreshes OAuth tokens, supports live-thread websockets. For completeness, not production use: appending .json to any public Reddit URL still returns structured data with no auth, rate-limited ~60 req/min by user-agent, but these endpoints increasingly return 403 in 2026 (til.simonwillison.net).

Video lessons

Supporting reading

• Reddit Data API Wiki, Reddit Help (https://support.reddithelp.com/hc/en-us/articles/16160319875092-Reddit-Data-API-Wiki), authoritative rate-limit and OAuth terms.
• praw-dev/praw, GitHub (https://github.com/praw-dev/praw), canonical library; read-only vs. authorized is the core mental model.
• PRAW Submission Stream Reply Bot tutorial (https://praw.readthedocs.io/en/latest/tutorials/reply_bot.html), official streaming code pattern with skip_existing.
• Reddit Responsible Builder Policy (https://support.reddithelp.com/hc/en-us/articles/42728983564564-Responsible-Builder-Policy), the governing document for what any app may do.

Exercise

Register a read-only Reddit API app, install PRAW, and stream comments from three relevant subreddits, printing any comment containing your brand or a competitor's name. Do not post anything. Confirm your User-Agent format is correct.

Assignment

Write a one-page API constraints memo: OAuth vs. unauthenticated QPM limits, the 1,000-item cap and its design implication, the commercial-contract threshold and timeline, and whether your use case needs that contract.

Claude workflow

• Skill idea: a "rate-limit budget" skill that checks a subreddit list and poll frequency against the 100 QPM ceiling before code gets written.
• Automation opportunity: a scheduled read-only PRAW script logging mentions is fully automatable end to end, it never touches posting/voting/DMs.

Expected outcomes

• States OAuth (100 QPM) vs. unauthenticated (10 QPM) limits from memory.
• Working read-only PRAW script logging mentions from three subreddits.
• API constraints memo on file.