Rotas e autenticação
Use GET e envie a chave de redditlistening.com em Authorization: Bearer ou X-API-Key. /v1/search busca texto nos campos title e text. /v1/posts restringe o tipo a post e /v1/comments a comment; essas listas não exigem id. /v1/item exige id e aceita somente esse parâmetro para um item específico, sem os demais filtros de conteúdo.
As buscas de conteúdo aceitam q, subreddit, author, kind, from, to, min_score, limit e page. kind pode ser post ou comment. from e to usam YYYY-MM-DD em UTC e filtram created_utc, o momento de criação do conteúdo. to inclui todo o dia final. Não são filtros da hora de recuperação ou de entrada no arquivo. min_score indica um limiar de pontuação, não ordenação nem sentimento.
/v1/subreddits recebe prefix e limit para encontrar nomes de comunidades. Não aceita page nem os filtros de datas de conteúdo; os seus números não são um inventário global exato. /v1/status é público e não cobrado. Retorna uma declaração estática e confirma a resposta HTTP, sem testar busca, disponibilidade dos registros, chave ou saldo.
Paginação e estrutura dos registros
Nas buscas de conteúdo, limit e page vão de 1 a 100. O arquivo usa ordem _doc, não uma sequência por tempo, relevância ou pontuação. Percorrer todas as páginas permitidas não comprova coleta completa. Dividir por datas pode organizar lotes, mas não demonstra que todos os registros correspondentes estejam presentes ou tenham sido recuperados.
A relação do total precisa acompanhar a interpretação: eq significa exato, gte um limite inferior e unknown ausência de um total confiável, que pode ser null. Desconhecido não é zero. Guarde os parâmetros para que outro pesquisador entenda a seleção, sem tratar o total de uma consulta como o número de consumidores ou de todas as conversas sobre a categoria.
A API retorna registros planos, sem árvore de conversa montada. Se parent_id e link_id estiverem presentes, o agrupamento local é possível, mas não garante a presença de pais ou de todas as respostas. Esses campos não são filtros de consulta. Etiquetas de reparo ou conforto pertencem ao seu estudo e devem ficar separadas dos campos recebidos.
Erros e custo das chamadas
HTTP 400 indica solicitação inválida, 401 chave ausente ou inválida, 402 saldo insuficiente e 429 limite de frequência. Corrija a causa antes de repetir. Solicitações rejeitadas não consomem créditos; falhas do serviço de origem devolvem a reserva. /v1/status não verifica se sua interpretação está correta, e um erro no código de análise local não equivale a uma falha da recuperação.
Cada recuperação bem-sucedida, mesmo vazia, custa um crédito. Se o cliente perder a resposta após um sucesso do servidor, esse sucesso pode ter sido cobrado. Uma repetição bem-sucedida custa outro crédito. Relê-la ou aplicar novas etiquetas a uma resposta já salva não chama novamente a API. Mantenha registros separados de chamadas e etapas locais para explicar custos e resultados.
