List CVMs (paginated)

Returns paginated CVMs in current workspace with total count.

GET /api/v1/cvms/paginated

List CVMs (paginated)

cURL

curl --request GET \
  --url https://cloud-api.phala.com/api/v1/cvms/paginated \
  --header 'Authorization: Bearer <token>'

200

{
  "items": [
    {
      "hosted": {
        "id": "<string>",
        "name": "<string>",
        "status": "<string>",
        "uptime": "<string>",
        "app_id": "<string>",
        "app_url": "<string>",
        "instance_id": "<string>",
        "configuration": {
          "name": "<string>",
          "image": "<string>",
          "vcpu": 123,
          "memory": 123,
          "disk_size": 123,
          "compose_file": {
            "name": "<string>",
            "allowed_envs": [
              "<string>"
            ],
            "bash_script": "<string>",
            "default_gateway_domain": "<string>",
            "docker_compose_file": "<string>",
            "init_script": [
              "<string>"
            ],
            "key_provider": "none",
            "key_provider_id": "<string>",
            "kms_enabled": true,
            "local_key_provider_enabled": false,
            "manifest_version": 2,
            "no_instance_id": false,
            "port_policy": {
              "ports": [
                {
                  "port": 123,
                  "pp": false
                }
              ],
              "restrict_mode": false
            },
            "pre_launch_script": "<string>",
            "public_logs": true,
            "public_sysinfo": true,
            "public_tcbinfo": true,
            "runner": "docker-compose",
            "requirements": {},
            "storage_discard": true,
            "event_log_version": 1,
            "snapshotter": "overlayfs",
            "verity_volumes": [
              {
                "source": "<string>",
                "target": "<string>",
                "verity_root": "<string>"
              }
            ],
            "gateway_enabled": true,
            "features": [
              "kms",
              "tproxy-net"
            ],
            "salt": "<string>",
            "secure_time": false,
            "storage_fs": "zfs",
            "swap_size": "<string>",
            "tproxy_enabled": true
          },
          "os_image_version": "<string>",
          "compose_file_raw": "<string>",
          "ports": [
            {
              "protocol": "<string>",
              "host_port": 123,
              "vm_port": 123,
              "host_address": "<string>",
              "nic_index": 123
            }
          ],
          "encrypted_env": "<string>",
          "app_id": "<string>",
          "user_config": "<string>",
          "hugepages": false,
          "pin_numa": false,
          "gpus": {
            "gpus": [],
            "attach_mode": "listed"
          },
          "kms_urls": [],
          "gateway_urls": [],
          "stopped": false,
          "networks": [
            {
              "mode": "<string>",
              "bridge_name": "",
              "parent": "",
              "vhost": true,
              "queues": 123
            }
          ],
          "annotations": {}
        },
        "exited_at": "<string>",
        "boot_progress": "<string>",
        "boot_error": "<string>",
        "shutdown_progress": "<string>",
        "image_version": "<string>",
        "events": [
          {
            "event": "<string>",
            "body": "<string>",
            "timestamp": 0
          }
        ],
        "interfaces": [
          {
            "mode": "<string>",
            "backend": "<string>",
            "mac": "",
            "bridge_name": "<string>",
            "netdev_id": "<string>",
            "vhost": true,
            "queues": 123,
            "macvtap_mode": "<string>"
          }
        ],
        "running": false
      },
      "name": "<string>",
      "status": "<string>",
      "public_urls": [
        {
          "app": "<string>",
          "instance": "<string>"
        }
      ],
      "enabled_ssh_access": true,
      "managed_user": {
        "id": 123,
        "username": "<string>"
      },
      "node": {
        "id": 123,
        "name": "<string>",
        "region_identifier": "<string>"
      },
      "listed": false,
      "in_progress": false,
      "dapp_dashboard_url": "<string>",
      "syslog_endpoint": "<string>",
      "allow_upgrade": false,
      "project_id": "prj_0123abcd",
      "project_type": "<string>",
      "billing_period": "<string>",
      "kms_info": {
        "id": "kms_0123abcd",
        "url": "<string>",
        "version": "<string>",
        "slug": "<string>",
        "chain_id": 123,
        "kms_contract_address": "<string>",
        "gateway_app_id": "<string>",
        "ca_pubkey": "<string>",
        "k256_pubkey": "<string>"
      },
      "contract_address": "<string>",
      "deployer_address": "<string>",
      "vcpu": 123,
      "memory": 123,
      "disk_size": 123,
      "gateway_domain": "<string>"
    }
  ],
  "total": 123,
  "page": 123,
  "page_size": 123,
  "pages": 123
}

Authorizations

Authorization · string · header · required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

family · enum<string> · default: all

Filter by instance family

Available options: all, cpu, gpu

instance_types · string[] | null

Filter by one or more instance type IDs

search · string | null

Search name, app_id, vm_uuid, instance_id

status · string[] | null

CVM status filter

base_image · string | null

OS image name filter

kms_slug · string | null

KMS slug filter

kms_type · string | null

KMS type filter

node · string | null

Node name filter (matches teepod or node name)

region · string | null

Region identifier filter

page · integer · default: 1

Page number (1-indexed)

Required range: x >= 1

page_size · integer · default: 30

Items per page (max 100)

Required range: 1 <= x <= 100

Response

200

application/json

Paginated CVM list with total count

PaginatedHostedCvms

PaginatedCvmInfos

Paginated response for CVM list endpoints

items · HostedCvm · object[] · required

Show child attributes

total · integer · required

page · integer · required

page_size · integer · required

pages · integer · required