Architecture and Data Model Constraints
Building an ingestion pipeline starts with recognizing an independent historical archive, not a live or official Reddit interface. Keep an original response sample, a query manifest, and the version of your transformation rules. These local artifacts help you explain a warehouse row later. They do not guarantee that the archive preserves a record or returns the same data on another run.
The API returns flat records rather than pre-assembled thread trees, meaning you must group parent and link relationships locally if those fields are present in the payload. The server does not provide complete ancestry guarantees, and there are no exposed query filters for parent_id or link_id to fetch all comments for a specific post directly. Clients must retrieve supported filtered flat records and group them conditionally when the fields exist, recognizing that a complete conversation history is never guaranteed by the service design.
Inspect returned fields such as id, kind, subreddit, created_utc, score, title and text before choosing local column types. This is a list of fields to inspect, not a promise that every record contains every field. Distinguish missing values, nulls and failed conversions. Send unexpected shapes to a local review area instead of silently turning them into accepted warehouse rows.
Endpoint Routing and Query Semantics
Authenticated GET requests use https://api.redditdataapi.com with either X-API-Key: <key> or Authorization: Bearer <key>. Use /v1/search for supported searches, /v1/posts for posts, and /v1/comments for comments. Only /v1/item requires id for direct lookup of a known record. The id parameter is not a posts or comments filter; those routes do not provide a server-built discussion tree.
Search filters are q, subreddit, author, kind, from, to, min_score, limit and page. kind accepts post or comment. Dates use YYYY-MM-DD in UTC, with to including the stated day. min_score filters a numeric score and never sorts results. The internal _doc order is neither chronological nor relevance order. No arbitrary query DSL or server-side custom analytics is exposed.
Set limit from 1 to 100 and page from 1 to 100; each request fetches one page. The /v1/subreddits route accepts prefix and limit, without guaranteeing globally exact aggregation counts. Read totals with relation: eq is exact, gte a lower bound, unknown unreliable and potentially null. Exhausting the permitted pages does not prove complete coverage. Group returned parent_id or link_id fields locally only when present; neither field is a supported query filter.
Error Handling, Pricing, and Reliability
Handle HTTP 400 for an invalid request, 401 for a missing or invalid key, 402 for insufficient credit, and 429 for a rate limit. Correct invalid parameters before retrying, check credentials for 401, and pause or fund the job for 402. Apply a bounded wait for rate limits. Inspect the response status before treating the body as a successful batch of records.
Each successful retrieval consumes one credit, including an empty response. Invalid requests do not debit credits and upstream failures refund reservations. A client may lose its connection after a successful server retrieval; if a repeated request succeeds, it costs another credit. Keep an attempt log separate from your local validation results, because rejecting a record in your loader does not reverse a successful API charge.
The public /v1/status route is uncharged and provides static service-scope information plus evidence that the HTTP app responds. It does not probe search or record availability. Keys and balances belong to redditdataapi.com. Keep your key in server configuration. Account sessions use a separate cookie; signing into the account panel does not replace a retrieval authentication header.
