DescribeInstances

Last Updated: May 03, 2018

Description

Describes the details of one or more instances.

The request parameters are filters used for describing a specific list of results. The filters use the AND logic, which matches a set of resources by specific criteria, such as IDs, billing methods, or tags. A parameter with null value does not play the role of a filter. However, if the InstanceIds parameter is a null JSON array InstanceIds=[], it is regarded as a valid filter and the responded value is null.

Request parameters

Name Type Required Description
Action String Yes The name of this interface. Value: DescribeInstances.
RegionId String Yes Region ID. For more information, see Regions and zones, or call DescribeRegions to obtain the latest region list.
ZoneId String No Zone ID. For more information, see Regions and zones, or call DescribeZones to obtain the latest zone list.
InstanceIds String No The instance ID. The value can contain an array of up to 100 instance IDs. The IDs are displayed in the format of ["i-xxxxxxxxx", "i-yyyyyyyyy", … "i-zzzzzzzzz"] and are separated by commas (,).
InstanceType String No Instance type. For more information, see Instance Type Family, or call DescribeInstanceTypes to obtain the latest type list.
InstanceTypeFamily String No Instance type family. For more information, see Instance Type Family, or call DescribeInstanceTypeFamilies to obtain the latest type family list.
InstanceNetworkType String No Network type of the instance. Optional values:
  • classic: Classic network
  • vpc: VPC
VpcId String No VPC ID. This parameter is effective if NetworkType=vpc.
VSwitchId String No VSwitch ID. This parameter is effective if NetworkType=vpc.
PrivateIpAddresses String No List of private IP addresses of VPC-Connected instances. This parameter is effective when NetworkType=vpc. The value can contain an array of up to 100 IP addresses. The IP addresses are displayed in the format of ["172.16.1.1", "172.16.2.1", … "172.16.10.1"] and are separated by commas (,).
InnerIpAddresses String No List of private IP addresses of classic network-connected instances. This parameter is effective when NetworkType=classic. The value can contain an array of up to 100 IP addresses. The IP addresses are displayed in the format of ["10.16.1.1", "10.16.2.1", … "10.16.10.1"] and are separated by commas (,).
PublicIpAddresses String No List of public IP addresses of classic network-connected instances. This parameter is effective when NetworkType=classic. The value can contain an array of up to 100 IP addresses. The IP addresses are displayed in the format of ["42.1.1.1", "42.1.2.1", … "42.1.10.1"] and are separated by commas (,).
SecurityGroupId String No Security group to which the instances belong.
InstanceChargeType String No Billing method of the instances. Optional values:
  • PrePaid: Subscribed instances
  • PostPaid: Pay-As-You-Go instances
InternetChargeType String No Billing method of the instance bandwidth. Optional value: PayByTraffic.
InstanceName String No Instance name. You can use wildcard for fuzzy search.
ImageId String No Image ID.
Status String No Status of the instances. Optional values:
  • Running
  • Starting
  • Stopping
  • Stopped
IoOptimized Boolean No Whether an instance is I/O optimized. Optional values: True | False.
Tag.n.Key String No The tag key of the instances. The valid range of n is [1, 5].
Once you use this parameter, it cannot be a null string.
Tag.n.Value String No The tag value of the instances. The valid range of n is [1, 5]. Once you use this parameter, it can be a null string.
PageNumber Integer No Displays the instances on several pages.
Start value: 1.
Default value: 1.
PageSize Integer No The maximum entries on a page.
Maximum value: 100.
Default value: 10.

Response 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.

Examples

Request example

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

Response Example

XML format

  1. <DescribeInstancesResponse>
  2. <PageNumber>1</PageNumber>
  3. <TotalCount>6</TotalCount>
  4. <PageSize>10</PageSize>
  5. <RequestId>8EF01A45-FFFA-497B-B5C3-1DE1B74DB32D</RequestId>
  6. <Instances>
  7. <Instance>
  8. <InnerIpAddress/>
  9. <ImageId>ubuntu_16_0402_64_20G_alibase_20170818.vhd</ImageId>
  10. <InstanceTypeFamily>ecs.g5</InstanceTypeFamily>
  11. <VlanId/>
  12. <NetworkInterfaces>
  13. <NetworkInterface>
  14. <MacAddress>00:16:3e:32:b4:dc</MacAddress>
  15. <PrimaryIpAddress>172.17.XX.XXX</PrimaryIpAddress>
  16. <NetworkInterfaceId>eni-2zeh9atclduxvf1zcyal</NetworkInterfaceId>
  17. </NetworkInterface>
  18. </NetworkInterfaces>
  19. <InstanceId>XXXXXXXXXXX</InstanceId>
  20. <EipAddress>
  21. <IpAddress/>
  22. <AllocationId/>
  23. <InternetChargeType/>
  24. </EipAddress>
  25. <InternetMaxBandwidthIn>1000</InternetMaxBandwidthIn>
  26. <ZoneId>cn-beijing-e</ZoneId>
  27. <InternetChargeType>PayByBandwidth</InternetChargeType>
  28. <SpotStrategy>NoSpot</SpotStrategy>
  29. <StoppedMode>Not-applicable</StoppedMode>
  30. <SerialNumber>d9bd1cdc-624d-4736-9da5-2ba2f741a304</SerialNumber>
  31. <IoOptimized>true</IoOptimized>
  32. <Memory>8192</Memory>
  33. <Cpu>2</Cpu>
  34. <VpcAttributes>
  35. <NatIpAddress/>
  36. <PrivateIpAddress>
  37. <IpAddress>172.17.XX.XXX</IpAddress>
  38. </PrivateIpAddress>
  39. <VSwitchId>vsw-2zeh0r1pabwtg6wcssgca</VSwitchId>
  40. <VpcId>vpc-2zeuphj08tt7q3brdb36x</VpcId>
  41. </VpcAttributes>
  42. <InternetMaxBandwidthOut>1</InternetMaxBandwidthOut>
  43. <DeviceAvailable>true</DeviceAvailable>
  44. <SecurityGroupIds>
  45. <SecurityGroupId>sg-2ze21r9qb638hvtrvsus</SecurityGroupId>
  46. </SecurityGroupIds>
  47. <SpotPriceLimit>0.0</SpotPriceLimit>
  48. <SaleCycle>Week</SaleCycle>
  49. <AutoReleaseTime/>
  50. <InstanceName>ECS-BUY-2017-57-10</InstanceName>
  51. <Description/>
  52. <ResourceGroupId/>
  53. <OSType>linux</OSType>
  54. <OSName>Ubuntu 16.04 64</OSName>
  55. <InstanceNetworkType>vpc</InstanceNetworkType>
  56. <PublicIpAddress>
  57. <IpAddress>47.94.XX.XX</IpAddress>
  58. </PublicIpAddress>
  59. <HostName>iZ2zeh9atclduxvf1zxuylZ</HostName>
  60. <InstanceType>ecs.g5.large</InstanceType>
  61. <CreationTime>2017-12-10T04:04Z</CreationTime>
  62. <Tags>
  63. <Tag>
  64. <TagValue>fqwfew</TagValue>
  65. <TagKey>fefqe</TagKey>
  66. </Tag>
  67. <Tag>
  68. <TagValue>weqfwq</TagValue>
  69. <TagKey>fqewfwqewf</TagKey>
  70. </Tag>
  71. <Tag>
  72. <TagValue>ewqffeqw</TagValue>
  73. <TagKey>fqfwewfqw</TagKey>
  74. </Tag>
  75. </Tags>
  76. <Status>Running</Status>
  77. <ClusterId/>
  78. <Recyclable>false</Recyclable>
  79. <RegionId>cn-beijing</RegionId>
  80. <GPUSpec/>
  81. <OperationLocks/>
  82. <GPUAmount>0</GPUAmount>
  83. <InstanceChargeType>PrePaid</InstanceChargeType>
  84. <ExpiredTime>2017-12-17T16:00Z</ExpiredTime>
  85. </Instance>
  86. </Instances>
  87. </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.XX.XXX"
  14. ]
  15. },
  16. "InstanceChargeType": "PostPaid",
  17. "InstanceId": "XXXXXXXXX",
  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.XX.XXX"
  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. }

Error codes

Error code Error message HTTP status code Meaning
InvalidTag.Mismatch The specified Tag.n.Key and Tag.n.Value are not match. 400 The specified Tag.n.Key and Tag.n.Value must be a matched key-value.
InvalidTagCount The specified tags are beyond the permitted range. 400 The number of the specified tags cannot exceed five.
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.
Thank you! We've received your feedback.