Authentication and request outcomes
Send authenticated GET requests to https://api.subredditapi.com with X-API-Key: <key> or Authorization: Bearer <key>. Both headers are supported. Keep the key in your server configuration, outside published datasets and diagnostic logs. The account panel uses a separate Secure HttpOnly session cookie. Signing into that panel does not replace the API-key header used to retrieve archived records.
HTTP 400 means an invalid request, 401 a missing or invalid key, 402 insufficient credit and 429 a rate limit. Correct parameters before retrying 400 and check the credential for 401. For 402, pause the collection or decide whether to top up. For 429, wait and bound your retries. Check the status before treating the response body as a successful sample.
Each successful retrieval consumes one credit, even if empty. Invalid requests do not debit the balance and upstream failures refund the reservation. A client may lose its connection after a successful, billable server retrieval. A successful repeat costs another credit. Keep attempt outcomes separately from the number of records you accepted into your research dataset; local rejection does not reverse an API charge.
Endpoint structure and filtering
The available routes are /v1/search, /v1/posts, /v1/comments, /v1/item, /v1/subreddits and /v1/status. Use search for supported text queries, posts for posts and comments for comments. Only /v1/item requires id for a known record; id is not a posts or comments filter. /v1/subreddits accepts prefix and limit for community discovery, without guaranteeing globally exact aggregation counts.
Search parameters are q, subreddit, author, kind, from, to, min_score, limit and page. kind accepts post or comment. Dates use YYYY-MM-DD in UTC and to includes the specified day. min_score sets a numeric threshold and does not sort. No arbitrary query DSL, server-side sentiment analysis, posting, voting or private messaging is provided by this independent historical service.
Pagination is controlled by limit and page parameters, both bounded between 1 and 100. The archive returns up to 100 records per request, ensuring manageable data payloads. Use page to iterate through results sequentially. Remember that iterating through pages does not guarantee full coverage or exhaustive export, as the archive structure may have gaps or ordering variations.
For the soil example, q=soil and subreddit=gardening restrict the search while limit=3 requests at most three records. Compare another community through a separate query, recording any changed parameter. The API returns flat records. Local grouping is possible when parent_id or link_id is present, but neither field is an exposed filter and a complete conversation tree is not guaranteed.
Pagination and interpretation
Pagination totals indicate the number of results but carry specific semantic relations. An exact total means the count is precise, while a greater-than-or-equal bound indicates a lower limit. An unknown total suggests the system cannot reliably determine the full count. These distinctions are vital for understanding the completeness of your query results without assuming exhaustive coverage.
Read relation with total: eq denotes an exact query total, gte a lower bound and unknown no reliable total, which may be null. Results use internal document order _doc, not chronological, relevance or score sorting. One request fetches one page of at most 100 records, with page limited to 1 through 100. Reaching the last permitted page does not establish exhaustive collection.
Preserve the actual responses, query parameters and retrieval time locally. These artifacts help you explain a selection or repeat its local processing. Repeating the remote query does not guarantee identical records. /v1/status is public and uncharged; it returns static historical-scope information and shows that the HTTP app responds. It does not probe the search backend, archive completeness, capacity or retrieval latency.
