Authentication and route boundaries
Authenticated retrieval accepts X-API-Key: <key> or Authorization: Bearer <key>. Use either supported header with requests to https://api.redditcommentsapi.com. Account sign-in uses a separate Secure HttpOnly session cookie; signing into the website does not replace the retrieval header in your application. Never embed a working key in public examples or browser code distributed to visitors.
GET /v1/search searches archived records. GET /v1/posts and GET /v1/comments restrict retrieval to posts and comments respectively. These three routes support q, subreddit, author, kind, from, to, min_score, limit and page. The kind values are post and comment; each type-specific route already fixes its own type. None of these routes accepts id as a search filter.
GET /v1/item requires id and accepts no other query filters. It retrieves an individual item rather than a discussion tree. GET /v1/subreddits accepts only prefix and limit for community-name lookup; it does not expose a hierarchy of communities, and aggregation counts are not guaranteed globally exact. Public GET /v1/status is uncharged and requires no key.
Dates, pages and interpretation
The q parameter provides text search, not an arbitrary query language or sentiment classifier. Use subreddit and author to restrict the selected records. Dates in from and to must use YYYY-MM-DD and UTC; to includes the whole final day. These bounds apply to created_utc, not archive ingestion time. Intraday intervals must be handled locally using available record timestamps.
Set limit and page within 1–100. Each request retrieves one page of at most 100 records, and a query permits at most 100 pages. The internal order _doc is archive document order, not an identifier, insertion-time sequence, chronological sort or relevance rank. The min_score threshold filters records but does not change this ordering or sort results by score.
Read pagination.relation together with pagination.total. The value eq reports an exact query total, gte reports a lower bound, and unknown means there is no reliable total, which may be null. An exact total does not establish that you downloaded every match. Splitting dates or iterating pages can organize retrieval but does not guarantee exhaustive or duplicate-free collection.
Relationships, failures and credit accounting
It is crucial to note that the server does not guarantee a complete conversation history when grouping by these identifiers. The presence of parent and link fields indicates relationships, but no completeness promise is attached to these associations. You should design your analysis tools to handle potential gaps in the lineage of a comment or post within the archive.
When present, parent_id and link_id are relationship metadata for local grouping, not supported server filters. Their presence does not guarantee that referenced items are available, or that every comment includes either field. Inspect identifier formats and preserve unresolved references. The API does not supply assembled threads, completeness checks or server-side conversation analytics. HTTP 400 means an invalid request, 401 missing or invalid authentication, 402 insufficient credits, and 429 a rate limit. Invalid requests do not debit credits; upstream failures refund reserved credits. A successful retrieval, even empty, costs one credit. A lost client response can follow billable server success, and a successful repeat costs another credit. Use /v1/status only for static service-scope information and evidence that the HTTP application responds. It does not query the search backend or establish record availability, latency or capacity. Treat payment verification and account balance as separate account-panel operations; the retrieval API has no conversation-level billing or payment-tracking endpoint.
