Queries the information about Elastic Compute Service (ECS) instances.
Operation description
Usage notes
-
You can specify multiple request parameters to filter query results. Specified request parameters have logical AND relations. Only the specified parameters are included in the filter conditions. However, if InstanceIds is set to an empty JSON array, this parameter is regarded as a valid filter condition and an empty result is returned.
-
If you are using a Resource Access Management (RAM) user or RAM role that does not have the permissions to call this operation, an empty list is returned. You can include
DryRun
in your request to check whether the empty list is caused by lack of permissions. -
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.
-
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, set
MaxResults
to specify the maximum number of entries to return in the call. The return value ofNextToken
is a pagination token, which can be used in the next request to retrieve a new page of results. When you call the DescribeInstances operation to retrieve a new page of results, setNextToken
to theNextToken
value returned in the previous call and setMaxResults
to specify the maximum number of entries to return in this call. - Method 2: Use
PageSize
to specify the number of entries to return on each page and then usePageNumber
to specify the number of the page to return.
You can use only one of the preceding methods. If a large number of entries are to be returned, we recommend that you use Method 1. When
MaxResults
orNextToken
is specified, thePageSize
andPageNumber
request parameters do not take effect and theTotalCount
response parameter is invalid. - Method 1: During a paged query, when you call the DescribeInstances operation to retrieve the first page of results, set
Debugging
Authorization information
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:
| 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 | caeba0bbb2be03f84eb48b699f0a4883 |
MaxResults | integer | No | The maximum number of entries per page. Valid values: 1 to 100. Default value:
| 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 |
InternetChargeType | string | No | The billing method for network usage. Valid values:
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:
| Running |
LockReason | string | No | The reason why the instance is locked. Valid values:
| security |
Filter.1.Key | string | No | The key of filter 1 used to query resources. Set the value to | CreationStartTime |
Filter.2.Key | string | No | The key of filter 2 used to query resources. Set the value to | CreationEndTime |
Filter.3.Key | string | No | The key of filter 3 used to query resources. Set the value to | ExpiredStartTime |
Filter.4.Key | string | No | The key of filter 4 used to query resources. Set the value to | 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 | 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 | 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 | 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 | 2017-12-08T22:40Z |
IoOptimized | boolean | No | Specifies whether the instance is an I/O optimized instance. Valid values:
| 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:
Default value: false. | false |
HttpEndpoint | string | No | Specifies whether the access channel is enabled for instance metadata. Valid values:
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:
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:
| |
string | No | The value of attribute N. Valid values of N: 1 to 20. Valid values:
| META_OPTIONS |
Response parameters
Examples
Sample success responses
JSON
format
{
"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 |