Skip to navigation

Lists and paging

A list operation is a GET that returns many resources at once, such as all your VMs. Paging splits a long list into pages: you ask for a page of a given size, then ask for the next one until there are no more. IBEE’s lists don’t all work the same way yet, so this page shows, for each list, what it returns and how to page through it.

Choose how to read a list

StyleParametersHow you know there’s moreUsed by
Offsetlimit (page size) and offset (records to skip)The page came back fullCloud VMs, GPU VMs, firewall groups, snapshots, backup runs
Skiplimit and skip (records to skip)The page came back fullLoad balancers, firewall group attachments
Page numberpage (starts at 1) and limit or page_sizetotal is larger than what you have readSecret stores, secrets, Container Registry lists
Continuation tokenlimit and continuation_tokenis_truncated is true; send next_continuation_token backBuckets
No pagingnoneEverything comes back in one answerMost networking, Block Storage, CDN and catalog lists

How it works

  1. You call the list with workspace_id (required on every list, as on every call) and, if the list pages, a page size.
  2. The answer is either a bare JSON array ([...]) or an object whose collection key is named after the resource (items, snapshots, runs, stores, …), often with a total or count.
  3. If the list pages and there may be more, you ask again with the next offset, page number or token.
  4. A list without paging parameters has no page controls: the service returns what it holds.

A common envelope for every list is planned for a later major version and will be announced in the changelog.

Before you begin

  • An API token with the product’s read permission, for example Virtual Machines → Read (vm.read). See Authentication.
  • IBEE_TOKEN and IBEE_WORKSPACE_ID set in your terminal, as in Make your first call.
  • jq for the example below.

Read every page of a list

This example prints every cloud VM in the workspace, 100 at a time. Cloud VMs return 10 per page unless you set limit (at most 100), newest first. Use the largest page the list allows: reading 1,000 VMs takes 10 requests at 100 per page, but 100 requests at the default of 10.

1

Ask for the first page

curl "https://api.ibee.ai/v1/compute/cloud-vms?workspace_id=$IBEE_WORKSPACE_ID&limit=100&offset=0" \
-H "Authorization: Bearer $IBEE_TOKEN"

The answer is a JSON array of VMs. Each VM’s ID is in id.

2

Loop until a page comes back short

A page with fewer than 100 VMs is the last one:

offset=0
while true; do
page=$(curl -sS "https://api.ibee.ai/v1/compute/cloud-vms?workspace_id=$IBEE_WORKSPACE_ID&limit=100&offset=$offset" \
-H "Authorization: Bearer $IBEE_TOKEN")
echo "$page" | jq -r '.[] | "\(.id) \(.name) \(.status)"'
count=$(echo "$page" | jq 'length')
[ "$count" -lt 100 ] && break
offset=$((offset + count))
done
3

Check the result

You see one line per VM: its ID, name and status. If the first page is empty ([]), the workspace has no cloud VMs.

For buckets, send continuation_token instead: repeat the call with the previous answer’s next_continuation_token until is_truncated is false.

Every list, with its page sizes

limit and page_size show the default first, then the maximum. “none” means the list has no paging parameters. The VM backup run lists return only finished, successful runs; read a run by ID to see any other state.

OperationPathResponse shapePaging (default / maximum)Other filters
listSecretStoresGET /secret-store/storesobject: stores, total, page, limitpage; limit 50 / 200include_archived
listSecretsGET /secret-store/stores/{store_id}/secretsobject: secrets, total, page, limitpage; limit 50 / 200q
listSecretVersionsGET /secret-store/secrets/{secret_id}/versionsobject: secret_id, secret_name, current_version, oldest_version, versionsnone
listSecretIdentitiesGET /secret-store/stores/{store_id}/identitiesobject: identities, totalnone
listSecretIdentityScopesGET /secret-store/identities/{identity_id}/scopesobject: scopes, totalnone
listBucketsGET /object-storage/bucketsobject: buckets, is_truncated, next_continuation_tokenlimit 100 / 1,000; continuation_token
listS3CredentialsGET /object-storage/credentialsobject: credentialsnone
listNetworkingSitesGET /networking/sitesJSON arraynone
listVpcsGET /networking/vpcsJSON arraynonesite_id
listVpcSubnetsGET /networking/vpcs/{vpc_id}/subnetsJSON arraynone
listVpcNodesGET /networking/vpcs/{vpc_id}/nodesJSON arraynone
listNatGatewaysGET /networking/vpcs/{vpc_id}/nat-gatewaysJSON arraynone
listNatPortForwardingRulesGET /networking/vpcs/{vpc_id}/nat-gateways/{nat_gateway_id}/port-forwarding-rulesJSON arraynone
listReservedIpsGET /networking/reserved-ipsJSON arraynonesite_id
listFirewallGroupsGET /networking/firewall-groupsJSON arraylimit 10 / 100; offset
listFirewallGroupAttachmentsGET /networking/firewall-groups/{firewall_group_id}/attachmentsJSON arraylimit 50 / 200; skip
listLoadBalancersGET /networking/load-balancersJSON arraylimit 100 / 500; skipstatus, layer, protocol
listComputeSitesGET /compute/sitesobject: sites, countnone
listComputePlansGET /compute/plansobject: plans, count, vm_type, site_id, currency, billing_intervalnonevm_type, site_id, currency, billing_interval, include_availability, os_type, requires_public_ip
listComputeImagesGET /compute/imagesobject: images, count, vm_type, site_idnonevm_type, site_id
listSnapshotStoragePlansGET /compute/plans/snapshot-storageobject: items, source, product_code, plan_id, plan_version, billing_interval, currency, site_filter_codesnonesite_id, currency, billing_interval
listBackupStoragePlansGET /compute/plans/backup-storageobject: items, source, product_code, plan_id, plan_version, billing_interval, currency, site_filter_codesnonesite_id, currency, billing_interval
listCloudVmsGET /compute/cloud-vmsJSON arraylimit 10 / 100; offsetsearch, sort_by, sort_direction, status, date
listCloudVmEventsGET /compute/cloud-vms/{vm_id}/eventsJSON arraylimit 100 / 500
listCloudVmSnapshotsGET /compute/cloud-vms/{vm_id}/snapshotsobject: snapshots, totallimit 50 / 200; offsetsearch
listAllCloudVmSnapshotsGET /compute/cloud-vm-snapshotsobject: snapshots, totallimit 100 / 500; offsetsearch
listCloudVmBackupRunsGET /compute/cloud-vms/{vm_id}/backups/runsobject: runs, totallimit 50 / 200; offsetsearch
listAllCloudVmBackupRunsGET /compute/cloud-vm-backups/runsobject: runs, totallimit 50 / 200; offsetvm_id, status, search
listGpuVmsGET /compute/gpu-vmsJSON arraylimit 10 / 100; offsetsearch, sort_by, sort_direction
listGpuVmEventsGET /compute/gpu-vms/{vm_id}/eventsJSON arraylimit 100 / 500
listGpuVmSnapshotsGET /compute/gpu-vms/{vm_id}/snapshotsobject: snapshots, totallimit 50 / 200; offsetsearch
listAllGpuVmSnapshotsGET /compute/gpu-vm-snapshotsobject: snapshots, totallimit 100 / 500; offsetsearch
listGpuVmBackupRunsGET /compute/gpu-vms/{vm_id}/backups/runsobject: runs, totallimit 50 / 200; offsetsearch
listAllGpuVmBackupRunsGET /compute/gpu-vm-backups/runsobject: runs, totallimit 50 / 200; offsetvm_id, status, search
listBlockStoragePlansGET /block-storage/plansobject: items, currency, billing_intervalnonesite_id, currency, billing_interval
listBlockVolumesGET /block-storage/volumesJSON arraynone
listBlockVolumeOperationsGET /block-storage/volumes/{volume_id}/operationsJSON arraynone
listCdnDistributionsGET /cdn/distributionsobject: distributions, countnone
listCdnCustomDomainsGET /cdn/distributions/{distribution_id}/custom-domainsobject: distribution_id, default_domain, custom_domainsnone
listContainerRegistriesGET /container-registry/registriesobject: items, total, page, page_sizepage; page_size 20 / 100
listContainerRegistryAccessTokensGET /container-registry/registries/{registry_id}/access-tokensJSON arraynoneinclude_revoked
listContainerRegistryRepositoriesGET /container-registry/registries/{registry_id}/repositoriesobject: items, total, page, page_sizepage; page_size 20 / 100search, sort
listContainerRegistryArtifactsGET /container-registry/registries/{registry_id}/artifactsobject: items, total, page, page_sizepage; page_size 20 / 100repository_name
listContainerRegistryVulnerabilitiesGET /container-registry/registries/{registry_id}/security/vulnerabilitiesobject: items, total, page, page_sizepage; page_size 20 / 100severity, cve_id, repository_name, digest, tag, package
listContainerRegistrySbomsGET /container-registry/registries/{registry_id}/security/sbomsobject: items, page_summary, total, page, page_sizepage; page_size 20 / 100repository_name

Paging in the SDKs and CLI

The SDKs and the CLI return the one page the API sends; they don’t read further pages for you. Pass the list’s paging parameters from the table above and repeat the call to read the next page. In the CLI these are options, such as --limit and --offset.

Troubleshooting

You seeWhat it meansWhat to do
Only 10 cloud VMs, GPU VMs or firewall groupsThose lists return 10 by defaultPass limit (up to 100) and page with offset.
The same records on every pageoffset (or skip, or page) isn’t changingAdd the number of records you received to offset each time.
A list is empty, but the portal shows resourcesThe workspace_id is another workspaceUse the ID of the workspace you see in the portal.
400 workspace_id_requiredThe URL has no workspace_id, or the shell cut the URL at &Quote the whole URL.
400 or 422 with detailThe product service refused a query parameter; detail names itUse a value inside the range in the table.