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:

- JSON
- XML

{
"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.