Rutas y reglas para recuperar registros históricos

Consulta las rutas GET, los filtros admitidos, la paginación y los errores HTTP. Separa la recuperación de registros de su transformación local.

Obtener clave API

Rutas principales y filtros admitidos

Las rutas de recuperación usan GET. Envía tu clave de redditextract.com mediante Authorization: Bearer seguido del secreto, o mediante X-API-Key. /v1/search busca registros; /v1/posts restringe el tipo a post y /v1/comments a comment. Estas dos últimas rutas no requieren id. /v1/item exige id para solicitar un elemento concreto y no acepta el conjunto de filtros de búsqueda.

En las búsquedas de contenido están disponibles q, subreddit, author, kind, from, to, min_score, limit y page. kind admite post o comment. Usa from y to en formato YYYY-MM-DD; los límites se aplican a created_utc en UTC y to incluye el día final completo. min_score establece un umbral, no una ordenación. No hay filtros de búsqueda parent_id o link_id.

/v1/subreddits permite consultar nombres mediante prefix y limitar la respuesta con limit. No es una búsqueda de publicaciones por varias comunidades, no admite page ni los filtros de fechas de contenido y sus recuentos no constituyen un inventario exacto global. /v1/status es público y no consume créditos: devuelve una declaración estática y permite comprobar que responde el servidor HTTP, sin probar la búsqueda ni la disponibilidad de un registro.

Paginación y estructura de respuesta

Las consultas de contenido permiten limit de 1 a 100 y page de 1 a 100. La respuesta sigue el orden interno _doc del archivo, que no es cronológico ni corresponde a relevancia o puntuación. Ese intervalo de páginas limita la recuperación: recorrerlo no garantiza que hayas obtenido todos los registros coincidentes. Una fecha más estrecha tampoco demuestra cobertura completa del periodo seleccionado.

Interpreta el total junto con su relación: eq indica un total exacto, gte una cota inferior y unknown la ausencia de un total fiable, que puede ser null. No conviertas unknown en cero. Anota estos datos con los parámetros de la consulta para explicar el alcance de cada extracción, sin presentar el total recibido como el tamaño de todo Reddit o de una comunidad completa.

Los registros son planos. Examina los campos disponibles y valida sus tipos antes de proyectarlos a tu esquema. Un título puede no estar presente en un comentario; tampoco debes deducir una identidad a partir de un campo vacío. Si conservas parent_id o link_id, trátalos como referencias disponibles para tu procesamiento local, no como prueba de una jerarquía completa incluida por el servidor.

Errores y contabilidad de solicitudes

HTTP 400 indica una solicitud inválida; revisa nombres, valores y formatos de los parámetros. HTTP 401 corresponde a una clave ausente o inválida, HTTP 402 a saldo insuficiente y HTTP 429 a un límite de frecuencia. No repitas indefinidamente la misma solicitud sin resolver la causa. Comprueba que la clave pertenezca al dominio antes de plantear una regeneración.

Una recuperación satisfactoria consume un crédito, incluido un resultado vacío. Las solicitudes rechazadas no consumen créditos y un fallo del origen devuelve la reserva. Si tu cliente pierde la respuesta después de un éxito del servidor, ese éxito puede haberse cobrado: un reintento satisfactorio cuesta otro crédito. Un error en tu conversión local tampoco convierte una respuesta satisfactoria de la API en un fallo reembolsable.

Rutas de la API

Método	Ruta	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`