Routes and credentials for a bounded reading task
The API host is https://api.redditlistening.com. /v1/search searches archived posts and comments; /v1/posts and /v1/comments constrain the record kind. These routes do not require id. /v1/item requires id for one archived object, which may be unavailable. /v1/subreddits accepts prefix and limit for community discovery, not arbitrary content filters or a guaranteed complete inventory. /v1/status is public and uncharged.
Protected reads accept either X-API-Key with the raw account key or Authorization: Bearer with the same key. Neither is Reddit OAuth. Use the redditlistening.com credential from your server; another network site has a different key and balance. The Secure HttpOnly cookie used to sign in to the account panel is separate from retrieval authentication. Do not put a real key in a shared research notebook.
The backpack example uses q=backpack, subreddit=BuyItForLife and limit=3. Supported content parameters are q, subreddit, author, kind, from, to, min_score, limit and page. kind is post or comment; limit and page range from 1 to 100. There are no location, language, sentiment, brand-score, parent_id or link_id filters, and the API does not accept an arbitrary query language. q searches the archived title and text fields.
Dates, record context and selection effects
Pass dates exactly as YYYY-MM-DD to filter created_utc. from begins that date in UTC, and to includes the whole specified UTC day through 23:59:59. For example, from=2026-04-01 and to=2026-04-30 cover those UTC calendar dates, not a local timezone interval. If to is today’s UTC date, it still denotes the whole day rather than the moment you submit the query. Only available archive records can be returned; this does not promise later or missing material.
API responses return flat records rather than server-assembled thread trees. This means that if parent_id and link_id fields are present, you may group them locally in your client application. However, the server does not guarantee complete conversation ancestry or a full thread view. There are no exposed query filters for link_id or parent_id, so you must fetch the data and assemble context yourself based on the flat structure provided by the endpoint.
Results use _doc archive order, not time, relevance or descending score. min_score is a threshold filter, not a judgement of research value or emotional tone. Excluding low-score records changes the observed set and can remove useful complaints or questions. Pagination is bounded by 100 pages; splitting queries by date or phrase organizes your work but cannot prove exhaustive coverage or remove overlaps.
Totals must be interpreted with their relation: eq means exact, gte a lower bound and unknown no reliable total, which can be null. These describe the response’s counting information, not market size or archive completeness. A local table of coded records needs its own stated denominator and exclusion rules. Do not add overlapping query totals together and label the result the number of customers or all mentions.
Errors and the difference between reading and interpreting
HTTP 400 means an invalid request, 401 a missing or invalid key, 402 insufficient credit, and 429 a rate limit. Correct the cause or reduce request frequency instead of retrying indefinitely. A successful empty response is different from a request failure. Likewise, an analyst being unable to classify a statement does not turn a successful API response into an error.
Each successful retrieval costs one credit, including an empty page. Invalid requests do not debit a retrieval, while upstream failures refund reservations. A successful response remains billed if your local coding or export fails afterward. Reopening the saved response for review is local work. /v1/status returns a static service-scope disclosure and an HTTP response, not search health, archive availability or an alerting service. A request that succeeded on the server can remain charged even if its response never reaches your client. Each successful retry costs another credit, including an empty result.
