Describe a full backup archive on a target

POST api/v2/jobs/rvc '{"method":"kvm.full_backup_info","params":{"filename":"<backup_file_path>"},"hostnames":["<node_hostname>"]}'

Starts a SC//Reliant™ Virtual Controller (RVC) job to describe a KVM virtual machine full backup archive on one or more targets, without extracting the archive and without affecting the virtual machine. The result describes the backup file, how and when the backup was taken, the virtual machine as its saved definition describes it, its firmware, and the members of the archive. The available targets are a node, node group, or saved filter. The response will indicate that the RVC job is created and is scheduled to run. You can use the job ID from the response to retrieve the job status and the payload.

This method is only available when using RVC version 3.13.0 or later.

Important: Do not use this method to check whether a backup created with kvm.full_backup has finished. This method reads only the first members of the archive, and the disk is the last member, so it can succeed while the archive is still being written. For more information, see Troubleshooting RVC jobs.

Unlike kvm.full_backup, filename is the full path to the archive on the node. If the file does not exist, the node returns error -32071.

In order to perform this action, the following conditions must be met:

Must have the Remote Job Execution feature turned on at the site level.
The user must have the following capabilities:
- Create and Update a RVC job
- Call KVM read-only methods

Request syntax

post api/v2/jobs/rvc '{"method":"kvm.full_backup_info","params":{"filename":"<backup_file_path>"},"hostnames":["<node_hostname>"]}'

Request parameters

The request accepts the following data in JSON format.

Parameter	Type	Description	Required
`method`	String	The RVC action to start. This value is specified as a combination of the RVC module and method. For example, to describe a full backup archive you would specify the `kvm` module and the `full_backup_info` method combined as `kvm.full_backup_info`.	Yes
`params`	Object	The parameters that identify the backup archive to describe on the host node. The only supported parameter is `filename`, which is the full path to the backup archive on the node.	Yes
`hostnames`	String array	The list of node hostnames on which to run the RVC job.	Dependent. Only if no node group or saved filter is provided.
`node_group_name`	String	The name of the node group on which to run the RVC job. The RVC job will run on all nodes that are members of the node group.	Dependent. Only if no hostnames or saved filter is provided.
`node_group_id`	Integer	The ID of the node group on which to run the RVC job. The RVC job will run on all nodes that are members of the node group.	Dependent. Only if no hostnames or saved filter is provided.
`saved_filter_name`	String	The name of the saved filter on which to run the RVC job. The RVC job will run on all nodes that match the saved filter.	Dependent. Only if no hostnames or node group is provided.
`saved_filter_id`	Integer	The ID of the saved filter on which to run the RVC job. The RVC job will run on all nodes that match the saved filter.	Dependent. Only if no hostnames or node group is provided.

Response syntax

When the hostnames request parameter is used, the following response syntax is received.

{
    "id": integer,
    "type": "RVC3",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "method": "kvm.full_backup_info",
        "params": {
            "filename": "<backup_file_path>"
        },
        "update_rpm": boolean,
        "hostnames": [
            "string",
            "string"
        ]
    },
    "time_started": "timestamp"
}

When the node group or saved filter request parameters are used, the following response syntax is received.

{
    "id": integer,
    "type": "RVC3",
    "status": "string",
    "message": "string",
    "trigged_by": "string",
    "parameters": {
        "method": "kvm.full_backup_info",
        "params": {
            "filename": "<backup_file_path>"
        },
        "update_rpm": boolean,
        "hostnames": [],
        "node_group_name": "string",
        "node_group_id": integer,
        "saved_filter_name": "string",
        "saved_filter_id": integer
    },
    "time_started": "timestamp"
}

Response parameters

If the action is successful, an HTTP 200 response is returned. The following data is returned in JSON format.

Field	Type	Description
`id`	Integer	The ID of the RVC job.
`type`	String	The type of RVC job. For RVC jobs, it is `RVC3`.
`status`	String	The status of the job.
`message`	String	This field is reserved for internal use.
`trigged_by`	String	The username of the person who initiated the job.
`parameters`	Object	The request parameters indicating the method, method parameters, and the hostnames, node groups, or saved filters the RVC job ran on.
`time_started`	Timestamp	The timestamp indicating when the job started. The timestamp is given in ISO 8601 UTC datetime format.

Errors

For a list of potential errors, refer to the common errors, as this action does not have any unique error responses. For more information, see Common errors.

Examples

Example 1: Describe a full backup archive on a list of node hostnames.

This example starts a RVC job describing the backup archive /mnt/kvm_backups/kvm1_2026-10-06_scheduled.tar.gz on the node with hostname sit0001red0.

ruby api.rb <customer_code> POST api/v2/jobs/rvc '{"method":"kvm.full_backup_info","params":{"filename":"/mnt/kvm_backups/kvm1_2026-10-06_scheduled.tar.gz"},"hostnames":["sit0001red0"]}'

Response

{
  "id": 1781942,
  "type": "RVC3",
  "status": "pending",
  "message": null,
  "trigged_by": "test.user",
  "parameters": {
    "method": "kvm.full_backup_info",
    "params": {
      "filename": "/mnt/kvm_backups/kvm1_2026-10-06_scheduled.tar.gz"
    },
    "update_rpm": true,
    "hostnames": [
      "sit0001red0"
    ]
  },
  "time_started": "2026-10-11T20:39:56Z"
}

Example 2: Describe a full backup archive on the nodes in a specified node group.

This example starts a RVC job describing the backup archive /mnt/kvm_backups/kvm1_2026-10-06_scheduled.tar.gz on the nodes in node group Test Node Group.

ruby api.rb <customer_code> POST api/v2/jobs/rvc '{"method":"kvm.full_backup_info","params":{"filename":"/mnt/kvm_backups/kvm1_2026-10-06_scheduled.tar.gz"},"node_group_name":"Test Node Group"}'

Response

{
  "id": 1781945,
  "type": "RVC3",
  "status": "pending",
  "message": null,
  "trigged_by": "test.user",
  "parameters": {
    "method": "kvm.full_backup_info",
    "params": {
      "filename": "/mnt/kvm_backups/kvm1_2026-10-06_scheduled.tar.gz"
    },
    "update_rpm": true,
    "hostnames": [],
    "node_group_name": "Test Node Group"
  },
  "time_started": "2026-10-11T20:40:20Z"
}

Example 3: Retrieving the payload from the RVC job.

This example retrieves the payload from RVC job ID 1781942, which displays the result of the kvm.full_backup_info method.

ruby api.rb <customer_code> GET "api/jobs/1781942?include_payload=true"

Response

{
  "id": 1781942,
  "type": "RVC3",
  "status": "finished",
  "message": null,
  "trigged_by": "test.user",
  "success_nodes_count": 1,
  "failed_nodes_count": 0,
  "total_nodes_count": 1,
  "parameters": {
    "method": "kvm.full_backup_info",
    "params": {
      "filename": "/mnt/kvm_backups/kvm1_2026-10-06_scheduled.tar.gz"
    },
    "hostnames": [
      "sit0001red0"
    ],
    "update_rpm": true
  },
  "time_started": "2026-10-11T20:39:56Z",
  "time_finished": "2026-10-11T20:39:56Z",
  "payload": {
    "sit0001red0": [
      {
        "result": {
          "file": {
            "name": "kvm1_2026-10-06_scheduled.tar.gz",
            "path": "/mnt/kvm_backups/kvm1_2026-10-06_scheduled.tar.gz",
            "size": 645040690,
            "modified": "2026-10-06T18:33:04Z",
            "compressed": true
          },
          "backup": {
            "vm": "kvm1",
            "rvc": "3.13.0",
            "host": "sit0001red0",
            "files": [
              "backup.metadata",
              "xml/vm/vm.xml",
              "xml/vm/vm.ini",
              "lost+found",
              "disk0.qcow2"
            ],
            "format": 3,
            "created": "2026-10-06T18:32:51Z",
            "libvirt": "11.3.0",
            "automatic": false,
            "disk_file": "disk0.qcow2",
            "disk_path": "/kvm/kvm1/disk0.qcow2",
            "optimized": true,
            "snapshots": 0,
            "compressed": true,
            "hypervisor": "QEMU 10.0.2",
            "cluster_managed": true,
            "current_snapshot": "",
            "disk_cluster_size": 65536,
            "disk_virtual_size": 34359738368,
            "uncompressed_size": 1622802432
          },
          "members": [
            {
              "name": "backup.metadata",
              "size": 1266
            },
            {
              "name": "xml/vm/vm.xml",
              "size": 3951
            },
            {
              "name": "xml/vm/vm.ini",
              "size": 738
            },
            {
              "name": "lost+found",
              "size": 4096
            },
            {
              "name": "disk0.qcow2",
              "size": 1622802432
            }
          ],
          "firmware": {
            "type": "bios",
            "secure_boot": false
          },
          "virtual_machine": {
            "arch": "x86_64",
            "boot": [
              "hd"
            ],
            "name": "kvm1",
            "uuid": "00000000-0000-4000-8000-000000000001",
            "clock": "localtime",
            "disks": [
              {
                "bus": "scsi",
                "path": "/kvm/kvm1/disk0.qcow2",
                "device": "disk",
                "format": "qcow2",
                "target": "vda"
              },
              {
                "bus": "ide",
                "path": "/mnt/gold-images/iso/install.iso",
                "device": "cdrom",
                "format": "raw",
                "target": "hdc"
              }
            ],
            "title": null,
            "vcpus": 4,
            "video": "qxl",
            "memory": 8589934592,
            "machine": "pc-i440fx-7.2",
            "vm_type": "kvm",
            "cpu_mode": "host-model",
            "firmware": "bios",
            "graphics": [
              {
                "port": 5902,
                "type": "spice",
                "listen": "192.0.2.10",
                "password": null
              }
            ],
            "cpu_model": null,
            "on_reboot": "restart",
            "interfaces": [
              {
                "mac": "52:54:00:00:00:01",
                "type": "bridge",
                "model": "virtio",
                "source": "br0"
              }
            ],
            "description": null,
            "guest_agent": true,
            "host_devices": []
          }
        },
        "timestamp": 1791751196
      }
    ]
  }
}

For archives in an earlier archive format (format 2 or earlier), virtual_machine and firmware are null, and most fields in backup are empty or null. The archive format, not the RVC version that created it, determines which fields are returned. For more information about what an archive contains, see kvm.full_backup in the RVC client reference.