1. Operations
  2. vcenter
  3. host

vcenter host: list

Returns information about at most 1000 visible (subject to permission checks) hosts in vCenter matching the vcenter.host.filter_spec.

Request:

HTTP request

GET https://{server}/rest/vcenter/host

?filter.connection_states.1=CONNECTED
&filter.connection_states.2=CONNECTED
&filter.clusters.1=obj-103
&filter.clusters.2=obj-103
&filter.datacenters.1=obj-103
&filter.datacenters.2=obj-103
&filter.names.1=string
&filter.names.2=string
&filter.hosts.1=obj-103
&filter.hosts.2=obj-103
&filter.folders.1=obj-103
&filter.folders.2=obj-103
&filter.standalone=true

Request Query Parameters:

Name Type Description
bold = required
filter filter_spec Optional. Specification of matching hosts for which information should be returned.
filter.hosts string[] Identifiers of hosts that can match the filter.

Optional. If unset or empty, hosts with any identifier match the filter.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: HostSystem. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: HostSystem.
filter.names string[] Names that hosts must have to match the filter (see vcenter.host.summary.name).

Optional. If unset or empty, hosts with any name match the filter.
filter.folders string[] Folders that must contain the hosts for the hosts to match the filter.

Optional. If unset or empty, hosts in any folder match the filter.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: Folder. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: Folder.
filter.datacenters string[] Datacenters that must contain the hosts for the hosts to match the filter.

Optional. If unset or empty, hosts in any datacenter match the filter.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: Datacenter. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: Datacenter.
filter.standalone boolean If true, only hosts that are not part of a cluster can match the filter, and if false, only hosts that are are part of a cluster can match the filter.

Optional. If unset Hosts can match filter independent of whether they are part of a cluster or not. If this field is true and vcenter.host.filter_spec.clusters os not empty, no hosts will match the filter.
filter.clusters string[] Clusters that must contain the hosts for the hosts to match the filter.

Optional. If unset or empty, hosts in any cluster and hosts that are not in a cluster match the filter. If this field is not empty and vcenter.host.filter_spec.standalone is true, no hosts will match the filter.When clients pass a value of this structure as a parameter, the field must contain identifiers for the resource type: ClusterComputeResource. When operations return a value of this structure as a result, the field will contain identifiers for the resource type: ClusterComputeResource.
filter.connection_states string[] Connection states that a host must be in to match the filter (see vcenter.host.summary.connection_state.

Optional. If unset or empty, hosts in any connection state match the filter.

Response:

HTTP Status Code: 200

Representations:

{
    "value": [
        {
            "connection_state": "CONNECTED",
            "host": "obj-103",
            "name": "string",
            "power_state": "POWERED_ON"
        },
        {
            "connection_state": "CONNECTED",
            "host": "obj-103",
            "name": "string",
            "power_state": "POWERED_ON"
        }
    ]
}
<?xml version="1.0" ?>
<ns0:List-Result xmlns:ns0="http://vmware.com/vcenter/host" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <value-array>
    <array-item>
      <connection_state>CONNECTED</connection_state>
      <host>obj-103</host>
      <power_state>POWERED_ON</power_state>
      <name>string</name>
    </array-item>
    <array-item>
      <connection_state>CONNECTED</connection_state>
      <host>obj-103</host>
      <power_state>POWERED_ON</power_state>
      <name>string</name>
    </array-item>
  </value-array>
</ns0:List-Result>

Response Type:

Name Type Description
bold = required
value summary[] Commonly used information about the hosts matching the vcenter.host.filter_spec.
value[].host string Identifier of the host.

When clients pass a value of this structure as a parameter, the field must be an identifier for the resource type: HostSystem. When operations return a value of this structure as a result, the field will be an identifier for the resource type: HostSystem.
value[].name string Name of the host.
value[].connection_state string Connection status of the host

Defines the connection status of a host. Value is one of:
CONNECTED: Host is connected to the vCenter Server
DISCONNECTED: Host is disconnected from the vCenter Server
NOT_RESPONDING: VirtualCenter is not receiving heartbeats from the server. The state automatically changes to connected once heartbeats are received again.
value[].power_state string Power state of the host

Defines the power states of a host. Value is one of:
POWERED_ON: The host is powered on. A host that is entering standby mode is also in this state.
POWERED_OFF: The host was specifically powered off by the user through vCenter server. This state is not a cetain state, because after vCenter server issues the command to power off the host, the host might crash, or kill all the processes but fail to power off.
STANDBY: The host was specifically put in standby mode, either explicitly by the user, or automatically by DPM. This state is not a cetain state, because after VirtualCenter issues the command to put the host in standby state, the host might crash, or kill all the processes but fail to enter standby mode. A host that is exiting standby mode is also in this state.Optional. It is only relevant when connection_state has value CONNECTED. This field is optional and it is only relevant when the value of connection_state is CONNECTED.

Errors:

HTTP Status Code Type Description
400 invalid_argument if the vcenter.host.filter_spec.connection_states field contains a value that is not supported by the server.
400 unable_to_allocate_resource if more than 1000 hosts match the vcenter.host.filter_spec.
503 service_unavailable if the system is unable to communicate with a service to complete the request.
401 unauthenticated if the user can not be authenticated.
403 unauthorized if the user doesn't have the required privileges.