Paginación: offset, limit y order
offset, limit, order y search: los cuatro parámetros que paginan casi todos los listados de la API de Arko, y las dos excepciones que invierten el orden por defecto.
Casi todos los listados de la API de Arko —agentes, powers, chats, mensajes, memorias, keys— se paginan con el mismo puñado de parámetros de consulta. Aprenderlos una vez te ahorra tener que redescubrirlos en cada endpoint nuevo que integres.
Los cuatro parámetros base
- offset: desde qué posición empezar a devolver resultados; por defecto 0.
- limit: cuántos resultados devolver por página; por defecto 100, que también es el máximo.
- order: DESC por defecto —lo más reciente primero—; pásalo como asc para invertirlo.
- search: un filtro parcial, insensible a mayúsculas, de hasta 200 caracteres.
La forma de la respuesta paginada
Un listado nunca devuelve un arreglo suelto: la data trae rows con los resultados de esa página, count con el total que existe para el filtro aplicado, más el offset y el limit que usaste. Con esos cuatro campos puedes construir cualquier paginación —numérica, infinita, con «cargar más»— sin pedir información adicional.
Las dos excepciones a DESC por defecto
Los mensajes de un chat y el historial del asistente Builder invierten el orden por defecto: llegan en ASC, del más antiguo al más reciente, porque ahí lo que importa es la cronología de la conversación, no la actividad reciente. Si tu código asume DESC en todos lados, estos dos endpoints van a sorprenderte la primera vez.
Una paginación consistente en el noventa por ciento de los endpoints es más peligrosa que una inconsistente en todos: las dos excepciones son las que te muerden cuando dejaste de prestar atención.
Un patrón simple para recorrer un listado completo
Si necesitas todos los resultados y no solo una página, incrementa offset en pasos de limit y detente cuando el número de rows devueltas sea menor que el limit que pediste —o cuando offset alcance count—. No asumas un número fijo de páginas: count puede cambiar entre una llamada y la siguiente si hay escritura concurrente.
Lleva esto a producción con Arko
Crea tu agente, conéctale tus APIs con Powers y publícalo en tu producto desde un solo panel. Empieza gratis hoy mismo.
Crear cuenta gratis
