Skip to main content

Paginación cursor

Las rutas /v1/... que devuelven listas usan paginación cursor-based, no page + offset. Es estable ante inserts concurrentes y eficiente sobre tablas grandes.

Shape de respuesta

Query params

Filtros adicionales (ej. status, event_type) son específicos de cada endpoint.

Ejemplo de paginar

Repetir hasta que has_more sea false y next_cursor sea null.

Patrón de cliente

Por qué cursor y no page+offset

  • Estabilidad: si insertas un evento nuevo entre la página 2 y la 3, el cursor sigue apuntando al “después del último que viste”. Un ?page=3&offset=50 se desplaza y muestra duplicados o saltos.
  • Performance: con cursor el server hace WHERE created_at < <cursor> (usa índice). Con offset hace OFFSET 1000 (escanea y descarta).
  • Predictibilidad: next_cursor es siempre seguro de seguir; no hay que adivinar si pediste demasiado.

Errores

  • ?cursor=basura400 invalid_cursor. Reiniciar paginación desde la primera página.
  • ?limit=0 o negativo → 400 validation_error.
  • ?limit=99999 → se trunca silenciosamente al máximo del endpoint.

Cuándo NO usar cursor

  • Para mostrar “página 5 de 47” en una UI clásica → no es posible con cursor (no hay total). Si lo necesitas, considera un endpoint específico de count, o pasa a un modelo page+offset con un trade-off documentado.
  • Para ranking/top-N → ordena en server, devuelve N items, sin paginar.