# vm.query

Type: object

##

Type: array
No Additional Items

#### Tuple Validation

##### Parameter 1: filters

#### filters

Type: array Default: []

List of filters for query results. See API documentation for "Query Methods" for more guidance.

No Additional Items

##### Each item of this array must be:

Type: object
Examples:

    [
        [
            "name",
            "=",
            "bob"
        ]
    ]

    [
        [
            "OR",
            [
                [
                    "name",
                    "=",
                    "bob"
                ],
                [
                    "name",
                    "=",
                    "larry"
                ]
            ]
        ]
    ]

##### Parameter 2: options

#### options

Type: object
Default:
{ "extra": {}, "order_by": [], "select": [], "count": false, "get": false, "offset": 0, "limit": 0, "force_sql_filters": false }

Query options including pagination, ordering, and additional parameters.

No Additional Properties

##

#### Extra

Type: object Default: {}

Extra options are defined on a per-endpoint basis and are described in the documentation for the associated query method.

##

#### Order By

Type: array of string Default: []

An array of field names describing the manner in which query results should be ordered. The field names may also have one of more of the following special prefixes: `-` (reverse sort direction), `nulls_first:` (place any null values at the head of the results list), `nulls_last:` (place any null values at the tail of the results list).

No Additional Items

##### Each item of this array must be:

Type: string
Example:

    [
        "size",
        "-devname",
        "nulls_first:-expiretime"
    ]

##

#### Select

Type: array Default: []

An array of field names specifying the exact fields to include in the query return. The dot character `.` may be used to explicitly select only subkeys of the query result.

No Additional Items

##### Each item of this array must be:

## Any of

Type: string
Type: array
No Additional Items

##### Each item of this array must be:

Type: object
Example:

    [
        "username",
        "Authentication.status"
    ]

##

#### Count

Type: boolean Default: false

Return a numeric value representing the number of items that match the specified `query-filters`.

##

#### Get

Type: boolean Default: false

Return the JSON object of the first result matching the specified `query-filters`. The query fails if there specified `query-filters` return no results.

##

#### Offset

Type: integer Default: 0

This specifies the beginning offset of the results array. When combined with the `limit` query-option it may be used to implement pagination of large results arrays. WARNING: some query methods provide volatile results and the onus is on the developer to understand whether pagination is appropriate for a particular query API method.

##

#### Limit

Type: integer Default: 0

This specifies the maximum number of results matching the specified `query-filters` to return. When combined wtih the `offset` query-option it may be used to implement pagination of large results arrays.

WARNING: Some query methods provide volatile results and the onus is on the developer to understand whether pagination is appropriate for a particular query API method.

##

#### Force Sql Filters

Type: boolean Default: false

Force use of SQL for result filtering to reduce response time. May not work for all methods.

##

#### Result

## Any of

Type: array of object
No Additional Items

##### Each item of this array must be:

#### VMQueryResultItem

Type: object
No Additional Properties

##

#### Command Line Args

Type: string

Additional command line arguments passed to the VM hypervisor.

##

#### Cpu Mode

Type: enum (of string)

CPU virtualization mode.

- `CUSTOM`: Use specified model.
- `HOST-MODEL`: Mirror host CPU.
- `HOST-PASSTHROUGH`: Provide direct access to host CPU features.

##### Must be one of:

- "CUSTOM"
- "HOST-MODEL"
- "HOST-PASSTHROUGH"

##

#### Cpu Model

Specific CPU model to emulate. `null` to use hypervisor default.

## Any of

Type: string
Type: null

##

#### Name

Type: string

Display name of the virtual machine.

Must be at least `1` characters long

##

#### Description

Type: string

Optional description or notes about the virtual machine.

##

#### Vcpus

Type: integer

Number of virtual CPUs allocated to the VM.

Value must be greater or equal to `1`

##

#### Cores

Type: integer

Number of CPU cores per socket.

Value must be greater or equal to `1`

##

#### Threads

Type: integer

Number of threads per CPU core.

Value must be greater or equal to `1`

##

#### Cpuset

Set of host CPU cores to pin VM CPUs to. `null` for no pinning.

## Any of

Type: string
Type: null

##

#### Nodeset

Set of NUMA nodes to constrain VM memory allocation. `null` for no constraints.

## Any of

Type: string
Type: null

##

#### Enable Cpu Topology Extension

Type: boolean

Whether to expose detailed CPU topology information to the guest OS.

##

#### Pin Vcpus

Type: boolean

Whether to pin virtual CPUs to specific host CPU cores. Improves performance but reduces host flexibility.

##

#### Suspend On Snapshot

Type: boolean

Whether to suspend the VM when taking snapshots.

##

#### Trusted Platform Module

Type: boolean

Whether to enable virtual Trusted Platform Module (TPM) for the VM.

##

#### Memory

Type: integer

Amount of memory allocated to the VM in mebibytes (MiB).

Value must be greater or equal to `20`

##

#### Min Memory

Minimum memory allocation for dynamic memory ballooning in mebibytes (MiB). Allows VM memory to shrink during low usage but guarantees this minimum. `null` to disable ballooning.

## Any of

Type: integer

Value must be greater or equal to `20`

Type: null

##

#### Hyperv Enlightenments

Type: boolean

Whether to enable Hyper-V enlightenments for improved Windows guest performance.

##

#### Bootloader

Type: enum (of string)

Boot firmware type. `UEFI` for modern UEFI, `UEFI_CSM` for legacy BIOS compatibility.

##### Must be one of:

- "UEFI_CSM"
- "UEFI"

##

#### Bootloader Ovmf

Type: string

OVMF firmware file to use for UEFI boot.

Examples:

    "OVMF_CODE.fd"

    "OVMF_CODE.secboot.fd"

##

#### Autostart

Type: boolean

Whether to automatically start the VM when the host system boots.

##

#### Hide From Msr

Type: boolean

Whether to hide hypervisor signatures from guest OS MSR access.

##

#### Ensure Display Device

Type: boolean

Whether to ensure at least one display device is configured for the VM.

##

#### Time

Type: enum (of string)

Guest OS time zone reference. `LOCAL` uses host timezone, `UTC` uses coordinated universal time.

##### Must be one of:

- "LOCAL"
- "UTC"

##

#### Shutdown Timeout

Type: integer

Maximum time in seconds to wait for graceful shutdown before forcing power off. Default 90s balances allowing sufficient time for clean shutdown while avoiding indefinite hangs.

Value must be greater or equal to `5` and lesser or equal to `300`

##

#### Arch Type

Guest architecture type. `null` to use hypervisor default.

## Any of

Type: string
Type: null

##

#### Machine Type

Virtual machine type/chipset. `null` to use hypervisor default.

## Any of

Type: string
Type: null

##

#### Uuid

Unique UUID for the VM. `null` to auto-generate.

## Any of

Type: string
Type: null

##

#### Devices

Type: array of object

Array of virtual devices attached to this VM.

No Additional Items

##### Each item of this array must be:

#### VMDeviceEntry

Type: object
No Additional Properties

##

#### Id

Type: integer

Unique identifier for the VM device.

##

#### Attributes

Device-specific configuration attributes.

## One of

#### VMCDROMDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for CD-ROM/DVD devices.

Specific value: `"CDROM"`

##

#### Path

Type: string Default: "*"

Path must not contain "{", "}" characters, and it should start with "/mnt/".

Must match regular expression: `^[^{}]*$`

Must be at least `1` characters long

#### VMDisplayDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for display/graphics devices.

Specific value: `"DISPLAY"`

##

#### Resolution

Type: enum (of string) Default: "1024x768"

Screen resolution for the virtual display.

##### Must be one of:

- "1920x1200"
- "1920x1080"
- "1600x1200"
- "1600x900"
- "1400x1050"
- "1280x1024"
- "1280x720"
- "1024x768"
- "800x600"
- "640x480"

##

#### Port

Default: null

VNC/SPICE port number for remote display access. `null` for auto-assignment.

## Any of

Type: integer

Value must be greater or equal to `5900` and lesser or equal to `65535`

Type: null

##

#### Web Port

Default: null

Web-based display access port number. `null` for auto-assignment.

## Any of

Type: integer
Type: null

##

#### Bind

Type: string Default: "127.0.0.1"

IP address to bind the display server to.

Must be at least `1` characters long

##

#### Wait

Type: boolean Default: false

Whether to wait for a client connection before starting the VM.

##

#### Password

Default: null

Password for display server authentication.

## Any of

Type: string
Type: null

##

#### Web

Type: boolean Default: true

Whether to enable web-based display access.

##

#### Type

Type: enum (of string) Default: "SPICE"

Display protocol type.

##### Must be one of:

- "SPICE"
- "VNC"

#### VMNICDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for network interface cards.

Specific value: `"NIC"`

##

#### Trust Guest Rx Filters

Type: boolean Default: false

Whether to trust guest OS receive filter settings for better performance.

##

#### Type

Type: enum (of string) Default: "E1000"

Network interface controller type. `E1000` for Intel compatibility, `VIRTIO` for performance.

##### Must be one of:

- "E1000"
- "VIRTIO"

##

#### Nic Attach

Default: null

Host network interface or bridge to attach to. `null` for no attachment.

## Any of

Type: string
Type: null

##

#### Mac

Default: null

MAC address for the virtual network interface. `null` for auto-generation.

## Any of

Type: string
Must match regular expression: `^([0-9A-Fa-f]{2}[:-]?){5}([0-9A-Fa-f]{2})$`
Type: null

#### VMPCIDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for PCI passthrough devices.

Specific value: `"PCI"`

##

#### Pptdev

Type: string

Host PCI device identifier to pass through to the VM.

Must be at least `1` characters long

#### VMRAWDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for raw disk devices.

Specific value: `"RAW"`

##

#### Path

Type: string Default: "127.0.0.1"

Path must not contain "{", "}" characters.

Must match regular expression: `^[^{}]*$`

Must be at least `1` characters long

##

#### Type

Type: enum (of string) Default: "AHCI"

Disk controller interface type. AHCI for compatibility, VIRTIO for performance.

##### Must be one of:

- "AHCI"
- "VIRTIO"

##

#### Exists

Type: boolean Default: false

Whether the disk file already exists or should be created.

##

#### Boot

Type: boolean Default: false

Whether this disk should be marked as bootable.

##

#### Size

Default: null

Size of the disk in bytes. Required if creating a new disk file.

## Any of

Type: integer
Type: null

##

#### Logical Sectorsize

Default: null

Logical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Physical Sectorsize

Default: null

Physical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Iotype

Type: enum (of string) Default: "THREADS"

I/O backend type for disk operations.

##### Must be one of:

- "NATIVE"
- "THREADS"
- "IO_URING"

##

#### Serial

Default: null

Serial number to assign to the virtual disk. `null` for auto-generated.

## Any of

Type: string

Must be at least `1` characters long

Type: null

#### VMDiskDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for virtual disk devices.

Specific value: `"DISK"`

##

#### Path

Default: null

Path to existing disk file or ZFS volume. `null` if creating a new ZFS volume.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Type

Type: enum (of string) Default: "AHCI"

Disk controller interface type. AHCI for compatibility, VIRTIO for performance.

##### Must be one of:

- "AHCI"
- "VIRTIO"

##

#### Create Zvol

Type: boolean Default: false

Whether to create a new ZFS volume for this disk.

##

#### Zvol Name

Default: null

Name for the new ZFS volume. Required if `create_zvol` is true.

## Any of

Type: string
Type: null

##

#### Zvol Volsize

Default: null

Size of the new ZFS volume in bytes. Required if `create_zvol` is true.

## Any of

Type: integer
Type: null

##

#### Logical Sectorsize

Default: null

Logical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Physical Sectorsize

Default: null

Physical sector size for the disk. `null` for default.

## Any of

Type: enum (of integer or null)

##### Must be one of:

- null
- 512
- 4096

Type: null

##

#### Iotype

Type: enum (of string) Default: "THREADS"

I/O backend type for disk operations.

##### Must be one of:

- "NATIVE"
- "THREADS"
- "IO_URING"

##

#### Serial

Default: null

Serial number to assign to the virtual disk. `null` for auto-generated.

## Any of

Type: string

Must be at least `1` characters long

Type: null

#### VMUSBDevice

Type: object
No Additional Properties

##

#### Dtype

Type: const

Device type identifier for USB devices.

Specific value: `"USB"`

##

Default: null

USB device attributes for identification. `null` for USB host controller only.

## Any of

#### USBAttributes

Type: object
No Additional Properties

##

#### Vendor Id

Type: string Default: "127.0.0.1"

USB vendor identifier in hexadecimal format (e.g., '0x1d6b' for Linux Foundation).

Must match regular expression: `^0x.*`

Must be at least `1` characters long

##

#### Product Id

Type: string Default: "127.0.0.1"

USB product identifier in hexadecimal format (e.g., '0x0002' for 2.0 root hub).

Must match regular expression: `^0x.*`

Must be at least `1` characters long

Type: null

##

#### Controller Type

Type: enum (of string) Default: "nec-xhci"

USB controller type for the virtual machine.

##### Must be one of:

- "piix3-uhci"
- "piix4-uhci"
- "ehci"
- "ich9-ehci1"
- "vt82c686b-uhci"
- "pci-ohci"
- "nec-xhci"
- "qemu-xhci"

##

#### Device

Default: null

Host USB device path to pass through. `null` for controller only.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Vm

Type: integer

ID of the virtual machine this device belongs to.

##

#### Order

Type: integer

Boot order priority for this device (lower numbers boot first).

##

#### Display Available

Type: boolean

Whether at least one display device is available for this VM.

##

#### Id

Type: integer

Unique identifier for the virtual machine.

##

#### VMStatus

Type: object

Current runtime status information for the VM.

No Additional Properties

##

#### State

Type: string Default: "127.0.0.1"

Current state of the virtual machine.

Must be at least `1` characters long

Examples:

    "RUNNING"

    "STOPPED"

    "SUSPENDED"

##

#### Pid

Process ID of the running VM. `null` if not running.

## Any of

Type: integer
Type: null

##

#### Domain State

Hypervisor-specific domain state.

## Any of

Type: string

Must be at least `1` characters long

Type: null

##

#### Enable Secure Boot

Type: boolean

Whether to enable UEFI Secure Boot for enhanced security.

#### VMQueryResultItem

Type: object
No Additional Properties

##

#### Command Line Args

Type: string

Additional command line arguments passed to the VM hypervisor.

##

#### Cpu Mode

Type: enum (of string)

CPU virtualization mode.

- `CUSTOM`: Use specified model.
- `HOST-MODEL`: Mirror host CPU.
- `HOST-PASSTHROUGH`: Provide direct access to host CPU features.

##### Must be one of:

- "CUSTOM"
- "HOST-MODEL"
- "HOST-PASSTHROUGH"

##

#### Cpu Model

Specific CPU model to emulate. `null` to use hypervisor default.

## Any of

Type: string
Type: null

##

#### Name

Type: string

Display name of the virtual machine.

Must be at least `1` characters long

##

#### Description

Type: string

Optional description or notes about the virtual machine.

##

#### Vcpus

Type: integer

Number of virtual CPUs allocated to the VM.

Value must be greater or equal to `1`

##

#### Cores

Type: integer

Number of CPU cores per socket.

Value must be greater or equal to `1`

##

#### Threads

Type: integer

Number of threads per CPU core.

Value must be greater or equal to `1`

##

#### Cpuset

Set of host CPU cores to pin VM CPUs to. `null` for no pinning.

## Any of

Type: string
Type: null

##

#### Nodeset

Set of NUMA nodes to constrain VM memory allocation. `null` for no constraints.

## Any of

Type: string
Type: null

##

#### Enable Cpu Topology Extension

Type: boolean

Whether to expose detailed CPU topology information to the guest OS.

##

#### Pin Vcpus

Type: boolean

Whether to pin virtual CPUs to specific host CPU cores. Improves performance but reduces host flexibility.

##

#### Suspend On Snapshot

Type: boolean

Whether to suspend the VM when taking snapshots.

##

#### Trusted Platform Module

Type: boolean

Whether to enable virtual Trusted Platform Module (TPM) for the VM.

##

#### Memory

Type: integer

Amount of memory allocated to the VM in mebibytes (MiB).

Value must be greater or equal to `20`

##

#### Min Memory

Minimum memory allocation for dynamic memory ballooning in mebibytes (MiB). Allows VM memory to shrink during low usage but guarantees this minimum. `null` to disable ballooning.

## Any of

Type: integer

Value must be greater or equal to `20`

Type: null

##

#### Hyperv Enlightenments

Type: boolean

Whether to enable Hyper-V enlightenments for improved Windows guest performance.

##

#### Bootloader

Type: enum (of string)

Boot firmware type. `UEFI` for modern UEFI, `UEFI_CSM` for legacy BIOS compatibility.

##### Must be one of:

- "UEFI_CSM"
- "UEFI"

##

#### Bootloader Ovmf

Type: string

OVMF firmware file to use for UEFI boot.

Examples:

    "OVMF_CODE.fd"

    "OVMF_CODE.secboot.fd"

##

#### Autostart

Type: boolean

Whether to automatically start the VM when the host system boots.

##

#### Hide From Msr

Type: boolean

Whether to hide hypervisor signatures from guest OS MSR access.

##

#### Ensure Display Device

Type: boolean

Whether to ensure at least one display device is configured for the VM.

##

#### Time

Type: enum (of string)

Guest OS time zone reference. `LOCAL` uses host timezone, `UTC` uses coordinated universal time.

##### Must be one of:

- "LOCAL"
- "UTC"

##

#### Shutdown Timeout

Type: integer

Maximum time in seconds to wait for graceful shutdown before forcing power off. Default 90s balances allowing sufficient time for clean shutdown while avoiding indefinite hangs.

Value must be greater or equal to `5` and lesser or equal to `300`

##

#### Arch Type

Guest architecture type. `null` to use hypervisor default.

## Any of

Type: string
Type: null

##

#### Machine Type

Virtual machine type/chipset. `null` to use hypervisor default.

## Any of

Type: string
Type: null

##

#### Uuid

Unique UUID for the VM. `null` to auto-generate.

## Any of

Type: string
Type: null

##

#### Devices

Type: array

Array of virtual devices attached to this VM.

No Additional Items

##### Each item of this array must be:

Type: object

##

#### Display Available

Type: boolean

Whether at least one display device is available for this VM.

##

#### Id

Type: integer

Unique identifier for the virtual machine.

##

Type: object

Current runtime status information for the VM.

##

#### Enable Secure Boot

Type: boolean

Whether to enable UEFI Secure Boot for enhanced security.

Type: integer

Required roles: VM_READ