DescribeInstances - Elastic Compute Service

Queries Elastic Compute Service (ECS) instances by various filter conditions. The details of the queried ECS instances are returned in the response.

Operation description

Instructions
- When you call the API operation by using Alibaba Cloud CLI, you must specify request parameter values of different data types in the required formats. For more information, see Parameter formats.
- If you use a Resource Access Management (RAM) user or RAM role that does not have the permissions to call this operation, an empty list is returned.
Suggestions
- Specify DryRun in the request to perform a dry run. In the dry run, the system checks the validity and authorization status of the parameters.
- You can use one of the following methods to check the responses:
  - Method 1: During a paged query, when you call the DescribeInstances operation to retrieve the first page of results, use MaxResults to specify the maximum number of entries to return in the call. The return value of NextToken is a pagination token, which you can use in the next request to retrieve a new page of results. When you call the DescribeInstances operation to retrieve a new page of results, set NextToken to the NextToken value returned in the previous call and set MaxResults to specify the maximum number of entries to return in this call.
  - Method 2: Use PageSize to specify the number of entries per page, and then use PageNumber to specify the page number.
  You can use only one of the preceding methods. If a large number of entries are returned, we recommend that you use Method 1.
  
  **
  
  Note If you specify MaxResults or NextToken, the PageSize and PageNumber request parameters do not take effect and the TotalCount response parameter is invalid.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
ecs:DescribeInstances	get	Instance `acs:ecs:{#regionId}:{#accountId}:instance/` *Instance `acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}`	ResourceOwner	none

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.	cn-hangzhou
VpcId	string	No	The ID of the virtual private cloud (VPC).	v-bp67acfmxazb4p****
VSwitchId	string	No	The ID of the vSwitch.	vsw-bp67acfmxazb4p****
ZoneId	string	No	The zone ID of the instance.	cn-hangzhou-g
InstanceNetworkType	string	No	The network type of the instance. Valid values: classic vpc	vpc
SecurityGroupId	string	No	The ID of the security group to which the instance belongs.	sg-bp67acfmxazb4p****
InstanceIds	string	No	The ID of the instance. The value can be a JSON array that consists of up to 100 instance IDs. Separate the IDs with commas (,).	["i-bp67acfmxazb4p**", "i-bp67acfmxazb4p", … "i-bp67acfmxazb4p**"]
PageNumber	integer	No	The page number. Pages start from page 1. Default value: 1.	1
PageSize	integer	No	The number of entries per page. Valid values: 1 to 100. Default value: 10.	10
NextToken	string	No	The pagination token that is used in the next request to retrieve a new page of results. You do not need to specify this parameter for the first request. You must specify the token that is obtained from the previous query as the value of `NextToken`.	caeba0bbb2be03f84eb48b699f0a4883
MaxResults	integer	No	The maximum number of entries per page. Valid values: 1 to 100. Default value: If you do not specify this parameter or if you set this parameter to a value that is smaller than 10, the default value is 10. If you set this parameter to a value that is greater than 100, the default value is 100.	10
InnerIpAddresses	string	No	The internal IP addresses of instances located in the classic network. This parameter is valid when InstanceNetworkType is set to classic. The value can be a JSON array that consists of up to 100 IP addresses. Separate the IP addresses with commas (,).	["10.1.1.1", "10.1.2.1", … "10.1.10.1"]
PrivateIpAddresses	string	No	The private IP addresses of instances located in a VPC. This parameter is valid when InstanceNetworkType is set to vpc. The value can be a JSON array that consists of up to 100 IP addresses. Separate the IP addresses with commas (,).	["172.16.1.1", "172.16.2.1", … "172.16.10.1"]
PublicIpAddresses	string	No	The public IP addresses of instances. The value can be a JSON array that consists of up to 100 IP addresses. Separate the IP addresses with commas (,).	["42.1.1.", "42.1.2.", … "42.1.10.**"]
EipAddresses	string	No	The elastic IP addresses (EIPs) of instances. This parameter is valid when InstanceNetworkType is set to vpc. The value can be a JSON array that consists of up to 100 IP addresses. Separate the IP addresses with commas (,).	["42.1.1.", "42.1.2.", … "42.1.10.**"]
InstanceChargeType	string	No	The billing method of the instance. Valid values: PostPaid: pay-as-you-go PrePaid: subscription	PostPaid
InternetChargeType	string	No	The billing method for network usage. Valid values: PayByBandwidth PayByTraffic Note When the pay-by-traffic billing method is used for network usage, the maximum inbound and outbound bandwidths are used as the upper limits of bandwidths instead of guaranteed performance specifications. In scenarios in which demands exceed resource supplies, the maximum bandwidths may not be reached. If you want guaranteed bandwidths for your instance, use the pay-by-bandwidth billing method for network usage.	PayByTraffic
InstanceName	string	No	The name of the instance. Fuzzy search with asterisk (*) wildcard characters is supported.	Test
ImageId	string	No	The ID of the image.	m-bp67acfmxazb4p****
Status	string	No	The status of the instance. Valid values: Pending: The instance is being created. Running: The instance is running. Starting: The instance is being started. Stopping: The instance is being stopped. Stopped: The instance is stopped.	Running
LockReason	string	No	The reason why the instance is locked. Valid values: financial: The instance is locked due to overdue payments. security: The instance is locked due to security reasons. recycling: The preemptible instance is locked and pending release. dedicatedhostfinancial: The instance is locked due to overdue payments for the dedicated host. refunded: The instance is locked because a refund is made for the instance.	security
Filter.1.Key	string	No	The key of filter 1 used to query resources. Set the value to `CreationStartTime`. You can specify a time by setting both `Filter.1.Key` and `Filter.1.Value` to query resources that were created after the specified time.	CreationStartTime
Filter.2.Key	string	No	The key of filter 2 used to query resources. Set the value to `CreationEndTime`. You can specify a time by setting both `Filter.2.Key` and `Filter.2.Value` to query resources that were created before the specified time.	CreationEndTime
Filter.3.Key	string	No	The key of filter 3 used to query resources. Set the value to `ExpiredStartTime`. You can specify a time by setting both `Filter.3.Key` and `Filter.3.Value` to query resources that expire after the specified time.	ExpiredStartTime
Filter.4.Key	string	No	The key of filter 4 used to query resources. Set the value to `ExpiredEndTime`. You can specify a time by setting both `Filter.4.Key` and `Filter.4.Value` to query resources that expire before the specified time.	ExpiredEndTime
Filter.1.Value	string	No	The value of filter 1 used to query resources. Set the value to a time. If you specify this parameter, you must also specify `Filter.1.Key`. Specify the time in the ISO 8601 standard in the `yyyy-MM-ddTHH:mmZ` format. The time must be in UTC.	2017-12-05T22:40Z
Filter.2.Value	string	No	The value of filter 2 used to query resources. Set the value to a time. If you specify this parameter, you must also specify `Filter.2.Key`. Specify the time in the `yyyy-MM-ddTHH:mmZ` format. The time must be in UTC.	2017-12-06T22:40Z
Filter.3.Value	string	No	The value of filter 3 used to query resources. Set the value to a time. If you specify this parameter, you must also specify `Filter.3.Key`. Specify the time in the `yyyy-MM-ddTHH:mmZ` format. The time must be in UTC.	2017-12-07T22:40Z
Filter.4.Value	string	No	The value of filter 4 used to query resources. Set the value to a time. If you specify this parameter, you must also specify `Filter.4.Key`. Specify the time in the `yyyy-MM-ddTHH:mmZ` format. The time must be in UTC.	2017-12-08T22:40Z
IoOptimized	boolean	No	Specifies whether the instance is an I/O optimized instance. Valid values: true false	true
NeedSaleCycle	boolean	No	Note This parameter is in invitational preview and is not publicly available.	false
InstanceType	string	No	The instance type of the instance.	ecs.g5.large
InstanceTypeFamily	string	No	The instance family of the instance.	ecs.g5
KeyPairName	string	No	The name of the SSH key pair bound to the instance.	KeyPairNameTest
ResourceGroupId	string	No	The ID of the resource group to which the instance belongs. If this parameter is specified to query resources, up to 1,000 resources that belong to the specified resource group can be displayed in the response. Note Resources in the default resource group are displayed in the response regardless of how this parameter is set.	rg-bp67acfmxazb4p****
HpcClusterId	string	No	The ID of the high-performance computing (HPC) cluster to which the instance belongs.	hpc-bp67acfmxazb4p****
RdmaIpAddresses	string	No	The remote direct memory access (RDMA) IP addresses of the instance in the HPC cluster.	10.10.10.102
DryRun	boolean	No	Specifies whether to perform only a dry run, without performing the actual request. Valid values: true: performs only a dry run. The system checks the request for potential issues, including invalid AccessKey pairs, unauthorized RAM users, and missing parameter values. If the request fails the dry run, an error message is returned. If the request passes the dry run, the DryRunOperation error code is returned. false: performs a dry run and performs the actual request. If the request passes the dry run, a 2xx HTTP status code is returned and the operation is performed. Default value: false.	false
HttpEndpoint	string	No	Specifies whether the access channel is enabled for instance metadata. Valid values: enabled disabled Default value: enabled. Note For information about instance metadata, see Access instance metadata.	enabled
HttpTokens	string	No	Specifies whether the security hardening mode (IMDSv2) is forcefully used to access instance metadata. Valid values: optional: The security hardening mode (IMDSv2) is not forcefully used. required: The security hardening mode (IMDSv2) is forcefully used. After you set this parameter to required, you cannot access instance metadata in normal mode. Default value: optional. Note For information about modes of accessing instance metadata, see Access instance metadata.	optional
HttpPutResponseHopLimit	integer	No	Note This parameter is in invitational preview and is not publicly available.	0
Ipv6Address	array	No	The IPv6 addresses assigned to elastic network interfaces (ENIs).
	string	No	IPv6 address N of the ENI. Valid values of N: 1 to 100.	2408:4321:180:1701:94c7:bc38:3bfa:****
Tag	array<object>	No	The tags of the instance.
	object	No
key	string	No	The key of the tag. Note This parameter will be removed in the future. To ensure future compatibility, we recommend that you use `Tag.N.Key`.	keyTest
Key	string	No	The key of tag N of the instance. Valid values of N: 1 to 20. If you specify a single tag to query resources, up to 1,000 resources to which the tag is added are returned. If you specify multiple tags to query resources, up to 1,000 resources to which all specified tags are added are returned. To query more than 1,000 resources that have specified tags added, call the ListTagResources operation.	TestKey
Value	string	No	The value of tag N of the instance. Valid values of N: 1 to 20.	TestValue
value	string	No	The value of the tag. Note This parameter will be removed in the future. To ensure future compatibility, we recommend that you use `Tag.N.Value`.	valueTest
AdditionalAttributes	array	No	The additional attributes. Valid values of N: 1 to 20. Valid values: META_OPTIONS: instance metadata. DDH_CLUSTER: dedicated host cluster. NETWORK_PRIMARY_ENI_IP: secondary IP address associated with the primary ENI. CPU_OPTIONS_TOPOLOGY_TYPE: CPU topology type of the instance. CURRENT_OS_NVME_SUPPORTED: specifies whether the operating system supports access to disks over the Non-Volatile Memory Express (NVMe) protocol.
	string	No	The value of attribute N. Valid values of N: 1 to 20. Valid values: META_OPTIONS: instance metadata. DDH_CLUSTER: dedicated host cluster. NETWORK_PRIMARY_ENI_IP: secondary IP address associated with the primary ENI. CPU_OPTIONS_TOPOLOGY_TYPE: CPU topology type of the instance. CURRENT_OS_NVME_SUPPORTED: specifies whether the operating system supports access to disks over the NVMe protocol.	META_OPTIONS

Response parameters

Parameter	Type	Description	Example
	object
NextToken	string	A pagination token. It can be used in the next request to retrieve a new page of results. If NextToken is empty, no next page exists.	caeba0bbb2be03f84eb48b699f0a4883
PageSize	integer	The number of entries per page.	10
PageNumber	integer	The page number.	1
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCount	integer	The total number of instances queried. Note If you specify the `MaxResults` and `NextToken` request parameters to perform a paged query, the value of the `TotalCount` response parameter is invalid.	1
Instances	array<object>	Details about the queried instances.
Instance	object
CreationTime	string	The time when the instance was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC. For more information, see ISO 8601.	2017-12-10T04:04Z
SerialNumber	string	The serial number of the instance.	51d1353b-22bf-4567-a176-8b3e12e4****
Status	string	The status of the instance.	Running
DeploymentSetId	string	The ID of the deployment set to which the instance belongs.	ds-bp67acfmxazb4p****
KeyPairName	string	The name of the key pair.	testKeyPairName
SaleCycle	string	Note The parameter is removed.	month
SpotStrategy	string	The bidding policy for the pay-as-you-go instance. Valid values: NoSpot: The instance is a regular pay-as-you-go instance. SpotWithPriceLimit: The instance is a preemptible instance with a user-defined maximum hourly price. SpotAsPriceGo: The instance is a preemptible instance for which the market price is automatically used as the bid price. The market price can be up to the pay-as-you-go price.	NoSpot
DeviceAvailable	boolean	Indicates whether data disks can be attached to the instance. Valid values: true false	true
LocalStorageCapacity	long	The capacity of local disks attached to the instance. Unit: GiB.	1000
Description	string	The description of the instance.	testDescription
SpotDuration	integer	The protection period of the preemptible instance. Unit: hours. Valid values: 1: After a preemptible instance is created, Alibaba Cloud ensures that the instance is not automatically released within 1 hour. After the 1-hour protection period ends, the system compares the bid price with the market price and checks the resource inventory to determine whether to retain or release the instance. 0: After a preemptible instance is created, Alibaba Cloud does not ensure that the instance runs for 1 hour. The system compares the bid price with the market price and checks the resource inventory to determine whether to retain or release the instance. Alibaba Cloud sends an ECS system event to notify you 5 minutes before the instance is released. Preemptible instances are billed by second. We recommend that you specify a protection period based on your business requirements. Note This parameter is returned when SpotStrategy is set to SpotWithPriceLimit or SpotAsPriceGo.	1
InstanceNetworkType	string	The network type of the instance. Valid values: classic vpc	vpc
InstanceName	string	The instance name.	InstanceNameTest
OSNameEn	string	The English name of the operating system of the instance.	CentOS 7.4 64 bit
HpcClusterId	string	The ID of the HPC cluster to which the instance belongs.	hpc-bp67acfmxazb4p****
SpotPriceLimit	float	The maximum hourly price of the instance. The value can be accurate to three decimal places. This parameter is valid when SpotStrategy is set to SpotWithPriceLimit.	0.98
Memory	integer	The memory size. Unit: MiB.	16384
OSName	string	The name of the operating system of the instance.	CentOS 7.4 64-bit
DeploymentSetGroupNo	integer	The number of the deployment set group to which the instance belongs in a deployment set.	1
ImageId	string	The image ID of the instance.	m-bp67acfmxazb4p****
VlanId	string	The virtual LAN (VLAN) ID of the instance. Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.	10
ClusterId	string	The ID of the cluster to which the instance belongs. Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.	c-bp67acfmxazb4p****
GPUSpec	string	The category of GPUs for the instance type.	NVIDIA V100
AutoReleaseTime	string	The automatic release time of the pay-as-you-go instance.	2017-12-10T04:04Z
DeletionProtection	boolean	Indicates whether release protection is enabled for the instance. This parameter determines whether you can use the ECS console or call the DeleteInstance operation to release the instance. Valid values: true: Release protection is enabled for the instance. false: Release protection is disabled for the instance. Note This parameter is applicable only to pay-as-you-go instances. The release protection feature can protect instances against manual releases, but not against automatic releases.	false
StoppedMode	string	Indicates whether the instance continues to be billed after it is stopped. Valid values: KeepCharging: The instance is stopped in standard mode. Billing for the instance continues after the instance is stopped, and resources are retained for the instance. StopCharging: The instance is stopped in economical mode. Billing for some resources of the instance stops after the instance is stopped. When the instance is stopped, its resources such as vCPUs, memory, and public IP addresses are released. The instance may be unable to restart if some required resources are out of stock in the current region. Not-applicable: The instance does not support economical mode.	KeepCharging
GPUAmount	integer	The number of GPUs for the instance type.	4
HostName	string	The hostname of the instance.	testHostName
InstanceId	string	The instance ID.	i-bp67acfmxazb4p****
InternetMaxBandwidthOut	integer	The maximum outbound public bandwidth. Unit: Mbit/s.	5
InternetMaxBandwidthIn	integer	The maximum inbound public bandwidth. Unit: Mbit/s.	50
InstanceType	string	The instance type of the instance.	ecs.g5.large
InstanceChargeType	string	The billing method of the instance. Valid values: PrePaid: subscription PostPaid: pay-as-you-go	PostPaid
RegionId	string	The region ID of the instance.	cn-hangzhou
IoOptimized	boolean	Indicates whether the instance is an I/O optimized instance. Valid values: true false	true
StartTime	string	The time when the instance was last started. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC. For more information, see ISO 8601.	2017-12-10T04:04Z
Cpu	integer	The number of vCPUs.	8
LocalStorageAmount	integer	The number of local disks attached to the instance.	2
ExpiredTime	string	The expiration time of the instance. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC. For more information, see ISO 8601.	2017-12-10T04:04Z
ResourceGroupId	string	The ID of the resource group to which the instance belongs.	rg-bp67acfmxazb4p****
InternetChargeType	string	The billing method for network usage. Valid values: PayByBandwidth: pay-by-bandwidth PayByTraffic: pay-by-traffic	PayByTraffic
ZoneId	string	The zone ID of the instance.	cn-hangzhou-g
Recyclable	boolean	Indicates whether the instance can be recycled.	false
ISP	string	Note This parameter is in invitational preview and is not publicly available.	null
CreditSpecification	string	The performance mode of the burstable instance. Valid values: Standard: the standard mode. For more information, see the "Standard mode" section in Overview of burstable instances. Unlimited: the unlimited mode. For more information, see the "Unlimited mode" section in Overview of burstable instances.	Standard
InstanceTypeFamily	string	The instance family of the instance.	ecs.g5
OSType	string	The type of the operating system of the instance. Valid values: windows: Windows operating systems linux: Linux operating systems	linux
NetworkInterfaces	array<object>	The ENIs attached to the instance.
NetworkInterface	object	The ENI attached to the instance.
Type	string	The type of the ENI. Valid values: Primary Secondary	Primary
MacAddress	string	The MAC address of the ENI.	00:16:3e:32:b4:**
PrimaryIpAddress	string	The primary private IP address of the ENI.	172.17..*
NetworkInterfaceId	string	The ID of the ENI.	eni-2zeh9atclduxvf1z****
PrivateIpSets	array<object>	The private IP addresses of the ENI.
PrivateIpSet	object
PrivateIpAddress	string	The private IP address of the ENI.	172.17..
Primary	boolean	Indicates whether the IP address is the primary private IP address. Valid values: true false	true
PrivateDnsName	string	Note This parameter is in invitational preview and is not publicly available.	dnsTestName
Ipv6Sets	array<object>	The IPv6 addresses of the ENI. This parameter has a value only when `AdditionalAttributes.N` is set to `NETWORK_PRIMARY_ENI_IP`.
Ipv6Set	object
Ipv6Address	string	The IPv6 address of the ENI.	2408:4321:180:1701:94c7:bc38:3bfa:***
Ipv4PrefixSets	array<object>	The IPv4 prefixes of the ENI. This parameter has a value only when `AdditionalAttributes.N` is set to `NETWORK_PRIMARY_ENI_IP`.
Ipv4PrefixSet	object
Ipv4Prefix	string	The IPv4 prefix of the ENI.	47.122../19
Ipv6PrefixSets	array<object>	The IPv6 prefixes of the ENI. This parameter has a value only when `AdditionalAttributes.N` is set to `NETWORK_PRIMARY_ENI_IP`.
Ipv6PrefixSet	object
Ipv6Prefix	string	The IPv6 prefix of the ENI.	2001:1111::::/64
OperationLocks	array<object>	The reasons why the instance was locked.
LockReason	object
LockMsg	string	The message returned when the instance was locked.	The specified instance is locked due to financial reason.
LockReason	string	The reason why the instance was locked. Valid values: financial: The instance was locked due to overdue payments. security: The instance was locked due to security reasons. recycling: The preemptible instance was locked and pending release. dedicatedhostfinancial: The instance was locked due to overdue payments for the dedicated host. refunded: The instance was locked because a refund was made for the instance.	Recycling
Tags	array<object>	The tags of the instance.
Tag	object
TagValue	string	The tag value of the instance.	TestValue
TagKey	string	The tag key of the instance.	TestKey
RdmaIpAddress	array	The RDMA IP addresses of the instance in the HPC cluster.
IpAddress	string	The RDMA IP address of the instance in the HPC cluster.	10.10.10.102
SecurityGroupIds	array	The IDs of the security groups to which the instance belongs.
SecurityGroupId	string	The ID of the security group.	sg-bp67acfmxazb4p****
PublicIpAddress	array	The public IP addresses of the instance.
IpAddress	string	The public IP address of the instance.	121.40..
InnerIpAddress	array	The internal IP addresses of the instance located in the classic network.
IpAddress	string	The internal IP address of the instance located in the classic network.	10.170..
VpcAttributes	object	The VPC attributes of the instance.
VpcId	string	The ID of the VPC.	vpc-2zeuphj08tt7q3brd****
NatIpAddress	string	The NAT IP address of the instance. The NAT IP address is used by ECS instances in different VPCs for communication.	172.17..
VSwitchId	string	The ID of the vSwitch to which the instance is connected.	vsw-2zeh0r1pabwtg6wcs****
PrivateIpAddress	array	The private IP addresses of the instance.
IpAddress	string	The private IP address of the instance.	172.17..
EipAddress	object	Details about the EIP associated with the instance.
IsSupportUnassociate	boolean	Indicates whether the EIP can be disassociated.	true
InternetChargeType	string	The metering method of the EIP. Valid values: PayByBandwidth PayByTraffic	PayByTraffic
IpAddress	string	The EIP.	42.112..
Bandwidth	integer	The maximum public bandwidth of the EIP. Unit: Mbit/s.	5
AllocationId	string	The ID of the EIP.	eip-2ze88m67qx5z****
HibernationOptions	object	Note This parameter is in invitational preview and is not publicly available.
Configured	boolean	Note This parameter is in invitational preview and is not publicly available.	false
DedicatedHostAttribute	object	The information about the dedicated host. The value is an array that consists of DedicatedHostClusterId, DedicatedHostId, and DedicatedHostName.
DedicatedHostId	string	The ID of the dedicated host.	dh-bp67acfmxazb4p****
DedicatedHostName	string	The name of the dedicated host.	testDedicatedHostName
DedicatedHostClusterId	string	The ID of the dedicated host cluster.	dc-bp67acfmxazb4h****
EcsCapacityReservationAttr	object	Details about the capacity reservation associated with the instance.
CapacityReservationPreference	string	The preference of the capacity reservation.	cr-bp67acfmxazb4p****
CapacityReservationId	string	The ID of the capacity reservation.	cr-bp67acfmxazb4p****
DedicatedInstanceAttribute	object	The attributes of the instance on the dedicated host.
Affinity	string	Indicates whether the instance on the dedicated host is associated with the dedicated host. Valid values: default: The instance is not associated with the dedicated host. When the instance is restarted from economical mode, the instance may be automatically deployed on another dedicated host in the automatic deployment resource pool. host: The instance is associated with the dedicated host. When the instance is restarted from economical mode, the instance is still deployed on the original dedicated host.	default
Tenancy	string	Indicates whether the instance is hosted on a dedicated host. Valid values: default: The instance is not hosted on a dedicated host. host: The instance is hosted on a dedicated host.	default
CpuOptions	object	Details about the CPU options.
Numa	string	Note This parameter is deprecated.	2
CoreCount	integer	The number of physical CPU cores.	2
ThreadsPerCore	integer	The number of threads per CPU core.	4
TopologyType	string	The CPU topology type of the instance. Valid values: ContinuousCoreToHTMapping: Hyper-Threading (HT) continuous CPU topology DiscreteCoreToHTMapping: HT discrete CPU topology	ContinuousCoreToHTMapping
MetadataOptions	object	Details about the metadata options.
HttpEndpoint	string	Indicates whether the access channel is enabled for instance metadata. Valid values: enabled disabled	enabled
HttpPutResponseHopLimit	integer	Note This parameter is not publicly available.	0
HttpTokens	string	Indicates whether the security hardening mode (IMDSv2) is forcefully used to access instance metadata. Valid values: optional: The security hardening mode (IMDSv2) is not forcefully used. required: The security hardening mode (IMDSv2) is forcefully used.	optional
ImageOptions	object	The image options.
LoginAsNonRoot	boolean	Indicates whether the instance that uses the image supports logons of the ecs-user user. Valid values: true false	false
CurrentOSNVMeSupported	boolean	Indicates whether the operating system supports access to disks over the NVMe protocol. Valid values: true false Note This parameter is returned only if you specify CURRENT_OS_NVME_SUPPORTED in AdditionalAttributes in the request.	true
SpotInterruptionBehavior	string	The interruption mode of the preemptible instance when the system initiates a preemptible instance interruption operation. Valid values: Terminate: releases the preemptible instance. Stop: stops the instance in economical mode.	Terminate
PrivateDnsNameOptions	object	Note This parameter is in invitational preview and is not publicly available.
EnableInstanceIdDnsARecord	boolean	Note This parameter is in invitational preview and is not publicly available.	false
EnableInstanceIdDnsAAAARecord	boolean	Note This parameter is in invitational preview and is not publicly available.	false
EnableIpDnsARecord	boolean	Note This parameter is in invitational preview and is not publicly available.	true
EnableIpDnsPtrRecord	boolean	Note This parameter is in invitational preview and is not publicly available.	true
HostnameType	string	Note This parameter is in invitational preview and is not publicly available.	Custom

Examples

Sample success responses

JSONformat

{
  "NextToken": "caeba0bbb2be03f84eb48b699f0a4883",
  "PageSize": 10,
  "PageNumber": 1,
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "TotalCount": 1,
  "Instances": {
    "Instance": [
      {
        "CreationTime": "2017-12-10T04:04Z",
        "SerialNumber": "51d1353b-22bf-4567-a176-8b3e12e4****",
        "Status": "Running",
        "DeploymentSetId": "ds-bp67acfmxazb4p****",
        "KeyPairName": "testKeyPairName",
        "SaleCycle": "month",
        "SpotStrategy": "NoSpot",
        "DeviceAvailable": true,
        "LocalStorageCapacity": 1000,
        "Description": "testDescription",
        "SpotDuration": 1,
        "InstanceNetworkType": "vpc",
        "InstanceName": "InstanceNameTest",
        "OSNameEn": "CentOS  7.4 64 bit",
        "HpcClusterId": "hpc-bp67acfmxazb4p****",
        "SpotPriceLimit": 0.98,
        "Memory": 16384,
        "OSName": "CentOS 7.4 64-bit\n",
        "DeploymentSetGroupNo": 1,
        "ImageId": "m-bp67acfmxazb4p****",
        "VlanId": "10",
        "ClusterId": "c-bp67acfmxazb4p****",
        "GPUSpec": "NVIDIA V100",
        "AutoReleaseTime": "2017-12-10T04:04Z",
        "DeletionProtection": false,
        "StoppedMode": "KeepCharging",
        "GPUAmount": 4,
        "HostName": "testHostName",
        "InstanceId": "i-bp67acfmxazb4p****",
        "InternetMaxBandwidthOut": 5,
        "InternetMaxBandwidthIn": 50,
        "InstanceType": "ecs.g5.large",
        "InstanceChargeType": "PostPaid",
        "RegionId": "cn-hangzhou",
        "IoOptimized": true,
        "StartTime": "2017-12-10T04:04Z",
        "Cpu": 8,
        "LocalStorageAmount": 2,
        "ExpiredTime": "2017-12-10T04:04Z",
        "ResourceGroupId": "rg-bp67acfmxazb4p****",
        "InternetChargeType": "PayByTraffic",
        "ZoneId": "cn-hangzhou-g",
        "Recyclable": false,
        "ISP": "null",
        "CreditSpecification": "Standard",
        "InstanceTypeFamily": "ecs.g5",
        "OSType": "linux",
        "NetworkInterfaces": {
          "NetworkInterface": [
            {
              "Type": "Primary",
              "MacAddress": "00:16:3e:32:b4:**",
              "PrimaryIpAddress": "172.17.**.***",
              "NetworkInterfaceId": "eni-2zeh9atclduxvf1z****",
              "PrivateIpSets": {
                "PrivateIpSet": [
                  {
                    "PrivateIpAddress": "172.17.**.**",
                    "Primary": true,
                    "PrivateDnsName": "dnsTestName"
                  }
                ]
              },
              "Ipv6Sets": {
                "Ipv6Set": [
                  {
                    "Ipv6Address": "2408:4321:180:1701:94c7:bc38:3bfa:***"
                  }
                ]
              },
              "Ipv4PrefixSets": {
                "Ipv4PrefixSet": [
                  {
                    "Ipv4Prefix": "47.122.*.*/19"
                  }
                ]
              },
              "Ipv6PrefixSets": {
                "Ipv6PrefixSet": [
                  {
                    "Ipv6Prefix": "2001:1111:*:*::/64"
                  }
                ]
              }
            }
          ]
        },
        "OperationLocks": {
          "LockReason": [
            {
              "LockMsg": "The specified instance is locked due to financial reason.",
              "LockReason": "Recycling"
            }
          ]
        },
        "Tags": {
          "Tag": [
            {
              "TagValue": "TestValue",
              "TagKey": "TestKey"
            }
          ]
        },
        "RdmaIpAddress": {
          "IpAddress": [
            "10.10.10.102"
          ]
        },
        "SecurityGroupIds": {
          "SecurityGroupId": [
            "sg-bp67acfmxazb4p****"
          ]
        },
        "PublicIpAddress": {
          "IpAddress": [
            "121.40.**.**"
          ]
        },
        "InnerIpAddress": {
          "IpAddress": [
            "10.170.**.**"
          ]
        },
        "VpcAttributes": {
          "VpcId": "vpc-2zeuphj08tt7q3brd****",
          "NatIpAddress": "172.17.**.**",
          "VSwitchId": "vsw-2zeh0r1pabwtg6wcs****",
          "PrivateIpAddress": {
            "IpAddress": [
              "172.17.**.**"
            ]
          }
        },
        "EipAddress": {
          "IsSupportUnassociate": true,
          "InternetChargeType": "PayByTraffic",
          "IpAddress": "42.112.**.**",
          "Bandwidth": 5,
          "AllocationId": "eip-2ze88m67qx5z****"
        },
        "HibernationOptions": {
          "Configured": false
        },
        "DedicatedHostAttribute": {
          "DedicatedHostId": "dh-bp67acfmxazb4p****",
          "DedicatedHostName": "testDedicatedHostName",
          "DedicatedHostClusterId": "dc-bp67acfmxazb4h****"
        },
        "EcsCapacityReservationAttr": {
          "CapacityReservationPreference": "cr-bp67acfmxazb4p****",
          "CapacityReservationId": "cr-bp67acfmxazb4p****"
        },
        "DedicatedInstanceAttribute": {
          "Affinity": "default",
          "Tenancy": "default"
        },
        "CpuOptions": {
          "Numa": "2",
          "CoreCount": 2,
          "ThreadsPerCore": 4,
          "TopologyType": "ContinuousCoreToHTMapping"
        },
        "MetadataOptions": {
          "HttpEndpoint": "enabled",
          "HttpPutResponseHopLimit": 0,
          "HttpTokens": "optional"
        },
        "ImageOptions": {
          "LoginAsNonRoot": false,
          "CurrentOSNVMeSupported": true
        },
        "SpotInterruptionBehavior": "Terminate",
        "PrivateDnsNameOptions": {
          "EnableInstanceIdDnsARecord": false,
          "EnableInstanceIdDnsAAAARecord": false,
          "EnableIpDnsARecord": true,
          "EnableIpDnsPtrRecord": true,
          "HostnameType": "Custom"
        }
      }
    ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidTag.Mismatch	The specified Tag.n.Key and Tag.n.Value are not match.	The specified Tag.N.Key and Tag.N.Value parameters do not correspond to each other.
400	InvalidTagCount	The specified tags are beyond the permitted range.	The number of specified tags exceeds the upper limit.
400	InvalidHpcClusterId.NotFound	The specified HpcClusterId is not found.	The specified HpcClusterId parameter does not exist.
400	InvalidHpcClusterId.Creating	The specified HpcClusterId is creating.	The specified HPC cluster is being created.
400	InternalError	The request processing has failed due to some unknown error, exception or failure.	An internal error has occurred. Try again later.
404	InvalidInstanceChargeType.NotFound	The InstanceChargeType does not exist in our records.	The specified instance billing method does not exist.
404	InvalidInternetChargeType.ValueNotSupported	The specified InternetChargeType is not valid.	The specified InternetChargeType parameter is invalid.
404	InvalidLockReason.NotFound	The specified LockReason is not found.	The specified lockout reason does not exist.
404	InvalidFilterKey.NotFound	Invalid filter.%s.	-
404	InvalidFilterValue	Invalid filter.%s.	-
404	InvalidNetworkType.NotFound	The specified InstanceNetworkType is not found.	-
404	InvalidStatus.NotFound	The specified Status is not found.	The specified resource state does not exist.

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-10-30	The Error code has changed. The response structure of the API has changed	View Change Details
2024-08-08	The Error code has changed. The response structure of the API has changed	View Change Details
2023-12-14	The Error code has changed. The response structure of the API has changed	View Change Details
2023-12-11	The Error code has changed. The response structure of the API has changed	View Change Details
2021-12-13	The Error code has changed. The response structure of the API has changed	View Change Details
2021-05-20	The API operation is not deprecated.. The Error code has changed. The request parameters of the API has changed	View Change Details