Documented archive queries for your replacement pipeline
Use both supported authentication headers, documented archive filters, UTC dates and bounded pagination; distinguish retrieval errors from successful empty pages.
Quick start
Send the request from your server and keep your API key private.
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, limit
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
Choose the route and authenticate
Retrieval uses GET at https://api.redditscraping.com with X-API-Key: <key> or Authorization: Bearer <key>. Both headers are supported alternatives. Store the actual key on your server, away from public code. The account panel uses a separate Secure HttpOnly session cookie; that browser session does not replace the key header required by your application to retrieve archived content.
/v1/search searches posts and comments. /v1/posts and /v1/comments restrict results to their respective types. These routes accept q, subreddit, author, kind, from, to, min_score, limit and page. kind accepts post or comment, while the specialized route already fixes its own type. No route accepts a target web URL for crawling, and these search routes do not accept id as a filter.
/v1/item requires id and accepts no other query filters; it looks up one item, not an entire discussion. /v1/subreddits accepts only prefix and limit for community-name lookup, without globally exact counts guaranteed. Public /v1/status needs no key or credits. It describes the service statically and shows that the HTTP application responds, without probing search availability, account balance or payment history.
Validate filters and the returned records
q performs text search, not an arbitrary query language, browser operation or sentiment analysis. subreddit and author restrict the matching records. from and to use strict YYYY-MM-DD dates in UTC and filter created_utc, not archive ingestion time. The whole to day is included. Handle intraday comparisons locally using available record timestamps rather than passing hours to these date parameters.
min_score applies a numerical score threshold and never sorts the response. The server uses internal archive document order _doc, not a record identifier, ingestion timeline, chronology or relevance ranking. Set limit and page between 1 and 100. Each request returns one page with at most 100 records, and one query permits at most 100 pages. More pages do not prove full archive coverage.
A successful retrieval returns data, pagination and credits. The records in data are flat and can have variable or missing fields. Validate what your application requires before normalization; do not assume every item has usable text or relationship metadata. If parent_id and link_id appear, local grouping is possible, but they are not query filters and do not establish complete conversation trees.
Interpret totals and handle each outcome
Read pagination.total together with pagination.relation. eq means an exact query total, gte a lower bound, and unknown an unreliable or unavailable total that can be null. Unknown is not zero. An exact total does not prove that you downloaded all matches. Smaller date windows can organize work but do not guarantee exhaustive retrieval, unique records or repeat-query stability.
HTTP 400 indicates invalid parameters, 401 missing or invalid authentication, 402 insufficient credits and 429 rate limiting. Invalid requests do not debit credits, while upstream failures refund reservations. Each successful retrieval costs one credit, even when data is empty. If your client loses the response after server success, the charge may already have occurred; a successful repeat costs another credit.
Keep original responses before updating local progress. A client wrapper can separate header configuration, request construction, validation and error handling without concealing page boundaries or billing outcomes. Use the account panel for balances and invoices rather than polling /v1/status for information it does not expose. The pricing page explains credit purchases; the guide shows how to test a local mapping against the homepage example.
