Recuperação de registros: contrato da API

Consulte autenticação, rotas GET, parâmetros aceitos, limites e códigos HTTP. Entenda registros planos e totais antes de montar seu extrator.

Obter chave API

Rotas e autenticação

Use GET nas rotas de leitura, com a chave deste domínio em Authorization: Bearer ou X-API-Key. /v1/search consulta conteúdo histórico. /v1/posts restringe o tipo a post e /v1/comments a comment, sem exigir id. /v1/item exige id para buscar um item específico; não aplique nessa rota os filtros de uma consulta de conteúdo.

Os parâmetros das buscas de conteúdo são q, subreddit, author, kind, from, to, min_score, limit e page. kind aceita post ou comment. Informe from e to como YYYY-MM-DD: o filtro usa created_utc em UTC, incluindo todo o dia final de to. min_score estabelece um limiar de pontuação e não ordena resultados. Não há filtros de consulta por parent_id ou link_id.

/v1/subreddits aceita prefix e limit para consultar nomes de comunidades. Não aceita page nem filtros de datas de conteúdo, e seus números não devem ser tratados como um inventário global exato. /v1/status é público e não cobra créditos. Ele apresenta uma declaração estática e confirma que o servidor HTTP responde, sem testar o mecanismo de busca ou a presença de um registro.

Limites e interpretação do lote

Nas buscas de conteúdo, limit varia de 1 a 100 registros e page de 1 a 100. Os resultados seguem a ordem interna _doc, não uma ordem cronológica, de relevância ou de pontuação. Percorrer as páginas permitidas não garante ingestão exaustiva. Reduzir um intervalo de datas pode delimitar seu trabalho, mas não comprova que todos os registros daquele período estejam disponíveis.

Os totais devem ser lidos junto com sua relação: eq indica um valor exato; gte, um limite inferior; unknown, ausência de total confiável, que pode ser null. Não converta um total desconhecido em zero. Guarde esses indicadores com os parâmetros para que quem usar o lote saiba distinguir quantidade observada e estimativa de alcance.

As respostas apresentam registros planos. Verifique presença e tipo antes de selecionar campos para seu modelo. parent_id e link_id, quando existirem, permitem relacionamentos locais, sem garantir que os registros referenciados também estejam no lote. Um esquema de destino pode separar campos obrigatórios e opcionais, mas essa classificação será da sua aplicação, não uma garantia adicional da API.

Falhas, créditos e novas tentativas

HTTP 400 indica parâmetros inválidos; revise os nomes e formatos enviados. HTTP 401 sinaliza chave ausente ou inválida, HTTP 402 indica saldo insuficiente e HTTP 429 corresponde ao limite de frequência. Resolva a causa antes de insistir na mesma requisição. Uma chave válida em outro domínio não substitui a chave de redditextract.com.

Uma recuperação bem-sucedida custa um crédito, mesmo vazia. Requisições rejeitadas não consomem créditos e falhas do serviço de origem devolvem a reserva. Se o cliente perder a resposta depois do sucesso no servidor, esse sucesso pode ter sido cobrado. Uma repetição bem-sucedida custa outro crédito. Falhas na sua validação de tipos ou na gravação local não alteram o resultado já obtido da API.

Rotas da API

Método	Rota	Parâmetros
`GET`	`/v1/search`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/posts`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/comments`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/item`	`id`
`GET`	`/v1/subreddits`	`prefix, limit`
`GET`	`/v1/status`	`—`

Parâmetros de consulta

Parâmetro	Valor / tipo / intervalo
`q`	`text`
`subreddit`	`keyword`
`author`	`keyword`
`kind`	`post \| comment`
`from`	`ISO date`
`to`	`ISO date`
`min_score`	`integer`
`limit`	`1–100`
`page`	`1–100`
`id`	`item ID`
`prefix`	`subreddit prefix`