Authenticate and choose a documented route
Use GET at https://api.redditfetch.com with X-API-Key: <key> or Authorization: Bearer <key>. Both header formats are supported. Your application should supply the actual key from its backend configuration rather than expose it in browser code. The Secure HttpOnly cookie used by the website account panel is separate from these headers; signing in to the site does not authenticate your application’s retrieval request.
/v1/search searches archived posts and comments; /v1/posts and /v1/comments restrict retrieval to their corresponding types. All three accept q, subreddit, author, kind, from, to, min_score, limit and page. kind uses the literal values post and comment, while a type-specific route already constrains its own type. These routes do not accept id, an arbitrary upstream URL or a custom query language.
/v1/item requires id and accepts no other query filters. It looks up one item rather than recursively obtaining an entire thread. /v1/subreddits accepts only prefix and limit for community-name lookup; its aggregation counts are not guaranteed globally exact. Public /v1/status requires neither a key nor credits and returns static service-scope information rather than account details or a search-health result.
Validate records, dates and page metadata
q provides text search, not sentiment analysis or a classification of useful JavaScript answers. subreddit and author narrow matches to the specified community or author. from and to require YYYY-MM-DD dates in UTC and apply to created_utc, not ingestion time. The entire to day is included. Intraday processing belongs in your local code using record timestamps when available.
min_score applies a numeric score threshold without changing order. Results use internal archive document order _doc, not document-ID order, ingestion chronology, publication time, relevance or score rank. limit and page range from 1 to 100. Each request retrieves one page of at most 100 records; one query allows at most 100 pages. Dividing periods can organize work but cannot prove exhaustive or duplicate-free retrieval.
A successful retrieval contains data, pagination and credits. Check data as an array before processing its flat records. Fields can vary or be absent. If parent_id or link_id appears, local grouping is optional; those fields are not search filters and do not guarantee complete ancestry. A client-side mapping should preserve missing context instead of manufacturing a parent or assuming a complete conversation.
Read pagination.total alongside pagination.relation: eq reports an exact query total, gte a lower bound, and unknown no reliable total, possibly null. Unknown is not zero. Even an exact total does not prove every match was downloaded or every historical comment is archived. Preserve returned page indicators with your collected evidence rather than inventing cursor tokens that this API does not provide.
Separate errors, success and accounting
The status endpoint returns a static disclosure proving the HTTP server responds, but it does not check search backend health or record availability. It is public and uncharged. Use it to confirm basic server responsiveness, but inspect your actual account interface for balance details and invoice verification. The status route does not report upstream load conditions or data coverage completeness for your queries.
HTTP 400 means invalid parameters, 401 missing or invalid authentication, 402 insufficient credits and 429 rate limiting. Correct the cause of 400, 401 or 402 rather than repeatedly issuing the same request. Delayed, bounded retries can be appropriate for 429. The network-wide trial eligibility rules are separate from request-rate limits; do not infer trial status from a rate-limit response. Invalid requests do not debit credits; upstream failures refund reserved credits. One successful retrieval, even empty, costs one credit. A client timeout or lost connection can follow billable server success, so a successful repeat costs another credit. Store validated responses before advancing local progress, and keep your own application’s errors separate from the archive’s HTTP outcome.
