Searching Reddit Programmatically: The API Guide

The practical reference: get a key, make your first call, paginate correctly, filter with q=, and pull real comment counts during Reddit's fresh-post blackout. Every example is copy-pasteable against the live API.

How do I get a Reddit API key?

Sign up — no card required — for $0.50 of free credit (333 reads), create a key from /developer, and send it as x-api-key:

curl -s "https://api.threadsnoop.com/v1/posts?subreddit=SaaS&limit=25" \
  -H "x-api-key: YOUR_KEY"

Every endpoint returns the same envelope:

{
  "data": [ /* raw Reddit-shaped post or comment objects */ ],
  "_threadsnoop": {
    "cursor": "t3_1abcdef",
    "has_more": true,
    "credits_used": 1,
    "credits_remaining": 332
  }
}

data passes through Reddit's own field names — no schema to learn. Reads are $1.50 per 1,000 (as low as $1.00/1,000 in bulk), 1 credit per request regardless of endpoint.

How does pagination work?

Pass the cursor back as after= when sorting oldest-first (sort=asc) or before= when sorting newest-first (sort=desc, default). Stop at has_more: false. Ask for limit=100 — fewer results per page just means more pages, and every page costs 1 credit regardless of size.

How do I filter Reddit posts by keyword?

Both listing endpoints take q= for an exact-phrase match (with basic plural flexing), applied server-side before the page comes back:

curl -s "https://api.threadsnoop.com/v1/comments?subreddit=freelance&q=invoice&limit=100" \
  -H "x-api-key: YOUR_KEY"

You pay per page scanned, not per match found— a page with zero matches still costs 1 credit, since it's one upstream read either way. Scope a rare phrase with after=/before= first rather than paginating a year of history blind.

Why does a fresh Reddit post show 0 comments?

Reddit doesn't finalize a post's score or comment count for roughly 36 hours — until then, /v1/posts shows a placeholder (score: 1, num_comments: 0) even with real replies already in. For the actual count on something fresh, pull the tree directly:

curl -s "https://api.threadsnoop.com/v1/comments/tree?post_id=t3_1abcdef&limit=100" \
  -H "x-api-key: YOUR_KEY"

How do I monitor a subreddit automatically?

There's no webhook — this is a pull API — so monitoring means calling on a schedule and tracking the newest ID you've seen, e.g. a 0 * * * * python3 poll.py cron entry that fetches sort=desc and stops once it hits last run's newest post. Every key gets the same rate limit — 2 req/s, burst 10 — and GET /v1/account (free, 0 credits) returns your balance and limit any time.

Everything above is a for-loop and an if-statement, on purpose — filtering intelligence is meant to live in your code or your agent, not ours. From Claude, Codex, or another MCP client, the same six endpoints are exposed as tools and the loop is handled for you — see using AI agents to search Reddit. And if you got here wondering why Claude can't already do this itself: why can't Claude Code search Reddit.

Frequently asked questions