Read Private and Member-Only Subreddits With Your Own Session

Reads on this API are anonymous by default. They are served from our pool of logged-in accounts, which is why you send no cookies for them and why they work with nothing but your API key.

That default cannot answer everything. A private subreddit, a restricted one, a member-only community, or your own front page are all invisible to an account that is not yours. Send your own Reddit session on the request and the same endpoint fetches the same thing as you.

Nothing changes unless you opt in

This is additive. If you send no session headers, every read behaves exactly as it did before: same pool, same response, same billing. Existing integrations need no change and were not affected by this feature shipping.

Send the session as headers

Get the values from POST /api/reddit/login, which returns your cookie jar. Send them as headers:

curl "https://api.redditapis.com/api/reddit/posts?subreddit=your_private_sub" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-reddit-session: YOUR_REDDIT_SESSION" \
  -H "x-reddit-loid: YOUR_LOID"

Headers, not query parameters. A Reddit session cookie grants full control of that account, and anything in a query string is written into access logs, proxy logs and browser history along the way. Headers are not.

Send both or neither

x-reddit-session without x-reddit-loid (or the reverse) is a 400 with code: "INCOMPLETE_SESSION", naming the header you left out.

It would be easy to fall back to an anonymous read there instead. That is exactly what makes it a bad idea: a private subreddit read anonymously comes back empty, and an empty listing is indistinguishable from a quiet one. You would get a plausible answer to a question you did not ask.

Reading through your own proxy

Add x-reddit-proxy to make the read leave from an IP you control, so it reaches Reddit from where that account normally acts:

-H "x-reddit-proxy: http://user:pass@host:port"

Same forms and the same behaviour as the write endpoints, including that your proxy is pinned for every retry, so a retry cannot move your account onto a different IP. Full detail on Proxies.

Without it, an authenticated read egresses through our shared pool. That egress is pinned for the request too, so your account is never presented to Reddit from several addresses in one call, but the address is ours rather than yours. Fine for most reads, and the wrong choice for an account with a strong geographic history.

A proxy sent without a session is a 400, not a silently anonymous read. There would be no account to act as, so the read would come from our egress while you believed it came from yours.

Which endpoints accept a session

The four user/:name/* listings have always required a session and have always taken it as query parameters. They now accept the header form too, and the query form keeps working. If you send both, the headers win, so a stale query parameter you forgot to delete cannot quietly serve you.

Errors

A rejected or expired session is always one of these, never a 200 with an empty list.

The 502 / 503 split is deliberate: a failure of your proxy is described so you can act on it, and a failure of ours is our problem to absorb rather than yours to pay for.

One thing this does not detect

If Reddit accepts your cookie but treats the request as logged out, a read of a public subreddit still returns real data and nothing marks it. For a private subreddit it surfaces correctly as 403, and for the feed as 403, so the gap is limited to public content, where the answer is at least not wrong. If you need certainty that a session is live, call GET /api/reddit/feed: it cannot be served without one.