Skip to main content

List Virtual Machines

GET https://infrahub-api.nexgencloud.com/v1/core/virtual-machines​

Retrieves a list of your current virtual machines, offering comprehensive details for each, such as hardware configuration, ID, operating system, operational status, firewall rules, and more.


Query string parameters​

search string or integer  optional​

Search for the name or ID of the virtual machine to retrieve it.

environment string or integer  optional​

Filter resources by name or ID of the environment.

page integer  optional​

The page number to retrieve virtual machines from.

pageSize integer  optional​

Specify the number of virtual machines to return per page.


Attributes​

status boolean​

Indicates the result of the request to retrieve a list of VMs. true signifies success, while false indicates an error.

message string​

A description of the status of the request.

page integer or null​

The page number for the virtual machines listed.

page_size integer or null​

The number of VMs listed per page retrieved.

count integer or null​

The total number of virtual machine instances returned in the response.

instances array of objects​

An array of instances objects, each containing details about a VM.

For descriptions of the fields within the instances object returned in response to your request, please refer to the documentation here.


Example request
curl -X GET "https://infrahub-api.nexgencloud.com/v1/core/virtual-machines" \
 -H "accept: application/json"\
 -H "api_key: YOUR API KEY"
Response
{
    "status": true,
    "message": "Getting VMs successful",
    "page": null,
    "page_size": null,
    "count": 1,
    "instances": [
      {
      "id": 288813,
      "name": "example-vm",
      "status": "ACTIVE",
      "environment": {
        "id": 29872,
        "name": "example-env",
        "org_id": 3971,
        "region": "CANADA-1",
        "features": {
          "network_optimised": true,
          "green_status": "GREEN"
        }
      },
      "image": {
        "name": "Ubuntu Server 22.04 LTS R535 CUDA 12.2 with Docker"
      },
      "flavor": {
        "id": 111,
        "name": "n3-RTX-A6000x1",
        "cpu": 28,
        "ram": 58.0,
        "disk": 100,
        "ephemeral": 0,
        "gpu": "RTX-A6000",
        "gpu_count": 1,
        "labels": [],
        "features": {
          "network_optimised": false,
          "no_hibernation": false,
          "no_snapshot": false,
          "local_storage_only": false
        }
      },
      "os": "Ubuntu Server 22.04 LTS R535 CUDA 12.2 with Docker",
      "keypair": {
        "name": "example-key"
      },
      "volume_attachments": [
        {
          "volume": {
            "id": 20019,
            "name": "example-volume",
            "description": "",
            "volume_type": "Cloud-SSD",
            "size": 100,
            "bootable": false
          },
          "status": "ATTACHED",
          "device": "/dev/vdb",
          "created_at": "2025-07-03T13:59:12"
        }
      ],
      "power_state": "RUNNING",
      "vm_state": "active",
      "fixed_ip": "10.0.9.152",
      "floating_ip": null,
      "floating_ip_status": "NO FLOATING IP",
      "security_rules": [
        {
          "id": 984202,
          "direction": "ingress",
          "protocol": "tcp",
          "port_range_min": 22,
          "port_range_max": 22,
          "ethertype": "IPv4",
          "remote_ip_prefix": "0.0.0.0/0",
          "status": "SUCCESS",
          "created_at": "2025-07-03T13:09:59"
        }
      ],
      "callback_url": null,
      "locked": false,
      "contract_id": null,
      "labels": [],
      "created_at": "2025-07-03T13:08:49",
      "features": {
        "network_optimised": false,
        "green_status": "GREEN"
      },
      "is_snapshotting": false,
      "cluster_id": null,
      "port_randomization": true,
      "port_randomization_status": "NO_FLOATING_IP",
      "requires_public_ip": false
    }
  ]
}

Returns​

Returns a list of your virtual machines as instances objects, each containing details about the VM.



Back to top​