Paginación
Cómo recorrer listas de la API de Constaia con paginación por cursor (limit y starting_after) y filtros por estado, tipo y metadata, con ejemplos.
Los endpoints que devuelven listas usan paginación por cursor. El principal es
GET /v1/analyses, que puede devolver miles de análisis.
Forma de una lista
{
"object": "list",
"data": [
{ "id": "an_01J9ZC4E7D2K8M1N3P5Q7R9S2T", "object": "analysis", "status": "completed", "...": "..." },
{ "id": "an_01J9ZB1F6C9H4J2K5L8M0N3P6Q", "object": "analysis", "status": "completed", "...": "..." }
],
"has_more": true,
"url": "/v1/analyses"
}| Campo | Descripción |
|---|---|
object | Siempre "list". |
data | Los elementos de esta página, del más reciente al más antiguo. |
has_more | true si hay más elementos después del último de data. |
url | Ruta del recurso listado. |
Parámetros
| Parámetro | Descripción |
|---|---|
limit | Elementos por página, de 1 a 100. Por defecto, 10. |
starting_after | Cursor: el id del último elemento de la página anterior. Devuelve los elementos más antiguos que ese. |
status | Filtra por queued, processing, completed o failed. |
type | Filtra por tipo de documento detectado, por ejemplo es_dni. |
metadata[clave] | Filtra por un valor exacto de metadata. Puedes combinar varias claves; deben cumplirse todas. |
Para recorrer todo: pide la primera página, y mientras has_more sea true, pide la siguiente pasando como
starting_after el id del último elemento de data.
Sin next_cursor ni ending_before
La respuesta no incluye un campo next_cursor: el cursor es siempre el id del último elemento. Tampoco hay
ending_before para ir hacia atrás; si necesitas volver a una página anterior, guarda los cursores que ya usaste.
Además:
- La lista solo incluye análisis del modo de la clave: una clave
ck_test_ve los de test y unack_live_los reales. - No aparecen los análisis borrados ni los creados con
keep_results: false. - Los filtros se aplican antes de paginar, así que
has_morese refiere a los resultados filtrados.
Ejemplos
#!/usr/bin/env bash
set -euo pipefail
cursor=""
while :; do
url="https://api.constaia.com/v1/analyses?limit=100&status=completed&metadata%5Bevent%5D=42"
[ -n "$cursor" ] && url="$url&starting_after=$cursor"
page=$(curl -sS "$url" -H "Authorization: Bearer $CONSTAIA_API_KEY")
echo "$page" | jq -r '.data[] | [.id, .document.type, .verdict.status] | @tsv'
[ "$(echo "$page" | jq -r '.has_more')" = "true" ] || break
cursor=$(echo "$page" | jq -r '.data[-1].id')
doneRecorrer muchas páginas seguidas cuenta para el límite de peticiones por segundo:
usa limit=100 para hacer menos peticiones. Los SDK reintentan los 429 automáticamente.
Otras listas
| Endpoint | Paginación |
|---|---|
GET /v1/analyses | Por cursor, como se describe arriba. |
GET /v1/document-types | Devuelve el catálogo completo en una página (has_more: false con el tamaño actual) e incluye total. Admite limit (hasta 500, 100 por defecto) y starting_after (id de tipo), además de filtros propios. Ver catálogo. |
GET /v1/webhook-endpoints | Siempre todos los endpoints en una sola respuesta, con has_more: false. |
Los SDK de JavaScript y Python devuelven estas dos últimas directamente como array (o lista).
Siguientes pasos
Idempotencia
Usa la cabecera Idempotency-Key para reintentar análisis, clasificaciones y lotes sin procesarlos ni cobrarlos dos veces, con ejemplos en varios lenguajes.
Almacenamiento y privacidad
Qué guarda Constaia de tus documentos y cuánto tiempo, con los modos none, temporary y persistent, keep_results, borrado, cifrado y perfiles de proceso.