Rutas y autenticación
Envía solicitudes GET con la clave de redditlistening.com en Authorization: Bearer o X-API-Key. /v1/search busca texto en title y text. /v1/posts restringe el tipo a post y /v1/comments a comment; ninguna de estas listas requiere id. /v1/item exige id y solo admite ese parámetro para consultar un elemento concreto. No añadas a esa ruta los filtros generales de búsqueda.
Las búsquedas de contenido aceptan q, subreddit, author, kind, from, to, min_score, limit y page. kind admite post o comment. Usa from y to con formato YYYY-MM-DD: filtran created_utc, la fecha de creación del contenido, en UTC. to incluye el día final completo. No delimitan la fecha en que tú recuperas el texto ni su incorporación al archivo. min_score establece un mínimo, sin ordenar ni clasificar el sentimiento.
/v1/subreddits admite prefix y limit para buscar nombres de comunidades, no page ni los filtros de contenido. Sus recuentos no constituyen un inventario global exacto. /v1/status es público y no se cobra: ofrece una declaración estática y confirma la respuesta HTTP, sin comprobar el buscador, la presencia de menciones, la clave o el saldo.
Páginas, registros y totales
En las búsquedas de contenido, limit y page van de 1 a 100. Las respuestas siguen el orden interno _doc, no una secuencia cronológica ni una clasificación por relevancia o puntuación. Recorrer todas las páginas permitidas no garantiza recuperar todos los resultados coincidentes. Dividir la investigación por fechas puede organizar el trabajo, pero no prueba una cobertura completa ni elimina automáticamente duplicados.
Interpreta el total con su relación: eq indica exactitud, gte una cota inferior y unknown que no hay un total fiable, que puede ser null. Un total desconocido no equivale a cero. Registra los parámetros junto a las respuestas para explicar cómo se obtuvo el conjunto leído. Ese total no mide la población de compradores ni el número completo de conversaciones existentes.
Los registros son planos. Si contienen parent_id o link_id, puedes relacionarlos localmente, sin garantía de disponer de sus padres o de toda la conversación. Estos campos no son filtros de consulta. Guarda por separado tus etiquetas de investigación: una categoría de reparación o una valoración del tono no es un campo analítico que el servidor haya calculado.
Errores y coste de la recuperación
HTTP 400 indica una solicitud inválida, 401 una clave ausente o incorrecta, 402 saldo insuficiente y 429 un límite de frecuencia. Comprueba parámetros, dominio de la clave y saldo según el caso antes de repetir. Las solicitudes rechazadas no consumen créditos y los fallos del origen devuelven la reserva. No interpretes un fallo local de clasificación como un fallo del servicio.
Una recuperación satisfactoria consume un crédito, aunque esté vacía. Si tu cliente pierde la respuesta después de un éxito del servidor, puede haberse cobrado ese éxito; un reintento satisfactorio cuesta otro crédito. Releer o reclasificar una respuesta guardada localmente no ejecuta otra consulta. Distingue esas operaciones en el presupuesto y en el registro metodológico de tu estudio.
