Choose a route and keep authentication on the server
The base host is https://api.redditextract.com. /v1/search searches historical posts and comments; /v1/posts and /v1/comments constrain the record kind. Those routes do not require id. /v1/item takes id for one archived record, which may be absent. /v1/subreddits supports community discovery using prefix and limit; it is not a content search or a complete community inventory. The public /v1/status route is a separate, uncharged status response.
Use either X-API-Key with the raw domain key or Authorization: Bearer followed by that key for protected retrievals. Neither format is Reddit OAuth. The key issued for redditextract.com and its balance are specific to this site. A browser login session serves the account panel, not API retrieval. Keep secrets out of frontend bundles, request examples, committed fixtures and transformation logs.
The PostgreSQL inspection request uses /v1/search?q=index&subreddit=PostgreSQL&limit=3. q is text search, not a way to submit arbitrary query syntax. Supported content filters are q, subreddit, author, kind, from, to, min_score, limit and page. from and to accept YYYY-MM-DD dates in UTC and filter created_utc; the entire to day is included; limit and page range from 1 to 100. Do not add fields, parent_id or link_id as query filters: those controls are not exposed.
Inspect the object and define your own destination types
Flat records are the API input to your mapper, not a promise of a universal destination schema. Check property presence separately from null and verify the runtime type before conversion. If your table needs record_id or body_text, document which available source property supplies it and what you do when that property is absent. Those names are your local aliases, not new API fields or server-side projection options.
Keep identifier values without numeric coercion. Validate a score before storing it as a number; do not treat missing values as zero. For a time field, establish its representation and units before converting it to your application format. Preserve the source value beside a derived value when that helps diagnose a conversion. Do not assume every object contains a title, text, author, timestamp or score merely because those concepts are useful to your application.
Retrieval uses archive _doc order, which is neither chronological, relevance, nor score order. Pagination supports up to 100 records per request and 100 pages per query. Bounded page iteration does not guarantee full coverage, complete ingestion, or that all matching records are returned. Always treat retrieved data as a bounded sample.
Totals must be read with their reported relation: eq denotes an exact count, gte a lower bound, and unknown the absence of a reliable total, which can be null. None of these descriptions establishes full archive coverage. min_score remains a threshold filter, never a score-sort control. Use observed pages as bounded input and maintain your own record of successful retrievals and local validation failures.
Handle request failures independently of transformation failures
HTTP 400 identifies an invalid request, 401 a missing or invalid key, 402 insufficient credit, and 429 a rate limit. Correct invalid parameters or credentials rather than repeating the same request unchanged. A local parsing exception is not an HTTP failure: keep the response and diagnose your mapper first. Public /v1/status only reports a static historical-archive disclosure and that the HTTP server responds; it does not check search health or record availability.
One successful retrieval costs one credit even if the returned list is empty. Requests rejected before retrieval do not purchase records; an upstream failure refunds the reserved credit. A successful response followed by a failure in your application is still a successful billed retrieval. Reprocessing the saved response locally avoids another API call, whereas requesting it again can incur another credit. Use the account panel on the key page to inspect your domain balance.
