You can call this operation to query details of one or more instances.

Description

  • You can specify multiple request parameters. Specified parameters have logical AND relations. Only the parameters that are specified are included in the filtering conditions. However, if InstanceIds is set to an empty JSON array, it is regarded as an effective filtering condition and an empty result is returned.
  • If you are using a RAM user or RAM role, an empty list is returned when the user or the role does not have the permission to call this operation. You can add the DryRun parameter in your request to determine whether the empty list is caused by the lack of permission.

When you call an API operation through Alibaba Cloud CLI, specify request parameter values of different data types in required formats. For more information, see CLI parameter format.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String No DescribeInstances

The operation that you want to perform. Set the value to DescribeInstances.
RegionId String Yes cn-hangzhou

The region ID of the instance. You can call the DescribeRegions operation to query the most recent region list.

InstanceIds String No ["i-bp67acfmxazb4ph***", "i-bp67acfmxazb4pi***", … "i-bp67acfmxazb4pj***"]

The IDs of the instances. It can be a JSON array that consists of multiple instance IDs. Separate multiple instance IDs with commas (,). A maximum of 100 instance IDs can be entered.

VpcId String No v-bp67acfmxazb4ph***

The ID of the VPC to which the instance to be queried belongs.
VSwitchId String No vsw-bp67acfmxazb4ph***

The ID of the VSwitch.
InstanceNetworkType String No vpc

The network type of the instance. Valid values:

  • classic: classic network
  • vpc: VPC
SecurityGroupId String No sg-bp67acfmxazb4ph***

The ID of the security group to which the instance belongs.
ZoneId String No cn-hangzhou-b

The zone ID of the instance.
PageNumber Integer No 1

The number of the page to return.

Pages start from page 1.

Default value: 1
PageSize Integer No 10

The number of entries to return on each page.

Valid values: 1 to 100

Default value: 10
InnerIpAddresses String No ["10.1.1.1", "10.1.2.1", … "10.1.10.1"]

The internal IP addresses of the classic network-type instance. This parameter takes effect when InstanceNetworkType is set to classic. The value can be a JSON array that consists of multiple IP addresses. Separate multiple IP addresses with commas (,). A maximum of 100 IP addresses can be entered.

PrivateIpAddresses String No ["172.16.1.1", "172.16.2.1", … "172.16.10.1"]

The private IP addresses of the VPC-type instance. This parameter takes effect when InstanceNetworkType is set to vpc. The value can be a JSON array that consists of multiple IP addresses. Separate multiple IP addresses with commas (,). A maximum of 100 IP addresses can be entered.

PublicIpAddresses String No ["42.1.1. **", "42.1.2. **", … "42.1.10. **"]

The public IP addresses of the instance. This parameter takes effect when InstanceNetworkType is set to classic. The value can be a JSON array that consists of multiple IP addresses. Separate multiple IP addresses with commas (,). A maximum of 100 IP addresses can be entered.

EipAddresses String No ["42.1.1. **", "42.1.2. **", … "42.1.10. **"]

The EIPs of the instance. This parameter takes effect when InstanceNetworkType is set to vpc. The value can be a JSON array that consists of multiple IP addresses. Separate multiple IP addresses with commas (,). A maximum of 100 IP addresses can be entered at a time.

InstanceChargeType String No PostPaid

The billing method of the instance. Valid values:

  • PostPaid: pay-as-you-go
  • PrePaid: subscription
InternetChargeType String No PayByTraffic

The billing method for network usage. Valid values:

  • PayByBandwidth
  • PayByTraffic
InstanceName String No *Joshua

The name of the instance. Fuzzy search with the wildcard * is supported.

ImageId String No m-bp67acfmxazb4ph***

The ID of the image.
Status String No Running

The status of the instance. Valid values:

  • Running
  • Starting
  • Stopping
  • Stopped
LockReason String No security

The reason why the instance is locked.
IoOptimized Boolean No true

Specifies whether the instance is I/O optimized.
Tag.N.Key String No FinanceDept

The key of tag N of the instance. Valid values of N: 1 to 20.
Tag.N.Value String No FinanceDeptJoshua

The value of tag N of the instance. Valid values of N: 1 to 20.
Tag.N.key String No FinanceDept

The key of the tag.

Note This parameter will be removed in the future. We recommend that you use the Tag.N.Key parameter to ensure compatibility.
Tag.N.value String No FinanceDeptJoshua

The value of the tag.

Note This parameter will be removed in the future. We recommend that you use the Tag.N.Value parameter to ensure compatibility.
InstanceType String No ecs.g5.large

The type of the instance.
InstanceTypeFamily String No ecs.g5

The instance family of the instance.
KeyPairName String No FinanceJoshua

The name of the SSH key pair for the instance.
ResourceGroupId String No rg-bp67acfmxazb4ph***

The ID of the resource group to which the instance belongs.
HpcClusterId String No hpc-bp67acfmxazb4ph***

The ID of the HPC cluster to which the instance belongs.
RdmaIpAddresses String No 10.10.10.102

The RDMA IP addresses of the HPC instance.
DryRun Boolean No false

Specifies whether to check the request only. Default value: false. Valid values:

  • true: The request is checked but instances are not queried. Check items include whether your AccessKey pair is valid, whether RAM users are authorized, and whether the required parameters are specified. If the check fails, the corresponding error message is returned. If the check succeeds, the DryRunOperation error code is returned.
  • false: The request is checked, and a 2XX HTTP status code is returned and instances are queried if the check succeeds.

Response parameters

Parameter Type Example Description
RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.
TotalCount Integer 58

The total number of instances.
PageNumber Integer 1

The page number of the returned page.
PageSize Integer 1

The number of entries returned per page.
Instances Array

An array of the returned information of instances.
InstanceId String i-bp67acfmxazb4ph***

The ID of the instance.
InstanceName String FinanceJoshua

The name of the instance.
Description String description

The description of the instance.
ImageId String m-bp67acfmxazb4ph***

The ID of the image that the instance is running.
OSName String CentOS 7.4 64-bit

The name of the operating system for the instance.
OSNameEn String CentOS 7.4 64-bit

The English name of the operating system for the instance.
OSType String linux

The operating system type of the instance, including Windows Server and Linux. Valid values:

  • windows
  • linux
RegionId String cn-hangzhou

The region ID of the instance.
ZoneId String cn-hangzhou-g

The zone ID of the instance.
ClusterId String c-bp67acfmxazb4ph***

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 compatibility.
InstanceType String ecs.g5.large

The type of the instance.
Cpu Integer 8

The number of vCPUs.
Memory Integer 1024

The memory size of the instance. Unit: MiB.
HostName String JoshuaHost

The host name of the instance.
DeploymentSetId String ds-bp67acfmxazb4ph***

The ID of the deployment set.
Status String Running

The state of the instance.
SerialNumber String 51d1353b-22bf-4567-a176-8b3e12e43***

The serial number of the instance.
InternetChargeType String PayByTraffic

The billing method for network usage. Valid values:

  • PayByBandwidth
  • PayByTraffic
InternetMaxBandwidthIn Integer 100

The maximum inbound public bandwidth. Unit: Mbit/s.
InternetMaxBandwidthOut Integer 5

The maximum outbound public bandwidth. Unit: Mbit/s.
VlanId String 10

The VLAN ID of the instance.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure compatibility.
CreationTime String 2017-12-10T04:04Z

The time when the instance was created.
StartTime String 2017-12-10T04:04Z

The start time of the preemption mode for the instance.
InstanceNetworkType String vpc

The network type of the instance. Valid values:

  • classic
  • vpc
InstanceChargeType String PostPaid

The billing method of the instance. Valid values:

  • PrePaid: subscription
  • PostPaid: pay-as-you-go
SaleCycle String month

The billing cycle of the instance.
ExpiredTime String 2017-12-10T04:04Z

The expiration time of the instance. The time follows the ISO 8601standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.

AutoReleaseTime String 2017-12-10T04:04Z

The automatic release time of the pay-as-you-go instance.
IoOptimized Boolean True

Indicates whether the instance is I/O optimized.
DeviceAvailable Boolean True

Indicates whether data disks can be attached to the instance.
InstanceTypeFamily String ecs.g5

The instance family.
LocalStorageCapacity Long 1000

The capacity of a local disk attached to the instance.
LocalStorageAmount Integer 2

The number of local disks attached to the instance.
GPUAmount Integer 4

The number of GPUs for the instance type.
GPUSpec String NVIDIA V100

The category of GPUs for the instance type.
SpotStrategy String NoSpot

The preemption policy for the preemptible instance. Valid values:

  • NoSpot: the regular pay-as-you-go instance.
  • SpotWithPriceLimit: applies to preemptible instances with a maximum hourly price.
  • SpotAsPriceGo: applies to pay-as-you-go instances priced at the market price at the time of purchase.
SpotPriceLimit Float 0.98

The maximum hourly price for the instance. It can be accurate to three decimal places. This parameter takes effect when SpotStrategy is set to SpotWithPriceLimit.

ResourceGroupId String rg-bp67acfmxazb4ph***

The ID of the resource group to which the instance belongs.
KeyPairName String FinanceJoshua

The name of the key pair.
Recyclable Boolean false

Indicates whether the instance can be recycled.
HpcClusterId String hpc-bp67acfmxazb4ph***

The ID of the HPC cluster to which the instance belongs.
StoppedMode String KeepCharging

Indicates whether the instance continues to be billed after it is stopped. Valid values:

  • KeepCharging: The billing of the instance continues after it is stopped, and resources in stock are reserved for the instance.
  • StopCharging: The billing of the instance stops after it is stopped. After the instance is stopped, its resources such as vCPUs, memory, and public IP address are released. You may be unable to restart the instance if some types of resources are out of stock in the current region.
  • Not-applicable: The No Fees for Stopped Instances (VPC-connected) feature is not applicable to the instance.
CreditSpecification String Standard

The running mode of the burstable instance. Valid values:

  • Standard: The standard mode. For more information, see the standard mode section of Burstable instances.
  • Unlimited: The unlimited mode. For more information, see the Unlimited mode section of Burstable instances.
DeletionProtection Boolean false

The release protection attribute of the instance. It indicates whether you can use the ECS console or call the DeleteInstance operation to release the instance.

  • true: enables release protection.
  • false: disables release protection.
Note This parameter is applicable only to pay-as-you-go instances. It can only protect against manual releases but not against automatic releases.
NetworkInterfaces Array

The ENIs of the instance.
NetworkInterfaceId String eni-2zeh9atclduxvf1zc***

The ID of the ENI.
MacAddress String 00:16:3e:32:b4:**

The MAC address of the ENI.
PrimaryIpAddress String 172.17.**. ***

The private IP address of the primary ENI.
OperationLocks Array

The reason why the instance was locked.
LockReason String Recycling

The type of 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 is pending for release.
  • dedicatedhostfinancial: The ECS instance was locked due to overdue payments on the dedicated host.
LockMsg String The specified instance is locked due to financial reason.

The message returned when the instanced was locked.
Tags Array

The tags of the instance.
TagKey String FinanceDept

The tag key of the instance.
TagValue String FinanceDept.Joshua

The tag value of the instance.
SecurityGroupIds List sg-bp67acfmxazb4ph***

The IDs of the security groups to which the instance belongs.
PublicIpAddress List 121.40.61.***

The public IP addresses of the instance.
InnerIpAddress List 10.170.**. ***

The internal IP addresses of the instance.
RdmaIpAddress List 10.10.10.102

The RDMA IP addresses of the HPC instance.
VpcAttributes Struct

The VPC attributes of the instance.
VpcId String vpc-2zeuphj08tt7q3brdb***

The ID of the VPC to which the instance belongs.
VSwitchId String vsw-2zeh0r1pabwtg6wcss***

The ID of the VSwitch.
NatIpAddress String 172.17.**. ***

The IP address of the instance. It is used by ECS instances in different VPCs for communication.

PrivateIpAddress List 172.17.**. ***

The private IP addresses of the instance.
EipAddress Struct

The information of the EIP bound to the instance.
AllocationId String i-bp67acfmxazb4ph***

The ID of the instance bound to the EIP.
IpAddress String 42.112.17.**

The EIP.
Bandwidth Integer 5

The peak value for public bandwidth of the EIP. Unit: Mbit/s.
InternetChargeType String PayByTraffic

The billing method of the EIP.
IsSupportUnassociate Boolean true

Indicates whether the EIP can be unbound.
DedicatedHostAttribute Struct

The host attribute array that consists of the DedicatedHostId and DedicatedHostName values.

DedicatedHostId String dh-bp67acfmxazb4ph***

The ID of the dedicated host.
DedicatedHostName String FinanceDept

The name of the dedicated host.
EcsCapacityReservationAttr Struct

The capacity reservation attribute of the ECS instance.
CapacityReservationId String cr-bp67acfmxazb4ph***

The ID of the reserved instance.
CapacityReservationPreference String cr-bp67acfmxazb4ph***

The preference of capacity reservation.
DedicatedInstanceAttribute Struct

The attribute of the instance on a dedicated host.
Tenancy String default

Indicates whether the host that hosts the instance is a dedicated host. Valid values:

  • default: The host is not a dedicated host.
  • host: The host is a dedicated host.
Affinity String default

Indicates whether the instance on a dedicated host is associated with the dedicated host. Valid values:

  • default: The instance is not associated with the dedicated host. With the No Fees for Stopped Instances (VPC-connected) feature enabled, when the instance is restarted after being stopped, it may be deployed to another dedicated host in the automatic deployment resource pool.
  • host: The instance is associated with the dedicated host. With the No Fees for Stopped Instances (VPC-connected) feature enabled, when the instance is restarted after being stopped, it still resides on the original dedicated host.
CpuOptions Struct

The configuration details of CPU.
CoreCount Integer 2

The number of CPU cores.
ThreadsPerCore Integer 4

The number of threads per core.
Numa String 2

The number of threads allocated. Example: 2.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=DescribeInstances
&RegionId=cn-hangzhou
&PageSize=1
PageNumber=1
&<Common request parameters>

Sample success responses

XML format 

<DescribeInstancesResponse>
    <PageNumber>1</PageNumber>
    <TotalCount>6</TotalCount>
    <PageSize>10</PageSize>
    <RequestId>8EF01A45-FFFA-497B-B5C3-1DE1B74DB32D</RequestId>
    <Instances>
        <Instance>
            <InnerIpAddress></InnerIpAddress>
            <ImageId>ubuntu_16_0402_64_20G_alibase_20170818.vhd</ImageId>
            <InstanceTypeFamily>ecs.g5</InstanceTypeFamily>
            <VlanId></VlanId>
            <NetworkInterfaces>
                <NetworkInterface>
                    <MacAddress>00:16:3e:32:b4:dc</MacAddress>
                    <PrimaryIpAddress>172.17.XX.XXX</PrimaryIpAddress>
                    <NetworkInterfaceId>eni-2zeh9atclduxvf1zc***</NetworkInterfaceId>
                </NetworkInterface>
            </NetworkInterfaces>
            <InstanceId>XXXXXXXXXXX</InstanceId>
            <EipAddress>
                <IpAddress></IpAddress>
                <AllocationId></AllocationId>
                <InternetChargeType></InternetChargeType>
            </EipAddress>
            <InternetMaxBandwidthIn>1000</InternetMaxBandwidthIn>
            <ZoneId>cn-beijing-e</ZoneId>
            <InternetChargeType>PayByBandwidth</InternetChargeType>
            <SpotStrategy>NoSpot</SpotStrategy>
            <StoppedMode>Not-applicable</StoppedMode>
            <SerialNumber>d9bd1cdc-624d-4736-9da5-2ba2f741a***</SerialNumber>
            <IoOptimized>true</IoOptimized>
            <Memory>8192</Memory>
            <Cpu>2</Cpu>
            <VpcAttributes>
                <NatIpAddress></NatIpAddress>
                <PrivateIpAddress>
                    <IpAddress>172.17.XX.XXX</IpAddress>
                </PrivateIpAddress>
                <VSwitchId>vsw-2zeh0r1pabwtg6wcss***</VSwitchId>
                <VpcId>vpc-2zeuphj08tt7q3brdb***</VpcId>
            </VpcAttributes>
            <InternetMaxBandwidthOut>1</InternetMaxBandwidthOut>
            <SecurityGroupIds>
                <SecurityGroupId>sg-2ze21r9qb638hvtrv***</SecurityGroupId>
            </SecurityGroupIds>
            <SpotPriceLimit>0.0</SpotPriceLimit>
            <SaleCycle>Week</SaleCycle>
            <AutoReleaseTime></AutoReleaseTime>
            <InstanceName>ECS-BUY-2017-57-10</InstanceName>
            <Description></Description>
            <ResourceGroupId></ResourceGroupId>
            <OSType>linux</OSType>
            <OSName>Ubuntu 16.04 64</OSName>
            <InstanceNetworkType>vpc</InstanceNetworkType>
            <PublicIpAddress>
                <IpAddress>47.94.XX.XX</IpAddress>
            </PublicIpAddress>
            <HostName>iZ2zeh9atclduxvf1zxu***</HostName>
            <InstanceType>ecs.g5.large</InstanceType>
            <CreationTime>2017-12-10T04:04Z</CreationTime>
            <Tags>
                <Tag>
                    <TagValue>fqwfew</TagValue>
                    <TagKey>fefqe</TagKey>
                </Tag>
                <Tag>
                    <TagValue>weqfwq</TagValue>
                    <TagKey>fqewfwqewf</TagKey>
                </Tag>
                <Tag>
                    <TagValue>ewqffeqw</TagValue>
                    <TagKey>fqfwewfqw</TagKey>
                </Tag>
            </Tags>
            <Status>Running</Status>
            <ClusterId></ClusterId>
            <Recyclable>false</Recyclable>
            <RegionId>cn-beijing</RegionId>
            <GPUSpec></GPUSpec>
            <OperationLocks></OperationLocks>
            <GPUAmount>0</GPUAmount>
            <InstanceChargeType>PrePaid</InstanceChargeType>
            <ExpiredTime>2017-12-17T16:00Z</ExpiredTime>
        </Instance>
    </Instances>
</DescribeInstancesResponse>

JSON format 

{
	"PageNumber": 1,
	"TotalCount":58,
	"PageSize": 1,
	"RequestId":"97935DF1-0289-4AA2-9DD1-72377838B16B",
	"Instances": {
		"Instance": [
			{
				"ImageId": "centos_7_06_64_20G_alibase_20190711.vhd",
				"VlanId": "",
				"EipAddress": {
					"IpAddress": "",
					"AllocationId": "",
					"InternetChargeType": ""
				},
				"ZoneId": "cn-hangzhou-f",
				"IoOptimized": true,
				"SerialNumber": "51d1353b-22bf-4567-a176-8b3e12e43***",
				 "Cpu": 2,
				"Memory": 8192,
				"DeviceAvailable": true,
				"SecurityGroupIds": {
					"SecurityGroupId": [
						"sg-bp17zljqpohu6j2io***"
					]
				},
				"SaleCycle": "",
				"AutoReleaseTime": "",
				"ResourceGroupId": "",
				"OSType": "linux",
				"OSName":"CentOS 7.6 64-bit",
				"InstanceNetworkType": "classic",
				"HostName": "iZbp1j4i2jdf3owlhebz***",
				"CreationTime": "2019-11-11T08:35Z",
				"Tags": {
					"Tag": [
						{
							"TagValue": "asg-bp1d8uuut40f4qc40***",
							"TagKey": "acs:autoscaling:scalingGroupId"
						},
						{
							"TagValue": "ESS",
							"TagKey": "ESS"
						}
					]
				},
				"EcsCapacityReservationAttr": {
					"CapacityReservationPreference": "none",
					"CapacityReservationId": ""
				},
				"RegionId": "cn-hangzhou",
				"DeletionProtection": false,
				"OperationLocks": {
					"LockReason": []
				},
				"ExpiredTime": "2099-12-31T15:59Z",
				"CpuOptions": {
					"Numa": "",
					"ThreadsPerCore": 2,
					 "CoreCount": 1
				},
				"InnerIpAddress": {
					"IpAddress": [
						"10.80.61.42"
					]
				},
				"InstanceTypeFamily": "ecs.mn4",
				 "InstanceId": "i-bp1j4i2jdf3owlheb***",
				 "InternetMaxBandwidthIn": 500,
				"CreditSpecification": "",
				"InternetChargeType": "PayByTraffic",
				5"SpotStrategy": "NoSpot",
				"StoppedMode": "Not-applicable",
				"InternetMaxBandwidthOut": 1,
				"VpcAttributes": {
					 "NatIpAddress": "",
					"PrivateIpAddress": {
						"IpAddress": []
					},
					"VSwitchId": "",
					 "VpcId": ""
				},
				"SpotPriceLimit": 0,
				 "StartTime": "2019-11-11T08:35Z",
				 "InstanceName": "ECS-asg-MyFirstScalingGroup",
				"Description": "ECS",
				 "OSNameEn": "CentOS  7.6 64 bit",
				"PublicIpAddress": {
					"IpAddress": [
						"121.40.77.XXX"
					]
				},
				"InstanceType": "ecs.mn4.large",
				"Status": "Running",
				 "Recyclable": false,
				"ClusterId": "",
				"GPUSpec": "",
				"InstanceChargeType": "PostPaid",
				"GPUAmount": 0,
				"DedicatedHostAttribute": {
					"DedicatedHostId": "",
					"DedicatedHostName": ""
				},
				"DedicatedInstanceAttribute": {
					"Affinity": "",
					"Tenancy": ""
				},
				"DeploymentSetId": ""
			}
		]
	}
}

Error codes

HTTP status code Error code Error message Description
404 InvalidInstanceChargeType.NotFound The InstanceChargeType does not exist in our records The error message returned because the specified billing method for network usage does not exist.
404 InvalidInternetChargeType.ValueNotSupported The specified InternetChargeType is not valid The error message returned because the specified billing method for network usage is invalid.
404 InvalidLockReason.NotFound The specified LockReason is not found The error message returned because the specified type of the reason why the instance was locked does not exist.
404 InvalidFilterKey.NotFound The error message returned because the specified start time or end time is invalid.
404 InvalidFilterValue The error message returned because the format of the specified time is invalid.
404 InvalidNetworkType.NotFound The specified InstanceNetworkType is not found The error message returned because the specified network type of the instance does not exist.
404 InvalidStatus.NotFound The specified Status is not found The error message returned because the specified resource status does not exist.
400 InvalidTag.Mismatch The specified Tag.n.Key and Tag.n.Value are not match. The error message returned because the specified Tag.N.Key parameter does not correspond to the specified Tag.N.Value parameter.
400 InvalidTagCount The specified tags are beyond the permitted range. The error message returned because the number of specified tags exceeds the upper limit.
400 InvalidHpcClusterId.NotFound The specified HpcClusterId is not found. The error message returned because the specified HPC cluster ID does not exist.
400 InvalidHpcClusterId.Creating The specified HpcClusterId is creating. The error message returned because the specified HPC cluster is being created.

For a list of error codes, visit the API Error Center.