Pagination

The ION Guard API uses cursor-based pagination to navigate resource lists. This method is more efficient than offset-based pagination for large and constantly changing datasets.

How it works

Instead of numbered pages (1, 2, 3...), the API returns a cursor — an opaque token that points to a position in the dataset. You use the cursor to request the next or previous page of results.

Request parameters

Parameter	Default	Description
limit	20	Number of items per page (maximum: 100)
cursor	—	Pagination token (obtained from the previous response)

limit values above 100 are automatically reduced to the ceiling of 100.

Filters by resource

Some listing endpoints accept additional filters that combine with pagination. For example, GET /api/v1/alerts (and GET /api/v1/sites/{site}/alerts) accept:

Filter	Description
type	Filters by alert type
severity	Filters by severity
status	Filters by alert status

Filters are applied before pagination and automatically preserved in the links.next / links.prev URLs.

Example request

GET /api/v1/alerts?limit=10
Authorization: Bearer {token}

Response format

The response is wrapped in three blocks: data (the resources), links (navigation URLs), and meta (pagination metadata).

{
  "data": [
    { "id": "9c1a...", "type": "panic", "status": "active", ... },
    { "id": "9c1b...", "type": "device-offline", "status": "acknowledged", ... }
  ],
  "links": {
    "first": null,
    "last": null,
    "prev": null,
    "next": "/api/v1/alerts?cursor=eyJpZCI6MTAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0&limit=10"
  },
  "meta": {
    "path": "/api/v1/alerts",
    "per_page": 10,
    "next_cursor": "eyJpZCI6MTAsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null
  }
}

Field	Description
data	Array of resources for the current page
links.next	Full URL for the next page (null if there are no more items)
links.prev	Full URL for the previous page (null if this is the first)
links.first / links.last	Always null in cursor-based pagination (there is no fixed first/last)
meta.path	Base path used to generate the URLs
meta.per_page	Items per page requested
meta.next_cursor	Cursor for the next page (null if there are no more items)
meta.prev_cursor	Cursor for the previous page (null if this is the first)

Navigating between pages

# First page
curl -s "https://ionguard.local/api/v1/alerts?limit=10" \
  -H "Authorization: Bearer $TOKEN"

# Next page (using meta.next_cursor from the previous response)
curl -s "https://ionguard.local/api/v1/alerts?limit=10&cursor=eyJpZCI6MTAuLi4" \
  -H "Authorization: Bearer $TOKEN"

End of list

When meta.next_cursor is null and links.next is null, there are no more items available.

Advantages of cursor-based pagination

• Performance — No need to count all records (O(1) vs O(n))
• Consistency — Insertions and deletions during navigation do not cause duplicate or skipped items
• Scalability — Works well with millions of records