Authentication and Payment Structure
To integrate the Reddit archive search into your automation workflows, you must first obtain a tenant-specific API key via email and password signup. Unlike network-wide credentials, this key is unique to your account and does not work on other domains in the network. After signing up, the key is displayed once immediately at signup, before payment. Save it in a secure secret store; the account widget does not persist it in localStorage or deliver it by email. Retrieval accepts either Authorization: Bearer or X-API-Key.
You are charged one credit per successful retrieval request, including empty results, upstream failures refund the reservation, and invalid requests do not debit credits. The minimum top-up is fifty dollars, with a base pricing of one dollar per thousand requests. Paid credits never expire, and there are no subscriptions. You must pay using the exact amount and receiving address displayed on the server-created invoice, whether using USDT TRC20 or USDC ERC20 Ethereum mainnet, rather than an address copied from an earlier invoice.
Verification involves pasting the transaction hash after payment. The invoice expires one hour after creation, but the transfer block timestamp eligibility extends seventy-two hours beyond the invoice expiry. This window determines eligible timestamps but is not a deadline for clicking verify. Only a confirmed genuine transfer adds credits. Provider outages can leave verification pending; neither this transfer window nor submitting a hash guarantees a settlement time.
Query Semantics and Data Structure
The API returns flat records, not server-assembled thread trees, meaning clients may group returned parent and link fields locally when present. There are no exposed link_id or parent_id query filters, and archive document order is neither chronological nor relevance-sorted. The /v1/posts and /v1/comments endpoints do not require an id parameter; the id parameter is exclusively for /v1/item. Posts and comments do not require an id for retrieval, ensuring flexible querying for your automation scripts.
Pagination allows up to one hundred records per request and one hundred pages per query. Bounded page iteration does not guarantee full coverage, complete ingestion, or exhaustive export, so never promise a complete archive by iterating pages. Totals carry a relation: eq means exact, gte means a lower bound, and unknown means no reliable total. An eq total is exact for that query; a gte total is only a lower bound, and an unknown total may be null. None of these values proves complete archive coverage.
Filtering options include q, subreddit, author, kind, from and to dates in YYYY-MM-DD format (UTC, with to inclusive), min_score, limit, and page. Note that min_score is strictly a filter, never a sorting control. The kind parameter accepts post or comment values. Subreddits support prefix matching, and item requires an id. The q parameter searches title and text, joining multiple terms with AND within a matching field. Keep that behavior in mind when defining a historical query.
Error Handling and System Limits
Handle HTTP protocol codes as literal ASCII numerals in your automation: 400 for invalid requests, 401 for missing or invalid keys, 402 for insufficient credit, and 429 for rate limits. Upstream failures refund the reserved credit; invalid requests are not charged. The /v1/status endpoint is public and uncharged, returning a static independent historical archive disclosure indicating the HTTP server responds, without checking search backend health or record availability.
The /v1/status endpoint does not provide green operational dashboard guarantees or monitoring data. It simply confirms the server is up. Your automation should not rely on this for data completeness checks. The archive is an independent historical repository, not live or official Reddit, so do not expect real-time updates or current event coverage. Focus on historical data retrieval rather than assuming live status for your automation workflows.
If a response is lost at the client after the server succeeds, your account may already have spent one credit. A successful retry spends another credit; limit retries and deduplicate saved results locally. Do not infer a refund from a timeout alone. Keys and balances belong to this domain. Payment verification does not promise recovery of wrong-token or wrong-network transfers or manual crediting.
