Pagination

List endpoints return a single page of results at a time. Use page plus a page-size parameter to navigate the full set.

Query parameters

Parameter	Type	Applies to
page	integer	All paginated endpoints. Starts at 1. Returns null in the response when omitted.
pageSize	integer	Core resource endpoints (/core/virtual-machines, /core/volumes, /core/environments, etc.).
per_page	integer	Billing and Pricebook endpoints, and /core/images.
page_size	integer	Object Storage endpoints (/object-storage/*).

The page-size parameter name varies by endpoint group. Check the individual endpoint's parameter list for which name it accepts. Most callers use 25 or 50; larger values reduce request count but increase per-request latency.

Response shapes

The API uses three pagination envelope shapes. Code that reads count and the data array should branch on which surface it targets.

Shape 1: virtual machines, volumes, clusters, snapshots, marketplace deployments, and most other Core lists. Pagination metadata precedes the data array.

GET /core/virtual-machines

{
  "status": true,
  "message": "Getting VMs successful",
  "page": 1,
  "page_size": 50,
  "count": 25,
  "instances": [ /* … */ ]
}

Shape 2: environments, keypairs, firewalls, and a handful of other Core endpoints. Same fields as Shape 1; metadata follows the data array. Read fields by name, not position.

GET /core/environments

{
  "status": true,
  "message": "Getting environments successful",
  "environments": [ /* … */ ],
  "page": null,
  "page_size": null,
  "count": 11
}

Shape 3: all /object-storage/* endpoints. No {status, message} envelope. Metadata lives in a meta object with different field names (current_page, total_pages).

GET /object-storage/access-keys

{
  "access_keys": [ /* … */ ],
  "meta": {
    "count": 5,
    "current_page": 1,
    "total_pages": 1
  }
}

Iterate every page

Request page 1, process results, increment page, repeat until the response array is shorter than the page size (or empty). For Shape 3, stop when meta.current_page >= meta.total_pages.

Python

import requests

base = "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines"
headers = {"api_key": "YOUR_API_KEY"}

page = 1
page_size = 50
while True:
    response = requests.get(
        base,
        headers=headers,
        params={"page": page, "pageSize": page_size},
    )
    response.raise_for_status()
    body = response.json()
    items = body.get("instances", [])
    if not items:
        break
    for item in items:
        process(item)
    if len(items) < page_size:
        break
    page += 1

cURL

curl "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines?page=1&pageSize=50" \
  -H "api_key: YOUR_API_KEY"

Stable pagination across writes

A list endpoint paginates over the live state at the time of each request. Inserting or deleting resources between page requests can cause an item to appear twice or be skipped. For workflows that need a stable view, fetch all pages first, then process the merged result.