Use DescribeDedicatedHosts to query dedicated host details - Elastic Compute Service - Alibaba Cloud - Elastic Compute Service

Queries the details of one or more dedicated hosts. This operation retrieves information including physical performance metrics, machine codes, usage status, and the list of created ECS instances. You can specify parameters such as dedicated host IDs, dedicated host cluster ID, hostname, and status to accurately query the required details, which provides strong support for the efficient management and optimization of cloud computing resources.

Operation description

You can query the details of one or more dedicated hosts by using one of the following methods:

Specify DedicatedHostIds to query the details of dedicated hosts.
Specify DedicatedHostClusterId to query the details of dedicated hosts in a dedicated host cluster.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ecs:DescribeDedicatedHosts

get

DedicatedHost

acs:ecs:{#regionId}:{#accountId}:ddh/*

DedicatedHost

acs:ecs:{#regionId}:{#accountId}:ddh/{#ddhId}

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the dedicated host. You can call the DescribeRegions operation to query the most recent region list.	cn-hangzhou
ZoneId	string	No	The zone ID. You can call the DescribeZones operation to query the most recent zone list.	cn-hangzhou-g
DedicatedHostIds	string	No	The IDs of the dedicated hosts. You can specify up to 100 IDs. Separate multiple IDs with commas (,).	["dh-bp165p6xk2tlw61e**", "dh-bp1f9vxmno7emy96**"]
DedicatedHostName	string	No	The name of the dedicated host.	MyDDHTestName
Status	string	No	The status of the dedicated host. Valid values: Available: The dedicated host is running. This is the normal status of a dedicated host. UnderAssessment: The physical machine has risks. The physical machine is available during the fault incubation period, but issues may occur on the ECS instances on the dedicated host. PermanentFailure: A permanent failure occurred. The dedicated host is unavailable. TempUnavailable: The dedicated host is temporarily unavailable. Redeploying: The dedicated host is being recovered. Default value: Available.	Available
DedicatedHostType	string	No	The type of the dedicated host. You can call the DescribeDedicatedHostTypes operation to query the most recent dedicated host type list.	ddh.g5
LockReason	string	No	The reason why the dedicated host is locked. Valid values: financial: The dedicated host is locked due to overdue payments. security: The dedicated host is locked due to security reasons.	financial
PageNumber	integer	No	Note This parameter will be deprecated soon. We recommend that you use NextToken and MaxResults for pagination.	1
PageSize	integer	No	Note This parameter will be deprecated soon. We recommend that you use NextToken and MaxResults for pagination.	10
ResourceGroupId	string	No	The ID of the resource group to which the dedicated host belongs. When you use this parameter to filter resources, the resource count cannot exceed 1,000. Note Filtering by the default resource group is not supported.	rg-aek3b6jzp66****
NeedHostDetail	string	No	Specifies whether to return the details of the dedicated host.	false
Tag	array<object>	No	The list of tags. You can specify 0 to 20 tags.
	object	No
Key	string	No	The tag key of the dedicated host. If you specify this parameter, it cannot be an empty string. The tag key can be up to 128 characters in length, and cannot start with `aliyun` or `acs:`. It cannot contain `http://` or `https://`.	TestKey
Value	string	No	The tag value of the dedicated host. If you specify this parameter, it can be an empty string. The tag value can be up to 128 characters in length, and cannot contain `http://` or `https://`.	TestValue
DedicatedHostClusterId	string	No	The ID of the dedicated host cluster.	dc-bp12wlf6am0vz9v2****
SocketDetails	string	No	Specifies whether to display socket-level capacity information. You can view the remaining resource information (vCPU and memory usage, remaining capacity, and total capacity) at the socket level to determine whether ECS instances of the corresponding type can be created. Valid values: true: Display the information. Only dedicated hosts of specific types support displaying socket-level resource information. For more information, see View and export dedicated host information. false: Do not display the information. Important Generally, each dedicated host has two CPUs, and the ID of each CPU is Socket 0 or Socket 1. On an exclusive dedicated host, to ensure that the ECS instances on the dedicated host deliver maximum performance, ECS instances are not created across sockets. This means that an ECS instance is created based on only one socket. If the remaining computing resources of one socket are greater than or equal to the resources required by the ECS instance type to be created, the ECS instance is created. If the remaining computing resources of each socket are less than the resources required by the ECS instance type to be created, the ECS instance fails to be created. Even if the total remaining resources of the two sockets on the dedicated host are greater than the resources required by the ECS instance type, the ECS instance still cannot be created.	true
NextToken	string	No	The query token. Set the value to the NextToken value returned in the previous call to this operation. You do not need to specify this parameter when you call this operation for the first time.	e71d8a535bd9cc11
MaxResults	integer	No	The maximum number of entries per page for a paged query. If you specify this parameter, the query uses the combination of MaxResults and NextToken for pagination. Maximum value: 100. Default value: 10.	10
QueryInventory	boolean	No	Specifies whether to query the inventory information of the dedicated host.

Response elements

Element	Type	Description	Example
	object
DedicatedHosts	object
DedicatedHost	array<object>	The details of the dedicated hosts.
	array<object>	The ID of the managed private space to which the dedicated host belongs.
ActionOnMaintenance	string	The migration policy for instances on the dedicated host when a failure occurs. Valid values: Migrate: Migrates the dedicated host to another physical server and starts the instances that were running before the failure. Stop: Stops the instances on the dedicated host. After the dedicated host is confirmed unrepairable, migrates the instances to another physical server and restarts them. Default value: Migrate if the dedicated host uses cloud disks, and Stop if the dedicated host uses local disks.	Migrate
AutoPlacement	string	Specifies whether the dedicated host is added to the automatic deployment resource pool. Valid values: on: The dedicated host is added to the automatic deployment resource pool. off: The dedicated host is not added to the automatic deployment resource pool. For more information about automatic deployment, see Introduction to automatic deployment.	on
AutoReleaseTime	string	The automatic release time. The time is displayed in the `yyyy-MM-ddTHH:mmZ` format in accordance with the ISO 8601 standard. The time must be in UTC.	2017-01-01T12:00Z
Capacity	object	The performance metrics of the dedicated host.
AvailableInstanceTypes	object
AvailableInstanceType	array<object>	The list of available instance types.
	object	The available instance type.
AvailableInstanceCapacity	integer	The available capacity for the instance type.	0
InstanceType	string	The instance type. For more information, see Instance family. Note This parameter is required.	ecs.g5.large
AvailableLocalStorage	integer	The available local disk capacity. Unit: GiB.	65
AvailableMemory	number	The available memory capacity. Unit: GiB.	25
AvailableVcpus	integer	The number of available vCPUs.	5
AvailableVgpus	integer	The number of available vGPUs.	2
LocalStorageCategory	string	The local disk category.	i2
SocketCapacities	object
SocketCapacity	array<object>	The list of capacity information by socket.
	object
AvailableMemory	number	The available memory capacity. Unit: GiB.	65
AvailableVcpu	integer	The number of available vCPUs.	64
SocketId	integer	The socket ID.	1
TotalMemory	number	The total memory capacity. Unit: GiB.	128
TotalVcpu	integer	The total number of vCPUs.	128
TotalLocalStorage	integer	The total local disk capacity. Unit: GiB.	512
TotalMemory	number	The total memory capacity. Unit: GiB.	1024
TotalVcpus	integer	The total number of vCPUs.	56
TotalVgpus	integer	The total number of vGPUs.	10
ChargeType	string	The billable methods of the dedicated host.	Prepaid
Cores	integer	The number of cores per CPU.	3
CpuOverCommitRatio	number	The CPU overcommit ratio. Valid values: 1 to 5.	1
CreationTime	string	The creation time of the dedicated host. The time is displayed in the `yyyy-MM-ddTHH:mmZ` format in accordance with the ISO 8601 standard. The time must be in UTC.	2018-01-01T12:00Z
DedicatedHostClusterId	string	The ID of the dedicated host cluster to which the dedicated host belongs.	dc-bp12wlf6am0vz9v2****
DedicatedHostId	string	The ID of the dedicated host.	dh-bp165p6xk2tlw61e****
DedicatedHostName	string	The name of the dedicated host.	MyDDHTestName
DedicatedHostOwnerId	integer	The ID of the user that owns the dedicated host.	100************7
DedicatedHostType	string	The dedicated host type.	ddh.g5
Description	string	The description of the dedicated host.	this-is-my-DDH
ExpiredTime	string	The expiration time of the subscription dedicated host. The time is displayed in the `yyyy-MM-ddTHH:mmZ` format in accordance with the ISO 8601 standard. The time must be in UTC.	2019-01-01T12:00Z
GPUSpec	string	The GPU model.	gpu
HostDetailInfo	object	[Deprecated] This parameter will be deprecated. To improve compatibility, we recommend that you use other parameters instead.
SerialNumber	string	[Deprecated] This parameter will be deprecated. To improve compatibility, we recommend that you use other parameters instead.	null
VgpuVersion	string	[Deprecated] This parameter will be deprecated. To improve compatibility, we recommend that you use other parameters instead.	null
Instances	object
Instance	array<object>	The list of ECS instances created on the dedicated host.
	object	The ECS instance created on the dedicated host.
InstanceId	string	The instance ID of the ECS instance created on the dedicated host.	i-bp14ot0ykf8w13a1****
InstanceOwnerId	integer	The ID of the user that owns the ECS instance.	128************0
InstanceType	string	The ECS instance type of the instance created on the dedicated host.	ecs.g5.large
SocketId	string	The socket ID where the instance is located.	0,1
MachineId	string	The machine ID of the dedicated host.	12aaa123456ff19dec12345d3026e****
NetworkAttributes	object	The network attributes of the dedicated host.
SlbUdpTimeout	integer	The Server Load Balancer (SLB) UDP timeout period. Unit: seconds. Only 60 seconds is supported.	60
UdpTimeout	integer	The UDP timeout period. Unit: seconds. Only 60 seconds is supported.	60
OperationLocks	object
OperationLock	array<object>	The list of reasons why the dedicated host is locked.
	object
LockReason	string	The reason why the dedicated host is locked. Valid values: financial: The dedicated host is locked due to overdue payments. security: The dedicated host is locked due to security reasons.	financial
PhysicalGpus	integer	The number of physical GPUs.	10
RegionId	string	The region ID of the dedicated host.	cn-hangzhou
ResourceGroupId	string	The ID of the resource group to which the dedicated host belongs.	rg-aek3b6jzp66****
SaleCycle	string	The billing cycle of the subscription dedicated host. Valid values: Month. Year.	Month
SchedulerOptions.ManagedPrivateSpaceId	string	The ID of the managed private space to which the dedicated host belongs.	mps-iq81z6pkbqjx61php46e
Sockets	integer	The number of physical CPUs.	5
Status	string	The status of the dedicated host. Valid values: Available: The dedicated host is running normally. UnderAssessment: The physical server has potential risks. The physical server is available but may cause issues for the ECS instances on the dedicated host. PermanentFailure: The dedicated host has a permanent failure and is unavailable.	Available
SupportedCustomInstanceTypeFamilies	object
SupportedCustomInstanceTypeFamily	array	The custom instance type family supported by the dedicated host.
	string	The custom instance type family supported by the dedicated host.	ecs.ddh6s.custom
SupportedInstanceTypeFamilies	object
SupportedInstanceTypeFamily	array	The list of ECS instance type families supported by the dedicated host.
	string	The ECS instance type family supported by the dedicated host.	ecs.g5
SupportedInstanceTypesList	object
SupportedInstanceTypesList	array	The list of ECS instance types supported by the dedicated host.
	string	The ECS instance type supported by the dedicated host.	ecs.g5.large
Tags	object
Tag	array<object>	The list of tags of the dedicated host.
	object	The tag.
TagKey	string	The tag key of the dedicated host.	TestKey
TagValue	string	The tag value of the dedicated host.	TestValue
ZoneId	string	The zone ID.	cn-hangzhou-g
NextToken	string	The paging token returned by this invoke. When you use MaxResults and NextToken for paged query, and this return value is empty, it indicates that no more data is returned.	e71d8a535bd9cc11
PageNumber	integer	The page number of the dedicated host list.	5
PageSize	integer	The number of entries per page.	1
RequestId	string	The request ID.	7654525A-9964-4ABB-8BCD-98F8835E809A
TotalCount	integer	The total number of dedicated hosts.	3

Examples

Success response

JSON format

{
  "DedicatedHosts": {
    "DedicatedHost": [
      {
        "ActionOnMaintenance": "Migrate",
        "AutoPlacement": "on",
        "AutoReleaseTime": "2017-01-01T12:00Z",
        "Capacity": {
          "AvailableInstanceTypes": {
            "AvailableInstanceType": [
              {
                "AvailableInstanceCapacity": 0,
                "InstanceType": "ecs.g5.large"
              }
            ]
          },
          "AvailableLocalStorage": 65,
          "AvailableMemory": 25,
          "AvailableVcpus": 5,
          "AvailableVgpus": 2,
          "LocalStorageCategory": "i2",
          "SocketCapacities": {
            "SocketCapacity": [
              {
                "AvailableMemory": 65,
                "AvailableVcpu": 64,
                "SocketId": 1,
                "TotalMemory": 128,
                "TotalVcpu": 128
              }
            ]
          },
          "TotalLocalStorage": 512,
          "TotalMemory": 1024,
          "TotalVcpus": 56,
          "TotalVgpus": 10
        },
        "ChargeType": "Prepaid",
        "Cores": 3,
        "CpuOverCommitRatio": 1,
        "CreationTime": "2018-01-01T12:00Z",
        "DedicatedHostClusterId": "dc-bp12wlf6am0vz9v2****",
        "DedicatedHostId": "dh-bp165p6xk2tlw61e****",
        "DedicatedHostName": "MyDDHTestName",
        "DedicatedHostOwnerId": 0,
        "DedicatedHostType": "ddh.g5",
        "Description": "this-is-my-DDH",
        "ExpiredTime": "2019-01-01T12:00Z",
        "GPUSpec": "gpu",
        "HostDetailInfo": {
          "SerialNumber": "null",
          "VgpuVersion": "null"
        },
        "Instances": {
          "Instance": [
            {
              "InstanceId": "i-bp14ot0ykf8w13a1****",
              "InstanceOwnerId": 0,
              "InstanceType": "ecs.g5.large",
              "SocketId": "0,1"
            }
          ]
        },
        "MachineId": "12aaa123456ff19dec12345d3026e****",
        "NetworkAttributes": {
          "SlbUdpTimeout": 60,
          "UdpTimeout": 60
        },
        "OperationLocks": {
          "OperationLock": [
            {
              "LockReason": "financial"
            }
          ]
        },
        "PhysicalGpus": 10,
        "RegionId": "cn-hangzhou",
        "ResourceGroupId": "rg-aek3b6jzp66****",
        "SaleCycle": "Month",
        "SchedulerOptions.ManagedPrivateSpaceId": "mps-iq81z6pkbqjx61php46e",
        "Sockets": 5,
        "Status": "Available",
        "SupportedCustomInstanceTypeFamilies": {
          "SupportedCustomInstanceTypeFamily": [
            "ecs.ddh6s.custom"
          ]
        },
        "SupportedInstanceTypeFamilies": {
          "SupportedInstanceTypeFamily": [
            "ecs.g5"
          ]
        },
        "SupportedInstanceTypesList": {
          "SupportedInstanceTypesList": [
            "ecs.g5.large"
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagKey": "TestKey",
              "TagValue": "TestValue"
            }
          ]
        },
        "ZoneId": "cn-hangzhou-g"
      }
    ]
  },
  "NextToken": "e71d8a535bd9cc11",
  "PageNumber": 5,
  "PageSize": 1,
  "RequestId": "7654525A-9964-4ABB-8BCD-98F8835E809A",
  "TotalCount": 3
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidStatus.ValueNotSupported	The pecified dedicated host status is not supported.	The host is in a state that does not support the current operation.
400	MissingParamter.RegionId	The regionId should not be null.	The RegionId parameter is required.
400	InvalidParameter.DedicatedHostIds	The specified parameter dedicatedHostIds is not valid.	The specified DedicatedHostIds parameter is invalid.
400	InvalidRegion.NotFound	The specified parameter RegionId is not valid.	The specified RegionId parameter is invalid.
400	InvalidZone.NotFound	The specified parameter ZoneId is not valid.	The specified ZoneId parameter is invalid.
403	InvalidDedicatedHostIds.Malformed	The amount of specified dedicatedHostIds exceeds the limit.	More than 100 dedicated host IDs are specified in the DedicatedHostIds value.
404	InvalidLockReason.NotFound	The specified LockReason is not found.	The specified lockout reason does not exist.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.