Pagination
How to walk Constaia API lists with cursor pagination (limit and starting_after) and filters by status, type and metadata, with code examples.
Endpoints that return lists use cursor pagination. The main one is GET /v1/analyses, which
can return thousands of analyses.
Shape of a list
{
"object": "list",
"data": [
{ "id": "an_01J9ZC4E7D2K8M1N3P5Q7R9S2T", "object": "analysis", "status": "completed", "...": "..." },
{ "id": "an_01J9ZB1F6C9H4J2K5L8M0N3P6Q", "object": "analysis", "status": "completed", "...": "..." }
],
"has_more": true,
"url": "/v1/analyses"
}| Field | Description |
|---|---|
object | Always "list". |
data | The items on this page, newest first. |
has_more | true if there are more items after the last one in data. |
url | Path of the listed resource. |
Parameters
| Parameter | Description |
|---|---|
limit | Items per page, from 1 to 100. Default 10. |
starting_after | Cursor: the id of the last item of the previous page. Returns the items older than that one. |
status | Filter by queued, processing, completed or failed. |
type | Filter by detected document type, e.g. es_dni. |
metadata[key] | Filter by an exact metadata value. You can combine several keys; all must match. |
To walk everything: request the first page and, while has_more is true, request the next one passing the id of
the last item in data as starting_after.
No next_cursor and no ending_before
The response has no next_cursor field: the cursor is always the id of the last item. There is no ending_before
to go backwards either; if you need to return to a previous page, keep the cursors you already used.
Also:
- The list only includes analyses of the key's mode: a
ck_test_key sees test analyses and ack_live_key sees live ones. - Deleted analyses and those created with
keep_results: falsedo not appear. - Filters are applied before paginating, so
has_morerefers to the filtered results.
Examples
#!/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')
doneWalking many pages in a row counts towards the requests-per-second limit: use
limit=100 to make fewer requests. The SDKs retry 429s automatically.
Other lists
| Endpoint | Pagination |
|---|---|
GET /v1/document-types | Returns the whole catalogue in one page (has_more: false at the current size) and includes total. Accepts limit (up to 500, default 100) and starting_after (a type id), plus its own filters. See catalogue. |
GET /v1/webhook-endpoints | Always every endpoint in a single response, with has_more: false. |
The JavaScript and Python SDKs return these last two directly as an array (or list).
Next steps
Idempotency
Use the Idempotency-Key header to retry analyses, classifications and batches without processing or paying for them twice, with examples in several languages.
Storage and privacy
What Constaia keeps from your documents and for how long, with the none, temporary and persistent modes, keep_results, deletion, encryption and profiles.