Retrieval of VM managers

You use the GET operation on the api/sam/vmmanagers element to request information about VM managers that are defined in your infrastructure. 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, VM managers that were inactive for more than 90 days as well as those that were removed. 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.


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

Resource URL


Resource information

Table 1. Resource information
Operation details Description
Purpose Returns a list of VM managers.
HTTP method GET
Resource URI https://hostname:port/api/sam/vmmanagers
Request headers
Accept-Language (optional)
  • Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language.
  • Values: en-US (only English is supported)
  • Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests.
  • Values: an alphanumeric string that is generated in License Metric Tool
Request Content-Type application/json
Response headers
  • Use: Specifies the content type of the response.
  • Values: application/json
  • Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language.
  • Values: en-US, …
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 no VM Manager Tool is defined in the License Metric Tool database. The code might also indicate an unknown problem that requires contacting IBM support.

Message body includes an error message with details.

Response attributes

Table 2. Response attributes and their possible values
Attribute Possible values
deleted Indicates whether the VM manager was removed from License Metric Tool.
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 and Azure Stack HCI.
  • 0 - WinRM
  • 1 - PowerShell
  • null - the VM manager is neither Hyper-V nor Azure Stack HCI
sharedcredentials Indicates whether the VM manager shares credentials with other hosts in the same cluster. The attribute is applicable only for Hyper-V and Azure Stack HCI.
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 or Azure Stack HCI
  • 2 - VMware vSphere or VMware ESX
  • 3 - RHV-M
  • 9.2.12 4 - Citrix Hypervisor (formerly XenServer)
  • 9.2.14 5 - Oracle VM
  • 9.2.17 6 - Nutanix
  • 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.
9.2.22 vmmanagertooltype VM Manager Tool deployment type.
  • 0 - Disconnected
  • 1 - Central
  • 2 - Local
For more information, see: VM Manager Tool deployment types and flow of data.
vmmanagertoolid ID of the VM Manager Tool that collects information from the particular VM manager.

Example HTTP conversation

GET https://hostname:port/api/sam/vmmanagers
Request header
Accept: application/json
Accept-Language: en-US
Token: <token>
Response body (JSON)

    "vmmanagertoolid": 1,
    "lastmodified":"2016-06-12 09:06:51.723",