Pagination

List operations return results one page at a time. The Elastio API is served by several backend services, and they paginate in one of three main styles. The style is part of each operation’s contract, so check the parameters of the operation you call in the API reference.

Style	Request parameters	Where the next page comes from	Example
Token	`page_size`, `next_page_token`, `prev_page_token`	`pagination.next_page_token`	`GET /gateway/api/v2/assets`
CamelCase token	`pageSize`, `pageToken`	`pagination.next_page_token` (with `total_count`)	`GET /gateway/integration/v2/alerts`
Offset	`limit`, `offset`	Add `limit` to `offset` until you reach `total`	`GET /gateway/api/v2/incidents`

Token pagination

Most /gateway/api/v2 list operations, the /gateway/api/v1/search/… operations and the database monitoring lists use token pagination:

page_size sets how many items to return.
The response contains pagination.next_page_token (and prev_page_token) when there are more pages.
Pass the value back as the next_page_token query parameter to get the next page, or prev_page_token to go back.
When next_page_token is missing or null, you have reached the last page.

GET

/gateway/api/v2/assetsGet list of v2 assets (live inventory)

Try it

{
  "total": 1840,
  "data": [ { "asset_id": "0b6f3c1e-8a52-4c2e-9d1f-5e7a2b9c4d10", "asset_name": "web-prod-01", "…": "…" } ],
  "pagination": { "next_page_token": "eyJvZmZzZXQiOjEwMH0", "prev_page_token": "…" }
}

This loop collects every AWS asset:

#!/usr/bin/env bash
# Requires jq. Writes one asset per line to assets.jsonl.
BASE="https://acme.app.elastio.com"
token=""
: > assets.jsonl

while :; do
  args=(--data-urlencode "platform=aws" --data-urlencode "page_size=100")
  [ -n "$token" ] && args+=(--data-urlencode "next_page_token=$token")

  page=$(curl -sfG "$BASE/gateway/api/v2/assets" -H "Authorization: Bearer $ELASTIO_TOKEN" "${args[@]}") || exit 1
  echo "$page" | jq -c '.data[]' >> assets.jsonl

  token=$(echo "$page" | jq -r '.pagination.next_page_token // empty')
  [ -z "$token" ] && break
done

wc -l < assets.jsonl

import os, requests

BASE = "https://acme.app.elastio.com"
HEADERS = {"Authorization": f"Bearer {os.environ['ELASTIO_TOKEN']}"}

def list_assets(**filters):
    params = {**filters, "page_size": 100}
    while True:
        resp = requests.get(f"{BASE}/gateway/api/v2/assets", headers=HEADERS, params=params, timeout=30)
        resp.raise_for_status()
        page = resp.json()
        yield from page.get("data", [])
        token = (page.get("pagination") or {}).get("next_page_token")
        if not token:
            return
        params["next_page_token"] = token

assets = list(list_assets(platform="aws"))
print(len(assets))

$Base = "https://acme.app.elastio.com"
$Headers = @{ Authorization = "Bearer $env:ELASTIO_TOKEN" }

$assets = [System.Collections.Generic.List[object]]::new()
$token = $null

do {
    $uri = "$Base/gateway/api/v2/assets?platform=aws&page_size=100"
    if ($token) { $uri += "&next_page_token=" + [uri]::EscapeDataString($token) }

    $page = Invoke-RestMethod -Uri $uri -Headers $Headers
    $assets.AddRange([object[]]@($page.data))
    $token = $page.pagination.next_page_token
} while ($token)

$assets.Count

Variations

Some operations name the request parameter page_token instead of next_page_token, for example GET /gateway/api/v1/search/assets, GET /gateway/api/v1/pursuit/reports and GET /gateway/api/v1/assets/{asset_id}/custom-hunts.
In operations that use the /gateway/api/v1 envelope, the pagination object is nested under data. GET /gateway/api/v1/search/assets returns data.assets and data.pagination.next_page_token, and caps page_size at 100.

CamelCase token pagination

The integration service (alerts, webhooks, Slack and Splunk invocations) and several /gateway/api/v1 operations (jobs, recovery points, hunt results, files with findings, data classification) use camelCase parameters:

pageSize sets the page size. For GET /gateway/integration/v2/alerts the default is 50 and the maximum 100.
Pass pagination.next_page_token from the response back as pageToken.
pagination.total_count gives the total number of matching items.

GET

/gateway/integration/v2/alertsList all alerts for a tenant (v2)

Try it

{
  "alerts": [ { "id": "a3c9e1f2-6b4d-4e8a-9c17-2d5f0b8e7a61", "name": "Ransomware on production", "status": "enabled", "…": "…" } ],
  "pagination": { "next_page_token": "…", "prev_page_token": null, "total_count": 27 }
}

The loop is the same as for token pagination, with different names: send pageToken, read pagination.next_page_token. In /gateway/api/v1 operations such as GET /gateway/api/v1/jobs, the pagination object is under data.pagination, and the items under a named field such as data.jobsList.

Offset pagination

Incidents, personal access tokens, audit logs, Cloud Configuration and policy membership lists use offsets:

limit sets the page size, and offset the number of items to skip.
The response includes a total count, so you know when to stop.

Limits differ per operation. GET /gateway/api/v2/incidents defaults to 20 and accepts at most 20; GET /rbac/api/v1/audit-logs defaults to 50 and accepts up to 1000.

GET

/gateway/api/v2/incidentsList retained incident episodes

Try it

{
  "total": 57,
  "data": [ { "id": "7d2e9f40-1c3b-4a8e-b5d6-2f9a0c1e3b47", "handle": "INC-000012", "status": "open", "…": "…" } ]
}

This loop collects every open incident:

#!/usr/bin/env bash
# Requires jq. Writes one incident per line to incidents.jsonl.
BASE="https://acme.app.elastio.com"
limit=20
offset=0
: > incidents.jsonl

while :; do
  page=$(curl -sf "$BASE/gateway/api/v2/incidents?status=open&limit=$limit&offset=$offset" \
    -H "Authorization: Bearer $ELASTIO_TOKEN") || exit 1
  echo "$page" | jq -c '.data[]' >> incidents.jsonl

  total=$(echo "$page" | jq '.total')
  count=$(echo "$page" | jq '.data | length')
  offset=$((offset + limit))
  [ "$count" -eq 0 ] || [ "$offset" -ge "$total" ] && break
done

wc -l < incidents.jsonl

import os, requests

BASE = "https://acme.app.elastio.com"
HEADERS = {"Authorization": f"Bearer {os.environ['ELASTIO_TOKEN']}"}

def list_incidents(limit=20, **filters):
    offset = 0
    while True:
        params = {**filters, "limit": limit, "offset": offset}
        resp = requests.get(f"{BASE}/gateway/api/v2/incidents", headers=HEADERS, params=params, timeout=30)
        resp.raise_for_status()
        page = resp.json()
        items = page.get("data", [])
        yield from items
        offset += limit
        if not items or offset >= page["total"]:
            return

incidents = list(list_incidents(status="open"))
print(len(incidents))

$Base = "https://acme.app.elastio.com"
$Headers = @{ Authorization = "Bearer $env:ELASTIO_TOKEN" }

$incidents = [System.Collections.Generic.List[object]]::new()
$limit = 20
$offset = 0

do {
    $page = Invoke-RestMethod -Uri "$Base/gateway/api/v2/incidents?status=open&limit=$limit&offset=$offset" -Headers $Headers
    $items = @($page.data)
    $incidents.AddRange([object[]]$items)
    $offset += $limit
} while ($items.Count -gt 0 -and $offset -lt $page.total)

$incidents.Count

Variations

The personal access token lists return items in tokens_details with a total.
GET /rbac/api/v1/audit-logs takes limit and offset, but reports its count in pagination.total_count.

Page numbers

A few reporting operations page by number instead. GET /gateway/reporting/v1/reports takes a 1-based page (default 1) and pageSize (default 20). Values of pageSize above 100 are accepted but capped to 100, and the response’s pageSize field shows the effective value.

Tips

Use the largest page size you need, within the operation’s maximum, to reduce the number of requests.
Treat tokens as opaque. Don’t decode, build or store them for later; request a fresh first page instead.
Expect data to change between pages. Items created or deleted while you page can shift offset-based results. For a consistent snapshot, page quickly and de-duplicate by ID.
Stop on an empty page as well as on a missing token or reached total, so a loop can never run forever.