API Overview and Integration
The Reddit Archive API provides historical records for Python and JavaScript developers, independently of the official Reddit service. Send your issued key in the X-API-Key request header when calling authenticated retrieval routes. Python HTTP clients and JavaScript fetch can supply this header. Keep the key in your application server configuration rather than embedding it in browser code delivered to visitors.
Response records are flat structures containing data fields rather than pre-assembled server threads. When parent_id and link_id fields exist, clients may group them locally to reconstruct conversation hierarchies. However, this local grouping does not guarantee complete ancestry or exhaustive connection to all related comments and posts. The API does not provide a server-side thread tree for nested structures.
The system uses archive _doc order rather than chronological or relevance sorting for returned results. Pagination limits allow at most 100 records per request and 100 pages per query. Iterating through these pages provides bounded retrieval but does not guarantee complete ingestion or exhaustive coverage of the entire archive. Developers should handle potential gaps carefully when exporting data for analysis.
Parameters and Filtering Logic
Use q for a search expression, subreddit for a community, author for an author, and kind with post or comment. The from and to filters use YYYY-MM-DD dates in UTC; to includes the stated day. min_score filters numeric scores and does not sort results. Set limit from 1 to 100 and page from 1 to 100. The subreddit listing supports an optional prefix.
Item retrieval requires an explicit id parameter for the specific endpoint, whereas posts and comments endpoints do not require an id. This design simplifies bulk data fetching where individual identifiers are unnecessary. The server does not apply local grouping completeness promises; returned records remain flat, meaning client-side logic must handle any hierarchical reconstruction without relying on server-side depth guarantees.
Response totals indicate result counts with varying precision levels. An exact match confirms the precise total, a lower bound indicates a minimum count, and unknown means the total is unreliable. Pagination iteration never guarantees exhaustive coverage because the system is not an exhaustive export mechanism. Developers must rely on these relation signals rather than assuming a complete dataset simply by exhausting available pages.
Errors, Status, and Authentication
HTTP 400 identifies an invalid request, 401 a missing or invalid API key, 402 insufficient credits, and 429 a rate limit. Check the response before attempting another retrieval: a missing key needs a credential correction, while insufficient credit needs an account decision. Invalid or rate-limited requests do not debit credits. Upstream failures refund the reserved credit rather than charging for a completed retrieval.
The status endpoint provides static disclosure about the historical archive scope and confirms HTTP server responsiveness. It does not check backend search health, record availability, or data coverage completeness. A successful status response is uncharged, serving purely as a diagnostic tool. It indicates the system is reachable but offers no guarantees regarding the specific availability of historical records.
Account actions allow key regeneration after password confirmation, which immediately invalidates the previous key. The account panel resides on the key page, not a separate dashboard. Payment uses USDT TRC20 or USDC ERC20 invoices with exact amounts. Successful retrievals, including empty results, consume one credit. Invalid requests do not debit credits, and upstream retrieval failures refund reservations. A client connection failure can occur after a billable server success; a retry that completes successfully costs another credit.
API routes
| Method | Route | Parameters |
|---|---|---|
GET | /v1/search | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/posts | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/comments | q, subreddit, author, kind, from, to, min_score, limit, page |
GET | /v1/item | id |
GET | /v1/subreddits | prefix |
GET | /v1/status | — |
Query parameters
| Parameter | Value / type / range |
|---|---|
q | text |
subreddit | keyword |
author | keyword |
kind | post | comment |
from | ISO date |
to | ISO date |
min_score | integer |
limit | 1–100 |
page | 1–100 |
id | item ID |
prefix | subreddit prefix |
curl -H "Authorization: Bearer YOUR_API_KEY" 'https://api.redditapistack.com/v1/search?q=research&limit=10'
import json, urllib.request
request = urllib.request.Request('https://api.redditapistack.com/v1/search?q=research&limit=10', headers={"Authorization": "Bearer YOUR_API_KEY"})
with urllib.request.urlopen(request) as response:
print(json.load(response))
fetch("https://api.redditapistack.com/v1/search?q=research&limit=10", {headers: {Authorization: "Bearer YOUR_API_KEY"}})
.then(response => response.json()).then(console.log);