Routes, query text and authentication
The API base is https://api.subredditdata.com. /v1/search reads archived posts and comments; /v1/posts and /v1/comments restrict the record kind. None of these list routes requires id. /v1/item requires id for an individual record. /v1/subreddits supports prefix and limit for community-name discovery, not a full community profile or a guaranteed census. /v1/status is public and uncharged.
Protected retrieval accepts X-API-Key with the raw key or Authorization: Bearer with the same key. Use the credential for subredditdata.com; another domain in the network has its own key and balance. The account page uses a separate Secure HttpOnly session cookie. Keep the real key out of public worksheets, client-side examples and shared diagnostic logs.
Content query parameters are q, subreddit, author, kind, from, to, min_score, limit and page. kind may be post or comment and is optional on search. q searches title and text with AND semantics for multiple analyzed terms within a matching field. It does not require each word in both fields, offer exact-phrase matching by default or accept an arbitrary query language. Topic synonyms and alternative spellings are not a completeness guarantee.
Parameters are route-specific: item accepts id, while subreddits accepts prefix and limit. Unknown parameters are errors. There are no parent_id, link_id, sentiment, membership-growth or demographic query filters. Keep the same route and record-kind choice across comparable worksheet rows; otherwise a difference in the available texts may simply reflect different selection rules.
Time windows and incomplete context
from and to take exact dates in YYYY-MM-DD format and filter created_utc in UTC. from begins at midnight; to includes the entire day through 23:59:59. For example, from=2026-04-01 and to=2026-04-30 define April UTC calendar dates. If to is today, it still includes the whole current UTC day, not only time before the request. This is a date-boundary rule, not a promise of available or future records.
API responses contain flat records rather than server-assembled thread trees, which changes how you structure your analysis. When parent_id and link_id fields are present, clients may group them locally to reconstruct conversations. However, no complete conversation or ancestry is guaranteed by the server. Client-side grouping is optional and does not imply that the returned fields are complete or exhaustive for every item in the archive.
limit and page range from 1 to 100. Results use archive _doc order, not time, relevance or score ranking. min_score filters on the numeric score without changing that order or identifying reliable testimony. Visiting the maximum number of pages does not retrieve a proven complete archive. Sorting a saved subset locally does not change the subset into a timeline of all community activity.
Interpret total counts with their relation: eq is exact for that response, gte is a lower bound and unknown means no reliable total, which may be null. None establishes archive coverage or a representative sample. Community-name aggregation counts are not guaranteed globally exact. Use the actual records you retained as the basis for any local topic tally, with overlap and exclusions recorded separately.
Separate transport, billing and research outcomes
HTTP 400 means an invalid request, 401 a missing or invalid key, 402 insufficient credits and 429 a request-rate limit. Correct the cause before retrying. An error is not a finding that no one discussed transit. /v1/status only supplies a static historical-service disclosure and shows that the HTTP server responds; it does not check the search source or archive availability.
Every successful retrieval costs one credit, including empty responses. Invalid requests do not debit a credit and upstream failures refund reservations. A client timeout or lost response is different: the server may have completed a successful, billed request. A successful retry is billed separately. Record the attempt as uncertain rather than promising that network retries are free; local analysis failures after a successful response also do not reverse its charge.
