Retrieval of VM managers

Use the GET operation on the api/sam/vmmanagers element to retrieve information about VM managers that are defined in your infrastructure. The API returns the same data as available on the VM Managers panel. The VM Managers that do not report longer than the value allowed through maxVMManagerVisibility are not be returned by the API.

The REST API returns more information than is visible on the user interface. It returns information about VM managers that are managed both in central and distributed mode. It also returns information from virtualization technologies that do not require defining connection to the VM manager such as Xen or KVM without RHV-M. The scope of VM managers from which data is collected depends on which VM Manager Tools are installed on computers that belong to the computer group to which you are assigned.

Permission required: To retrieve information about VM managers, you must have the 'Manage VM Managers and Servers' permission.

Table 1. Operation descriptions
Operation details Description
Operation GET /api/sam/vmmanagers
Purpose Returns a list of VM managers.
HTTP method GET
Resource URI https://server_host_name:port_number/api/sam/vmmanagers?token=token
Request Content-Type application/json
Response Content-Type application/json
Normal HTTP response codes
  • 200 – OK
Error HTTP response codes
  • 400 – "Bad Request" if a query parameter contains errors or is missing
  • 401 – "Unauthorized" if the user does not have the Manage VM Managers and Servers permission
  • 403 – "Forbidden" if the computer where the central VM Manager tool is installed does not belong to the computer group that the user is assigned
  • 500 – "Internal Server Error" if no VM Manager tool is defined in the BigFix Inventory database.

Message body includes an error message with details.

Response attributes

Table 2. Response attributes and their possible values
Attribute Possible values
lastcollection Date and time when data was collected from the VM manager.
deleted Indicates whether the VM manager was removed from BigFix Inventory.
lastmodified The date and time when the VM manager was last modified.
login User name that is used to access the VM manager.
protocol Communication protocol used by the VM manager. The attribute is applicable only for Hyper-V.
  • 0 - WinRM
  • 1 - PowerShell
  • null - the VM manager is not Hyper-V
sharedcredentials Indicates whether the VM manager shares credentials with other hosts in the same cluster. The attribute is applicable only for Hyper-V.
status Status of the VM manager.
  • -1 - Invalid credentials - suspended
  • 0 - Pending
  • 1 - OK
  • 2 - Connection failed
  • 3 - Invalid credentials - attempting
  • 6 - Duplicated address
  • 7 - Hard timeout - suspended
  • 8 - OK - duplicated UUIDs discarded
  • 9 - No VM Manager Data
  • 98 - Inactive
  • 99 - Unknown problem
For more information about each status, see: VM manager statuses.
type Type of the VM manager.
  • 1 - Hyper-V
  • 2 - VMware vSphere or VMware ESX
  • 3 - RHV-M
  • 9.2.12 4 - Citrix Hypervisor (formerly XenServer)
  • 99 - Other. The value is used for VM managers for which data is collected by using the Run Capacity Scan on Virtualization Hosts task, for example Xen and KVM without RHV-M.
url Web address of the VM manager.
vmmanagerid ID of the VM manager.
vmmanagertoolid ID of the VM Manager tool that collects information from the particular VM manager.

Example HTTP conversation

GET http://localhost:9081/api/sam/vmmanagers
Response body (JSON)
    "lastmodified":"2016-06-12 09:06:51.723",