Pagination

Les listes qui peuvent grandir sans borne sont paginées par curseur : la réponse porte un nextCursor opaque, que vous renvoyez pour obtenir la page suivante. Les lignes des Tables sont la seule exception et utilisent un offset, parce qu’une Table est un tableur trié par n’importe quelle colonne, à la demande.

Les listes par curseur

Une liste paginée prend deux paramètres de requête facultatifs et rend un champ de plus :

Où	Nom	Sens
requête	limit	La taille de page. Chaque route a un défaut et un maximum (le plus souvent 50 et 200 ; voir la référence). Un limit au-dessus du maximum est refusé en 400.
requête	cursor	Le nextCursor de la page précédente. Absent pour la première page.
réponse	nextCursor	Le curseur de la page suivante, ou null quand il n’y en a plus.

GET /api/v1/executions?workflowId=0192f1c2-aaaa-7000-8000-000000000001&limit=50

{
  "executions": [ { "id": "…", "status": "succeeded", "…": "…" } ],
  "nextCursor": "MjAyNi0xMC0wNFQwOToxMjo0NC4xMjNafDAxOTJmMWMy"
}

Puis :

GET /api/v1/executions?workflowId=0192f1c2-aaaa-7000-8000-000000000001&limit=50&cursor=MjAyNi0xMC0wNFQwOToxMjo0NC4xMjNafDAxOTJmMWMy

Les règles à suivre :

• Le curseur est opaque : ne le décodez pas, ne le fabriquez pas, ne le conservez pas au-delà du parcours en cours. Son format peut changer d’une version à l’autre.
• Gardez les mêmes filtres d’une page à la suivante. Un curseur encode une position dans un ordre donné ; changer status ou workflowId en route donne un résultat indéfini.
• Arrêtez-vous quand nextCursor vaut null. Une page vide avec un curseur null est une fin normale, pas une erreur.
• Les listes vont du plus récent au plus ancien sauf mention contraire (exécutions, incidents, messages, journal d’audit) ; les exécutions en attente sont triées par échéance.
• Un curseur est stable face aux insertions : une exécution créée pendant que vous paginez ne décale pas les pages suivantes.

Les routes paginées ainsi comprennent GET /api/v1/executions, GET /api/v1/executions/waiting, GET /api/v1/executions/incidents, GET /api/v1/messages, GET /api/v1/threads, GET /api/v1/contacts, GET /api/v1/approvals, GET /api/v1/review, GET /api/v1/notifications, GET /api/v1/journal, GET /api/v1/sending/journal, GET /api/v1/admin/audit et les cas de GET /api/v1/eval-runs/{id}.

Les listes non paginées

Les listes courtes et bornées sont rendues entières : les workflows (GET /api/v1/workflows), les boîtes, les tables, les connexions, les clés d’API, les versions d’un workflow, les membres de l’instance. Elles ne prennent pas de cursor et ne rendent pas de nextCursor.

Les lignes de Tables : offset et limit

GET /api/v1/tables/{id}/rows trie par n’importe quelle colonne (sort, dir), filtre (q, filter, match) et pagine par offset :

Nom	Défaut	Maximum	Sens
offset	0	100000	Le nombre de lignes à sauter
limit	100	500	La taille de page

La réponse porte les lignes et deux compteurs : total, le nombre de lignes que le filtre retient toutes pages confondues, et totalUnfiltered, la taille de la table. La page n de taille limit est offset = (n - 1) × limit ; la dernière page est atteinte quand offset + rows.length >= total.

GET /api/v1/tables/0192f1c2-dddd-7000-8000-000000000001/rows?sort=created_at&dir=desc&offset=200&limit=100

L’offset est plafonné : une requête au-delà de 100000 est refusée en 400, et une page située après la fin des lignes filtrées est tables.page_out_of_range. Les Tables sont des objets bornés (voir Tables) : c’est ce qui rend l’offset acceptable ici, et nulle part ailleurs.