DescribeInstances

Last Updated: Sep 12, 2017

Description

This API queries details of all instances.

  • This API does not verify the dependency between parameters. The return results are the intersection of all criteria.
  • A parameter with the value of null does not play the role of a filter. However, if the InstanceIds parameter is an empty JSON array (that is, []), it is regarded as a valid filter and the returned value is null.

Request parameters

Name Type Required Description
Action String Yes Required parameter, value: DescribeInstances.
RegionId String Yes Region
VpcId String No VPC ID
VSwitchId String No Switch ID
ZoneId String No Zone ID
InstanceIds String No List of instance IDs
It is a formatted JSON Array: [“i-xxxxxxxxx”, “i-yyyyyyyyy”, … “i-zzzzzzzzz”], which contains a maximum of 100 IDs separated by commas.
InstanceType String No Instance type
InstanceTypeFamily String No Instance type family
InstanceNetworkType String No Network type of the instance
PrivateIpAddresses String No List of private IP addresses of VPC type instances. This parameter is effective when NetworkType is VPC.
It is a JSON Array: [“172.16.1.1”, “172.16.2.1”, … “172.16.10.1”], which contains a maximum of 100 IP addresses separated by commas.
InnerIpAddresses String No List of private IP addresses of Classic type instances. This parameter is effective when NetworkType is Classic.
It is a JSON Array: [“10.1.1.1”, “10.1.2.1”, … “10.1.10.1”], which contains a maximum of 100 IP addresses separated by commas.
PublicIpAddresses String No List of public IP addresses of Classic type instances. This parameter is effective when NetworkType is Classic.
It is a JSON Array: [“42.1.1.1”, “42.1.2.1”, … “42.1.10.1”], which contains a maximum of 100 IP addresses separated by commas.
SecurityGroupId String No Security group to which an instance belongs.
InstanceChargeType String No Payment option for an instance.
  • PrePaid: applicable to subscribed instances
  • Value: PostPaid, applicable to Pay-As-You-Go instances
InternetChargeType String No Internet billing method; optional values: PayByBandwidth | PayByTraffic. The value is PayByBandwidth for a prepaid instance.
  • PayByTraffic
  • PayByBandwidth
InstanceName String No Instance name
ImageId String No Image ID
Status String No Status of an instance. Options include:
  • Running
  • Starting
  • Stopping
  • Stopped
DeviceAvailable String No Whether disks can be attached to an instance.
True | False
IoOptimized String No Whether an instance is I/O optimized.
True | False
Tag.n.Key String No Tag key, n starting from 1, with the maximum value of 5.
The parameter value cannot be a null string.
Tag.n.Value String No Tag value, n starting from 1, with the maximum value of 5.
The parameter value can be a null string.
PageNumber Integer No Page number of the instance status list. The start value is 1 and the default value is 1.
PageSize Integer No Number of lines per page in the case of querying by page. The maximum value is 100, and the default value is 10.

Return parameters

Name Type Description
TotalCount Integer Total number of instances.
PageNumber Integer Page number of the instance list.
PageSize Integer Number of lines per page set during input.
Instances InstanceAttributesType Array format composed of InstanceAttributesType, which returns instance information.

Error codes

Error code Description HTTP status code Meaning
InvalidInstanceChargeType.NotFound The InstanceChargeType does not exist in our records. 404 The specified InstanceChargeType does not exist.
InvalidInternetChargeType.ValueNotSupported The specified InternetChargeType is not valid. 404 The specified InternetChargeType does not exist.
InvalidNetworkType.NotFound The specified InstanceNetworkType is not found. 404 The specified InstanceNetworkType does not exist.
InvalidStatus.NotFound The specified Status is not found. 404 The specified Status does not exist.
InvalidTag.Mismatch The specified Tag.n.Key and Tag.n.Value are not match. 400 The specified Tag.n.Key and Tag.n.Value do not match.
InvalidTagCount The specified tags are beyond the permitted range. 400 The number of the specified tags exceeds five.

Example

Request example

  1. https://ecs.aliyuncs.com/?Action=DescribeInstances
  2. &RegionId=cn-hangzhou
  3. &<Public Request Parameters>

Return Example

XML format

  1. <DescribeInstancesResponse>
  2. <CreationTime>2014-09-21T01:12:35Z</CreationTime>
  3. <DeviceAvailable>true</DeviceAvailable>
  4. <Description></Description>
  5. <EipAddress>
  6. <AllocationId></AllocationId>
  7. <InternetChargeType></InternetChargeType>
  8. <IpAddress></IpAddress>
  9. </EipAddress>
  10. <ExpiredTime>2011-09-08T16:00Z</ExpiredTime>
  11. <HostName>iZ25skktcp4Z</HostName>
  12. <ImageId>ubuntu1404_64_20G_aliaegis_20140703.vhd</ImageId>
  13. <InnerIpAddress></InnerIpAddress>
  14. <InstanceChargeType>PostPaid</InstanceChargeType>
  15. <IpAddress></IpAddress>
  16. <InstanceId>i-25skktcp4</InstanceId>
  17. <InstanceName>iZ25skktcp4Z</InstanceName>
  18. <InstanceNetworkType>vpc</InstanceNetworkType>
  19. <InstanceType>ecs.t1.xsmall</InstanceType>
  20. <InternetChargeType></InternetChargeType>
  21. <InternetMaxBandwidthIn>-1</InternetMaxBandwidthIn>
  22. <InternetMaxBandwidthOut></InternetMaxBandwidthOut>
  23. <IoOptimized>false</IoOptimized>
  24. <OperationLocks>
  25. <LockReason></LockReason>
  26. </OperationLocks>
  27. <PublicIpAddress>
  28. <IpAddress></IpAddress>
  29. </PublicIpAddress>
  30. <RegionId>cn-beijing</RegionId>
  31. <SecurityGroupIds>
  32. <SecurityGroupId>sg-25am0n4q0</SecurityGroupId>
  33. </SecurityGroupIds>
  34. <SerialNumber>51d1353b-22bf-4567-a176-8b3e12e43135</SerialNumber>
  35. <Status>Running</Status>
  36. <VlanId></VlanId>
  37. <VpcAttributes>
  38. <NatIpAddress>10.175.68.212</NatIpAddress>
  39. <PrivateIpAddress>
  40. <IpAddress>192.168.2.3</IpAddress>
  41. </PrivateIpAddress>
  42. <VSwitchId>vsw-25gbsqby3</VSwitchId>
  43. <VpcId>vpc-25onv3oi4</VpcId>
  44. </VpcAttributes>
  45. <ZoneId>cn-beijing-a</ZoneId>
  46. </DescribeInstancesResponse>

JSON format

  1. {
  2. "Instances": {
  3. "Instance": [
  4. {
  5. "CreationTime": "2015-07-27T07:08Z",
  6. "DeviceAvailable": true,
  7. "EipAddress": {},
  8. "ExpiredTime": "2011-09-08T16:00Z",
  9. "HostName": "iZ94t3s0jxkZ",
  10. "ImageId": "centos6u5_64_20G_aliaegis_20150130.vhd",
  11. "InnerIpAddress": {
  12. "IpAddress": [
  13. "10.170.106.80"
  14. ]
  15. },
  16. "InstanceChargeType": "PostPaid",
  17. "InstanceId": "i-94t3s0jxk",
  18. "InstanceName": "dd\u6027\u80fd\u6d4b\u8bd5",
  19. "InstanceNetworkType": "classic",
  20. "InstanceType": "ecs.s2.large",
  21. "InternetChargeType": "PayByTraffic",
  22. "InternetMaxBandwidthIn": -1,
  23. "InternetMaxBandwidthOut": 1,
  24. "IoOptimized": false,
  25. "OperationLocks": {
  26. "LockReason": []
  27. },
  28. "PublicIpAddress": {
  29. "IpAddress": [
  30. "120.25.13.106"
  31. ]
  32. },
  33. "RegionId": "cn-shenzhen",
  34. "SecurityGroupIds": {
  35. "SecurityGroupId": [
  36. "sg-94kd0cyg0"
  37. ]
  38. },
  39. "SerialNumber": "51d1353b-22bf-4567-a176-8b3e12e43135",
  40. "Status": "Running",
  41. "VpcAttributes": {
  42. "PrivateIpAddress": {
  43. "IpAddress": []
  44. }
  45. },
  46. "ZoneId": "cn-shenzhen-a"
  47. }
  48. ]
  49. },
  50. "PageNumber": 1,
  51. "PageSize": 10,
  52. "RequestId": "14A07460-EBE7-47CA-9757-12CC4761D47A",
  53. "TotalCount": 1
  54. }
Thank you! We've received your feedback.