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

Queries the details of one or more dedicated hosts. You can retrieve information such as the physical performance metrics, machine code, usage status, and the list of created ECS instances on the dedicated hosts. You can specify parameters such as dedicated host IDs, dedicated host cluster ID, hostname, and status to precisely query the details of dedicated hosts, providing strong support for efficient management and optimization of cloud computing compute 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 DescribeRegions to query the most recent region list.	cn-hangzhou
ZoneId	string	No	The zone ID. You can call DescribeZones to query the most recent zone list.	cn-hangzhou-g
DedicatedHostIds	string	No	The list of dedicated host IDs. You can specify up to 100 IDs, separated by commas (,).	["dh-bp165p6xk2tlw61e**", "dh-bp1f9vxmno7emy96**"]
DedicatedHostName	string	No	The name of the dedicated host.	MyDDHTestName
Status	string	No	The usage status of the dedicated host. Valid values: Available: The dedicated host is running as expected. UnderAssessment: The physical machine has potential risks. The physical machine is available but may cause issues for ECS instances on the dedicated host. PermanentFailure: The dedicated host has a permanent failure and is unavailable. TempUnavailable: The dedicated host is temporarily unavailable. Redeploying: The dedicated host is being restored. Default value: Available.	Available
DedicatedHostType	string	No	The type of the dedicated host. You can call DescribeDedicatedHostTypes to query the most recent list of dedicated host types.	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 for security reasons.	financial
PageNumber	integer	No	Note This parameter will be offline soon. Use NextToken and MaxResults to perform paged query operations for paging.	1
PageSize	integer	No	Note This parameter will be offline soon. Use NextToken and MaxResults to perform paged query operations for paging.	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 1000. Note Filtering by the default resource group is not supported.	rg-aek3b6jzp66****
NeedHostDetail	string	No	The detailed information of the dedicated host.	false
Tag	array<object>	No	The tags. Valid values of N: 0 to 20.
	object	No
Key	string	No	The tag key of the dedicated host. If you specify this parameter, the value 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, the value 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 use socket-level capacity information to view remaining resources (vCPUs, memory usage, remaining capacity, and total capacity) to determine whether an ECS instance of a specific instance type can be created. Valid values: true: Display socket-level capacity information. Only specific dedicated host types support displaying socket-level resource information. For more information, see View and export DDH information. false: Do not display socket-level capacity information. Important Each dedicated host typically has two CPUs, numbered Socket 0 and Socket 1. On a dedicated host, ECS instances are not created across sockets to ensure maximum performance. An ECS instance is created based on a single socket only. If the remaining computing resources of one socket are greater than or equal to the ECS instance type to be created, the ECS instance is created. If the remaining computing resources of each socket are less than the ECS instance type to be created, the ECS instance fails to be created, even if the combined remaining resources of both sockets exceed the ECS instance type requirements.	true
NextToken	string	No	The pagination token. Set this parameter to the NextToken value returned in the previous call. You do not need to set this parameter for the first request.	e71d8a535bd9cc11
MaxResults	integer	No	The maximum number of entries per page for a paged query. If you set this parameter, it indicates that the paging method using the MaxResults and NextToken parameters is used. Maximum value: 100. Default value: 10.	10
QueryInventory	boolean	No

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 plan for instances on the dedicated host when a failure occurs. Valid values: Migrate: The dedicated host is migrated to another physical server. Instances that were not stopped before the failure are started. Stop: Instances are stopped on the current dedicated host. After the dedicated host is confirmed to be irreparable, the instances are migrated to another physical server and restarted. Default value when the dedicated host uses cloud disk storage: Migrate. Default value when the dedicated host uses local disk storage: Stop.	Migrate
AutoPlacement	string	Indicates 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 Automatic deployment.	on
AutoReleaseTime	string	The automatic release time. The time follows the ISO 8601 standard in the `yyyy-MM-ddTHH:mmZ` format. The time is displayed in UTC+0.	2017-01-01T12:00Z
Capacity	object	The performance metrics of the dedicated host.
AvailableInstanceTypes	object
AvailableInstanceType	array<object>	The available instance types.
	object	The available instance type information.
AvailableInstanceCapacity	integer	The available capacity of the instance type.
InstanceType	string	The instance type. For more information, see Instance family. Note This parameter is required.
AvailableLocalStorage	integer	The remaining local disk capacity. Unit: GiB.	65
AvailableMemory	number	The remaining memory capacity. Unit: GiB.	25
AvailableVcpus	integer	The remaining number of vCPUs.	5
AvailableVgpus	integer	The number of available virtual GPUs.	2
LocalStorageCategory	string	The category of local disks.	i2
SocketCapacities	object
SocketCapacity	array<object>	The socket-level capacity information.
	object
AvailableMemory	number	The remaining memory capacity. Unit: GiB.	65
AvailableVcpu	integer	The remaining number of 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 virtual GPUs.	10
ChargeType	string	The billable methods of the dedicated host.	Prepaid
Cores	integer	The number of cores per physical 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 follows the ISO 8601 standard in the `yyyy-MM-ddTHH:mmZ` format. The time is displayed in UTC+0.	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 user ID of the dedicated host owner.	100************7
DedicatedHostType	string	The type of the dedicated host.	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 follows the ISO 8601 standard in the `yyyy-MM-ddTHH:mmZ` format. The time is displayed in UTC+0.	2019-01-01T12:00Z
GPUSpec	string	The GPU model.	gpu
HostDetailInfo	object	This parameter is about to be deprecated. For better compatibility, use other parameters.
SerialNumber	string	This parameter is about to be deprecated. For better compatibility, use other parameters.	null
VgpuVersion	string	This parameter is about to be deprecated. For better compatibility, use other parameters.	null
Instances	object
Instance	array<object>	The 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 user ID of the ECS instance owner.	128************0
InstanceType	string	The ECS instance type of the instance created on the dedicated host.	ecs.g5.large
SocketId	string	The ID of the socket to which the instance belongs.	0,1
MachineId	string	The machine code of the dedicated host.	12aaa123456ff19dec12345d3026e****
NetworkAttributes	object	The network attributes of the dedicated host.
SlbUdpTimeout	integer	The 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 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 for 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 subscription unit. 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 as expected. UnderAssessment: The physical machine has potential risks. The physical machine is available but may cause issues for 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 families supported by the dedicated host.
	string	The custom instance family supported by the dedicated host.	ecs.ddh6s.custom
SupportedInstanceTypeFamilies	object
SupportedInstanceTypeFamily	array	The ECS instance families supported by the dedicated host.
	string	The ECS instance family supported by the dedicated host.	ecs.g5
SupportedInstanceTypesList	object
SupportedInstanceTypesList	array	The 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 tags of the dedicated host.
	object	The tag key-value pair.
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 query token returned in this invoke. If the return value is empty when you use MaxResults and NextToken for paging, no more data is available.	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": ""
              }
            ]
          },
          "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.