Keep retrieval and account access separate
Protected data requests use GET under https://api.redditapigateway.com. Both X-API-Key: <key> and Authorization: Bearer <key> are accepted alternatives. Use this domain's archive key rather than Reddit OAuth credentials. Keep the secret in protected server configuration and out of public code, URLs and diagnostic logs. An archive key does not encode the roles or budgets of your product's own users.
The account panel on the key page uses email/password access and a Secure HttpOnly session cookie. This is separate from the key header used by your application's retrieval requests. The widget keeps invoice and user identifiers in localStorage per hostname for invoice recovery, not the raw API key. HttpOnly applies to the session cookie, not localStorage. Signing into the panel does not authenticate a separate data client.
/v1/status is public, uncharged and requires no key. It gives a static disclosure of the historical service and confirms that the HTTP application responds. It does not probe the search backend, record availability, usage or balance. Do not turn that response into a product quota check or search-readiness guarantee. Read actual retrieval responses and inspect account balance in the account panel for their respective purposes.
Use each route's documented parameters
/v1/search searches posts and comments. /v1/posts adds a post constraint and /v1/comments a comment constraint. All three accept q, subreddit, author, kind, from, to, min_score, limit and page, not id. kind accepts post or comment; omit it to allow both kinds through search. q is text search rather than arbitrary query DSL, a sentiment classifier or custom server-side analytics.
/v1/item?id=... requires id only and looks for a single archived record, which may be absent. It does not retrieve parents or replies automatically. /v1/subreddits accepts prefix and limit only for community-name discovery, without page traversal or globally exact counts guaranteed. prefix is not a content-route filter. Neither route accepts an arbitrary Reddit URL to crawl or a request for a complete conversation.
from and to require YYYY-MM-DD dates in UTC and filter created_utc rather than archive ingestion time; the final to day is fully included. min_score is a numeric score threshold, without sorting or quality assessment. Content records are flat, and fields may vary. Present parent_id and link_id can support local grouping but are not query filters and do not establish complete ancestry.
Apply page boundaries and billing semantics
Content searches allow limit and page from 1 to 100, one page per request. Results follow internal _doc order, not insertion time, chronology, relevance or score. Local sorting only reorganizes what was received. Smaller intervals, page iteration and local deduplication cannot prove complete coverage or unique records. The archive offers no guaranteed fixed schema, immutable response or permanent record availability.
Responses contain data, pagination and credits. Read pagination.total with relation: eq means an exact query total, gte a lower bound and unknown no reliable total, possibly null. An exact count does not prove all matches were downloaded or all Reddit history is represented. Preserve returned has_more and window_exhausted as boundary signals. The reported balance is not a per-user quota or a future-credit reservation.
Each successful retrieval costs one credit, even empty. Additional pages and successful repeats each have their own cost. Invalid requests do not debit; upstream failures refund reservations. A client disconnect may follow a charged success, and a local processing failure does not refund that success. HTTP 400 concerns parameters, 401 the key, 402 the balance and 429 frequency. Budget retries separately and save responses before advancing a local job.
