Paginación
Cómo se piden las páginas de una lista, qué devuelve cada una y qué rutas paginan.
Todas las listas de la API paginan igual: pides una página por número y recibes sus filas junto con el total. Esta página explica los parámetros, la respuesta, cómo recorrer una lista entera y cuáles son las rutas paginadas.
Parámetros
| Parámetro | Tipo | Default | Rango |
|---|---|---|---|
page | entero | 1 | desde 1 (la primera página es la 1) |
pageSize | entero | 50 | de 1 a 200 |
Un valor fuera de rango (pageSize=500, page=0) contesta 400 INVALID con details; no se recorta en silencio. Los dos se combinan con los filtros propios de cada ruta:
curl "https://app.reclee.com/api/v1/job-posts?status=ACTIVE&page=2&pageSize=20" \
-H "Authorization: Bearer $RECLEE_API_KEY"Respuesta
{
"rows": [ { "id": "3f8a2b6c-1d4e-4a7b-9c2d-8e5f6a7b8c9d", "title": "Senior Backend Engineer" } ],
"total": 27,
"page": 2,
"pageSize": 20
}| Campo | Qué es |
|---|---|
rows | Las filas de esta página. Su forma depende de la ruta. |
total | Cuántas filas cumplen los filtros en total, no solo en esta página. |
page | La página que pediste. |
pageSize | El tamaño de página que se aplicó. |
Una página más allá del final no es un error: devuelve rows vacío con el total real. El orden de cada lista es estable (las vacantes, por ejemplo, de la más nueva a la más vieja), así que recorrer página por página no repite ni saltea filas mientras nadie escriba en el medio.
Recorrer una lista entera
Pide páginas hasta que hayas leído total filas, o hasta recibir una página vacía:
page=1
while : ; do
body=$(curl -s "https://app.reclee.com/api/v1/crm/leads?page=$page&pageSize=200" \
-H "Authorization: Bearer $RECLEE_API_KEY")
count=$(echo "$body" | jq '.rows | length')
echo "$body" | jq -c '.rows[]'
[ "$count" -lt 200 ] && break
page=$((page + 1))
doneCada página es un pedido y cuenta contra el límite de 60 por minuto: para listas grandes usa pageSize=200 y filtra en el servidor todo lo que puedas.
Rutas paginadas
Estas rutas GET devuelven una página. Todas usan pageSize hasta 200 con 50 por defecto, salvo los movimientos de créditos, que admiten hasta 100 por página y devuelven 20 por defecto.
| Área | Rutas |
|---|---|
| Cuenta | /account/api-keys · /account/members |
| Créditos | /billing/credit-movements (máx. 100, default 20) |
| Vacantes | /job-posts · /job-posts/contexts · /job-posts/figures · /job-posts/refs · /job-posts/refs/open |
| Una vacante | /job-posts/{jobPostId}/applications · /match-scores · /members · /notes · /rescorable · /score-states · /shares · /subscriptions |
| ATS | /ats/interview-types · /ats/labels |
| Una postulación | /ats/applications/{applicationId}/comments · /interviews · /labels · /report/versions |
| Perfiles | /profiles/{profileId}/bookmarks · /events · /milestones · /notes · /tags |
| Talent pool | /talent/pool · /talent/pool/{profileId}/own · /talent/pool/identity-reviews |
| Listas y tags | /talent/bookmarks · /talent/bookmarks/{bookmarkId} · /talent/tags · /talent/tags/vocabulary |
| Búsqueda de talento | /talent/searches |
| Sourcing | /sourcing/longlists · /sourcing/longlists/delivered · /sourcing/longlists/{longlistId}/entries · /sourcing/longlists/{longlistId}/searches · /sourcing/runs/{longlistId}/pages · /sourcing/scores · /sourcing/talent-icps |
| Definiciones de búsqueda | /sourcing/search-definitions · /sourcing/search-definitions/performance · /sourcing/search-definitions/{definitionId}/searches · /sourcing/searches/{searchId}/profiles |
| CRM | /crm/leads · /crm/leads/{leadId}/activity · /crm/leads/{leadId}/contacts · /crm/contacts/{contactId}/history · /crm/requests · /crm/requests/{requestId}/placements |
En la especificación OpenAPI, estas rutas declaran page y pageSize y responden con el esquema Page.
Rutas con su propia paginación
Unas pocas listas no usan page/pageSize porque su forma de recorrerse es otra:
| Ruta | Cómo se pide | Qué devuelve |
|---|---|---|
GET /notifications | ?limit= hasta 200 (más los filtros unreadOnly, type, jobPostId). No hay páginas siguientes: el feed cubre los últimos 30 días. | Un array de notificaciones. El header X-Has-More: true avisa que el limit cortó la lista. |
GET /copilot/threads | ?cursor= con el nextCursor de la página anterior; sin cursor, la primera. | { threads, nextCursor }. nextCursor es null cuando no hay más. Son tus conversaciones con el asistente. |
GET /careers/job-posts | ?slug= del sitio de empleo, ?offset= desde 0 y ?limit= hasta 100. | { jobPosts, total, limit, offset }. |
GET /billing/credit-movements | page y pageSize como el resto, pero pageSize hasta 100 y 20 por defecto. | Una página { rows, total, page, pageSize }. |
Listas que no paginan
Algunas lecturas devuelven todo de una vez porque son chicas o porque no son una lista que crece: un recurso individual, un catálogo fijo (como los paquetes de créditos), un conjunto que se lee y se escribe entero (como los criterios de una vacante), una lista de ids que pediste o un archivo. Esas rutas no paginan; la referencia REST dice la forma de cada una.
Las tools de lectura del MCP tienen sus propios parámetros de paginación (limit y page), descritos en cada tool.