Paginación | Arbol AI Docs

Las operaciones de lista responden una página a la vez, en un orden estable. Cada página lleva cursores opacos que conducen a las páginas que la rodean.

Pedir una página

Parámetro	Por defecto	Significado
`limit`	`25`	La cantidad máxima de elementos en una página, de 1 a 100. Para leer más se necesita otra página.
`cursor`	Ninguno	Un cursor del `pageInfo` de la respuesta anterior. Omítelo para la primera página.
`direction`	`forward`	En qué sentido recorrer el orden desde `cursor`: `forward` o `backward`.

La mayoría de las listas son operaciones GET y los reciben como parámetros de query. Las búsquedas que se envían con POST los reciben en el cuerpo JSON, como agenda.appointments.search y raiz.knowledge.search.

Unas pocas operaciones fijan sus propios límites para limit. agenda.appointments.list admite hasta 500, y raiz.knowledge.search usa 8 por defecto con un máximo de 20. La referencia de la operación indica sus límites.

Leer la página

El data de una lista es una página:

Campo	Significado
`object`	Siempre `"list"`.
`data`	Los elementos de esta página.
`pageInfo.hasNextPage`	Si existe una página posterior en el orden actual.
`pageInfo.hasPreviousPage`	Si existe una página anterior en el orden actual.
`pageInfo.nextCursor`	El cursor de la página siguiente, o `null` si no hay.
`pageInfo.previousCursor`	El cursor de la página anterior, o `null` si no hay.

Por ejemplo, la primera página de account.apiKeys.list, de una sola key. La llamada necesita el permiso (scope) account:api-keys:read:

curl "https://api.getarbol.com/v1/account/api-keys?limit=1" \
  --header "Authorization: Bearer $ARBOL_API_KEY"

{
  "success": true,
  "data": {
    "object": "list",
    "data": [
      {
        "id": "exampleClientId0001",
        "name": "Billing backend",
        "scopes": ["account:billing:read"],
        "createdAt": "2026-10-01T15:00:00.000Z",
        "createdBy": null,
        "restrictions": null
      }
    ],
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "nextCursor": "EXAMPLE_CURSOR_2",
      "previousCursor": null
    }
  },
  "error": null,
  "metadata": { "requestId": "00000000-0000-4000-8000-000000000003" }
}

Leer todas las páginas

Llama sin cursor y luego vuelve a llamar con cursor igual a pageInfo.nextCursor mientras pageInfo.hasNextPage sea true. Mantén iguales todos los demás parámetros.

cursor=""
while :; do
  params=(--data-urlencode "limit=100")
  if [ -n "$cursor" ]; then params+=(--data-urlencode "cursor=$cursor"); fi
  page=$(curl -sS --get https://api.getarbol.com/v1/account/api-keys "${params[@]}" \
    --header "Authorization: Bearer $ARBOL_API_KEY")
  jq -e '.success' <<<"$page" >/dev/null || { echo "$page" >&2; break; }
  jq -c '.data.data[]' <<<"$page"
  [ "$(jq -r '.data.pageInfo.hasNextPage' <<<"$page")" = "true" ] || break
  cursor=$(jq -r '.data.pageInfo.nextCursor' <<<"$page")
done

import { createClient } from "@arbol-ai/sdk";

const arbol = createClient({
  baseUrl: "https://api.getarbol.com",
  token: process.env.ARBOL_API_KEY!,
});

let cursor: string | undefined;
do {
  const { data: page } = await arbol.account.apiKeys.list({ limit: 100, cursor });
  for (const key of page.data) console.log(key.id, key.name);
  cursor = page.pageInfo.hasNextPage ? (page.pageInfo.nextCursor ?? undefined) : undefined;
} while (cursor);

Reglas de los cursores

Los cursores son opacos. Úsalos exactamente como los devolvió la API. No construyas, edites ni decodifiques ninguno.
Un cursor pertenece a su consulta. Envíalo con los mismos filtros que lo produjeron. Raíz rechaza un cursor de otra lista con 400 INVALID_CURSOR.
Algunas lecturas no paginan. Unas pocas reciben solo limit y no responden pageInfo, como agenda.firstAvailability.get. Su referencia lo indica.