Queries the details of one or more Elastic Compute Service (ECS) instances.
Operation description
-
You can specify multiple request parameters to be queried. Specified 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, it 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 the
DryRun
parameter in your request to check whether the empty list is caused by lack of permissions. -
When you call an API operation by using Alibaba Cloud CLI, you must specify request parameter values of different data types in required formats. For more information, see Parameter format overview.
-
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 call 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.
-
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) to which the instance belongs. | v-bp67acfmxazb4p**** |
VSwitchId | string | No | The ID of the vSwitch to which the instance is connected. | 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 IDs of instances. 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 number of the page to return. Pages start from page 1. Default value: 1. | 1 |
PageSize | integer | No | The number of entries to return on each page. Maximum value: 100. Default value: 10. | 10 |
NextToken | string | No | The query token. Set the value to the | caeba0bbb2be03f84eb48b699f0a4883 |
MaxResults | integer | No | The maximum number of entries to return on each page. Maximum value: 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 VPCs. 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 for network usage is used, the maximum inbound and outbound bandwidth values are used as upper limits of bandwidths instead of guaranteed performance specifications. In scenarios where demand outstrips resource supplies, these maximum bandwidth values may not be reached. If you want guaranteed bandwidths for your instances, use the pay-by-bandwidth billing method for network usage.
| PayByTraffic |
InstanceName | string | No | The name of the instance. Fuzzy search with the asterisk (*) wildcard characters is supported. | Test |
ImageId | string | No | The ID of the image. | m-bp67acfmxazb4p**** |
Status | string | No | The state 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 the | 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 the | 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 the | 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 the | 2017-12-08T22:40Z |
IoOptimized | boolean | No | Specifies whether the instance is I/O optimized. | true |
NeedSaleCycle | boolean | No | Note
This parameter is currently in invitational preview and unavailable for general users.
| 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 address of the HPC instance. | 10.10.10.102 |
DryRun | boolean | No | Specifies whether to check the validity of the request without actually making the request. Default value: false. Valid values:
| false |
HttpEndpoint | string | No | Specifies whether the access channel is enabled for instance metadata. Valid values:
Default value: enabled. Note
For more information about instance metadata, see Overview of ECS 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 more information about modes of accessing instance metadata, see Access mode of instance metadata.
| optional |
HttpPutResponseHopLimit | integer | No | Note
This parameter is currently in invitational preview and unavailable for general users.
| 0 |
Ipv6Address | array | No | IPv6 address N of the elastic network interface (ENI). You can specify multiple IPv6 addresses. Valid values of N: 1 to 100. | |
string | No | The IPv6 address of the elastic network interface(ENI). | 2408:4321:180:1701:94c7:bc38:3bfa:**** | |
Tag | object [] | No | The tags. | |
key | string | No | The key of tag N of the instance. Note
This parameter will be removed in the future. We recommend that you use the Tag.N.Key parameter to ensure future compatibility.
| keyTest |
Key | string | No | The key of tag N of the instance. Valid values of N: 1 to 20. If a single tag is specified to query resources, up to 1,000 resources that have this tag added can be displayed in the response. If multiple tags are specified to query resources, up to 1,000 resources that have all these tags added can be displayed in the response. 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 tag N of the instance. Note
This parameter will be removed in the future. We recommend that you use the Tag.N.Value parameter to ensure future compatibility.
| valueTest |
AdditionalAttributes | array | No | The value of attribute N. Valid values of N: 1 to 20. | |
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": "",
"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
}
]
},
"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
},
"SpotInterruptionBehavior": "Terminate"
}
]
}
}
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 | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
2023-12-14 | The Error code has changed. The response structure of the API has changed | see changesets | ||||||||||||
| ||||||||||||||
2023-12-11 | The Error code has changed. The response structure of the API has changed | see changesets | ||||||||||||
| ||||||||||||||
2021-12-13 | The Error code has changed. The response structure of the API has changed | see changesets | ||||||||||||
| ||||||||||||||
2021-05-20 | The API operation is not deprecated.. The Error code has changed. The request parameters of the API has changed | see changesets | ||||||||||||
|