REST API - list
  1. Operations
  2. vcenter
  3. host

vcenter host: list

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

Request:

HTTP request

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

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

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

Representation:

{
    "value" : [
        {
            "host" : "obj-103",
            "name" : "string",
            "connection_state" : "CONNECTED",
            "power_state" : "POWERED_ON"
        },
        {
            "host" : "obj-103",
            "name" : "string",
            "connection_state" : "CONNECTED",
            "power_state" : "POWERED_ON"
        }
    ]
}

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.
500 unable_to_allocate_resource if more than 2500 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.