Call the DescribeInstances operation to obtain instance information.

Considerations

When you call this operation, the number of instances queried via TagFilters.N.Key and TagFilters.N.Values.N can not exceed 1,000. If the number of instances to be queried exceeds 1,000, call the DesribeTags operation.

Debugging

API Explorer

You can initiate calls online through API Explorer without paying attention to the signature generation process and quickly obtain the call results.

Go to debug

Request parameters

Only the request parameters specific to this operation and some common parameters are listed below. For more information, refer to Common parameters.

Action stringrequired Sample value: DescribeInstances

The action that you want to perform. Value: DescribeInstances.

Version string required Sample value: 2020-04-01

The API version. Valid value: 2020-04-01.

AffinityGroupIds.N string[] Optional Sample value: AffinityGroupIds.1=affinityGroup-ydp80pygaoujldck****&AffinityGroupIds.2=affinityGroup-ydp7hq2wowujldck****

Affinity group ID. A maximum of 100 affinity group IDs is supported.

Argument - N: specifies the serial number of the affinity group.

Multiple IDs are divided with ampersands (&).

DedicatedHostClusterId string Optional Sample value: dc-ycle6b76kgv2wrsm****

The ID of the dedicated host cluster.

You can call the DescribeDedicatedHostClusters operation to query the ID of the dedicated host cluster.

DedicatedHostId string Optional Sample value: dh-3tigy72q3u3vj0x2****

The IDs of the dedicated hosts.

You can call the DescribeDedicatedHosts operation to query the list of dedicated hosts.

DeploymentSetGroupNumbers.N integer[] Optional Sample value: DeploymentSetGroupNumbers.1=1&DeploymentSetGroupNumbers.2=2

Use the group number of a deployment set to query instances within the corresponding deployment set group.

Argument - N: Indicates the serial number of the deployment set group. The value range is 1 to 7.

Multiple DeploymentSetGroupNumber values are divided with &.

DeploymentSetIds.N string[] Optional Sample value: DeploymentSetIds.1=dps-yc1o9aahks5m57nk****&DeploymentSetIds.2=dps-ybr1vulgy87grbt6****

Use the deployment set ID to query the instances within the corresponding deployment set.

Argument - N: specifies the serial number of the deployment set. Valid range: 1-100.

Separate multiple deployment set IDs with &.

EipAddresses.N string[] Optional Sample value: EipAddresses.1=12.XX.XX.89&EipAddresses.2=12.XX.XX.35

EIP address. A maximum of 100 EIP addresses is supported. You can call the DescribeEipAddresses operation to query EIP addresses.

Argument - N: specifies the serial number of the EIP address.

Multiple EIP addresses are divided with ampersands (&).

HpcClusterId string Optional Sample value: hpcCluster-3tean8ni5m3vj0wz****

When you query an HPC-optimized instance, you can specify the HPC Cluster ID for the instance.

InstanceChargeType string Optional Sample value: PostPaid

Billing method of the instance. Value:

PostPaid: pay-as-you-go

PrePaid: subscription

InstanceIds.N string[] Optional Sample value: InstanceIds.1=i-3ti9101aju3vj0******&InstanceIds.2=i-3tiegs1y963vj0******

The instance ID. A maximum of 100 instance IDs are supported.

Parameter - N: specifies the serial number of the instance.

Separate multiple instance IDs with ampersands (&).

InstanceName string Optional Sample value: instance-test

The name of the instance. Fuzzy queries with keywords are supported.

InstanceTypeFamilies.N string[] Optional Sample value: InstanceTypeFamilies.1=ecs.g2i&InstanceTypeFamilies.2=ecs.c2i

Filter instances by instance family. A maximum of 100 instance families are supported.

Parameter - N: specifies the serial number of the instance.

Multiple instance families are divided with &.

InstanceTypeIds.N string[] Optional Sample value: InstanceTypeIds.1=ecs.g2i.2xlarge&InstanceTypeIds.2=ecs.c2i.2xlarge

Filter instances by instance type. A maximum of 100 instance types are supported.

Parameter - N: specifies the serial number of the instance.

Multiple instance types are separated by &.

Ipv6Addresses.N string[] Optional Sample value: Ipv6Addresses.1=2406:d440:103:5f00:a4a2:cbe2:efa0:****

The IPv6 address of the instance.

Argument - N: specifies the serial number of the IPv6 address. Valid range: 1-100.

Multiple network interfaces are separated by &.

tip

The feature of assigning IPv6 addresses to network interfaces is currently in Beta. Only accounts that have completed enterprise authentication can apply for a trial. If you need a trial, contact your account manager.

KeyPairName string Optional Sample value: kp-test-123

Name of the key pair.

MaxResults integer Optional Sample value: 10

The number of entries returned on each page in a pagination query.

Maximum value: 100

Default value: 10

NextToken string Optional Sample value: --

Pagination token marking the query position. Omit this parameter for initial API requests. In the next query, set the NextToken parameter to the value returned by the previous API call.

PrimaryIpAddress string Optional Sample value: 172.16.XX.XX

Private IP address of the instance, such as the IP address of the primary network interface or secondary network interface.

ProjectName string Optional Sample value: project_a

The project to which the resource belongs. A resource can only belong to one project.

Only letters, digits, underscores (_), hyphens (-), and dots (.) are allowed.

The length is limited to 64 characters.

ScheduledInstanceId string Optional Sample value: esi-ycmfqs85zrm0tqlp****

ESI order ID.

You can call DescribeScheduledInstances operation to query the ESI order ID.

Status string Optional Sample value: RUNNING

The status of the instance. Value:

CREATING: The instance is being created.

RUNNING: The instance is running.

Stopping: The instance is being stopped.

Stopped: The instance is stopped.

Rebooting: The instance is being restarted.

Starting: The instance is being started.

Rebuilding: The instance is being reinstalled.

Resizing: The instance is being resized.

Error: Error occurred.

Deleting: The instance is being deleted.

TagFilters.N.Key string[] Optional Sample value: TagFilters.1.Key=k1

The specified tag key when querying resources based on tags.

Parameter - N: specifies the serial number of the tag key. Valid range: 1–10.

Separate multiple tag keys with ampersands (&).

Tag keys must be unique.

TagFilters.N.Values.N string[] Optional Sample value: TagFilters.1.Values.1=v1&TagFilters.1.Values.2=v2

The tag value specified when resources are queried based on tags.

The first N: specifies the serial number of the tag key. Valid range: 1–10.

The second N specifies the serial number of the tag value. Valid range: 1-3. That is, you can query up to three tag values of the same tag key.

Separate multiple tag values with &.

tip

To pass in this parameter, pass in TagFilters.N.Key first.

If you do not pass in this parameter, all tag values under the same tag key are queried.

If you specify an empty string, you query tags with an empty tag value.

VpcId string Optional Sample value: vpc-3thbinq64t4bwbha****

VPC ID.

You can call the DescribeVpcs operation to query VPCs that meet the condition.

ZoneId string Optional Sample value: cn-beijing-a

The ID of the availability zone where the instance is located.

You can call the DescribeZones operation to query the availability zones in the same region.

Response parameters

Only the response parameters specific to this operation are listed below. For more information, refer to Response structure.

Instances object[] Sample value: --

The information about instances that meet the conditions.

AffinityGroupId string Sample value: affinityGroup-ydp80pygaoujldck****

Affinity group ID.

CpuOptions object Sample value: --

CPU configuration detail.

TopologyType string Sample value: DiscreteCoreToHTMapping

The CPU topology mode. Valid values:

ContinuousCoreToHTMapping: HT continuous mode.

DiscreteCoreToHTMapping: HT discrete mode.

CoreCount integer Sample value: 4

The number of CPU physical cores

ThreadsPerCore integer Sample value: 2

Number of threads per CPU core. It indicates whether hyper-threading is enabled for the CPU.

Valid values:

1: Disable hyper-threading

2: Enable hyper-threading

vCPU count = number of physical CPU cores * number of threads per core

Cpus integer Sample value: 4

Number of CPUs.

CreatedAt string Sample value: 2021-06-28T18:29:38+08:00

The creation time.

DeletionProtection boolean Sample value: true

The attribute of instance deletion protection. Specify whether to delete the instance through the console or API. Valid values:

true: Enable instance deletion protection.

false: Disable instance deletion protection.

DeploymentSetGroupNumber integer Sample value: 2

Serial number of the deployment set group.

DeploymentSetId string Sample value: dps-yc1o9aahks5m57nk****

The ID of deployment set to which the instance belongs.

Description string Sample value: ECS instance for testing.

Instance description.

EipAddress object Sample value: --

The list of EIPs associated with the instance.

AllocationId string Sample value: eip-2749d8a20h4hs7fap8taa****

The ID of an EIP.

IpAddress string Sample value: 101.126.XX.XX

EIP address.

ElasticScheduledInstanceType string Sample value: NoEsi

The ESI type. Value:

NoEsi: non-ESI type.

Esi: ESI type.

Segmented: ESI-Segmented

EnableJumboFrame boolean Sample value: false

Whether jumbo frames are enabled for the instance. Valid values:

true: NAT Traversal is enabled.

false: Disabled.

ExpiredAt string Sample value: 2200-01-01T00:00:00+08:00

Expiration time of the instance.

This argument can be returned only when InstanceChargeType is set to PrePaid.

Hostname string Sample value: instance-host-name

Instance hostname.

HpcClusterId string Sample value: hpcCluster-3tean8ni5m3vj0******

The HPC cluster ID.

ImageId string Sample value: image-3tefr6wgx63vj0******

The image ID.

InstanceChargeType string Sample value: PostPaid

Billing method of the instance. Value:

PostPaid: pay-as-you-go

PrePaid: subscription

InstanceId string Sample value: i-3ti9101aju3vj0******

The instance ID.

InstanceName string Sample value: instance-test

The instance name.

InstanceTypeId string Sample value: ecs.c2i.xlarge

Instance type.

KeyPairId string Sample value: kp-3tgh3ifp8j44kd******

Key pair ID.

KeyPairName string Sample value: kp-test-123

The name of the key pair.

LocalVolumes object[] Sample value: --

The local volume configuration of the instance.

Count integer Sample value: 4

The number of local volumes mounted on the instance.

Size integer Sample value: 200

The capacity of one local volume mounted on the instance. Unit: GiB

VolumeType string Sample value: LOCAL_SSD

The local volume type. Valid values:

LOCAL_SSD: local SSD

LOCAL_HDD: local HDD

MemorySize integer Sample value: 32768

Memory size. Unit: MiB.

MetadataOptions object Sample value: --

Instance metadata option set.

HttpTokens string Sample value: optional

The access mode of instance metadata. You can set whether to enable the security hardening mode. Valid value:

optional: not mandatory (Normal Mode and Security Hardening Mode)

required: mandatory (Security Hardening Mode).

tip

For information on how to view metadata and the available metadata items, refer to Viewing instance metadata.

NetworkInterfaces object[] Sample value: --

Information about the network interface mounted to the instance.

Ipv6Addresses string[] Sample value: ["2408::153:3921:XX:XX:7b12:1c5f", "2408:4008:2cf:XX:XX:dd1e:2a22:5ddf"]

IPv6 address of the network interface.

MacAddress string Sample value: 00:16:3e:5b:** :**

MAC address.

NetworkInterfaceId string Sample value: eni-3tiu4lmhwq4e8i******

Network interface ID.

PrimaryIpAddress string Sample value: 172.16.XX.XX

Private IP address.

SecurityGroupIds string[] Sample value: ["sg-mj48avnqyio05smt1a******","sg-3cj59ih2v9hj46c6rr******"]

ID of the security group associated with the network interface.

SubnetId string Sample value: subnet-3tisodmzai4e8i******

Subnet ID.

Type string Sample value: primary

The network interface attribute. Value:

primary: the primary network interface

secondary: the secondary network interface

VpcId string Sample value: vpc-3thbinq64t4bwb******

VPC ID.

OsName string Sample value: CentOS 7.6 64位

The operating system of the image.

OsType string Sample value: Linux

OS type:

Linux

Windows

Placement object Sample value: --

Information of the ECS instance deployed on a dedicated host.

Affinity string Sample value: Default

For ECS instances in economical mode, some resources are released after instances are stopped. This argument is used to check whether the instances are still deployed on the original host when restarted. Valid values:

Host: When instances in economical mode are restarted, they are still deployed on the original host.

Default: When the instance with Economical Mode enabled restarts, it will be preferentially migrated to a host that supports automatic deployment. If resources on the host that supports automatic deployment are insufficient, the instance restarts on the original host.

DedicatedHostClusterId string Sample value: dc-ycle6b76kgv2wrsm****

The ID of dedicated host cluster where the instance is deployed.

DedicatedHostId string Sample value: dh-bp67acfmxazb4p****

The ID of the dedicated host on which the instance is deployed.

Tenancy string Sample value: Default

Whether to create an instance on a dedicated host. Value:

Default (default): Create a regular ECS instance.

Host: Create an ECS instance deployed on a dedicated host. If you do not specify DedicatedHostId, the instance is deployed on the dedicated host selected automatically by the system.

ProjectName string Sample value: project_a

The project to which the resource belongs. A resource can only belong to one project.

Only letters, digits, underscores (_), hyphens (-), and dots (.) are allowed.

The length is limited to 64 characters.

RdmaIpAddresses string[] Sample value: ["198.18.xx.xx","198.18.xx.xx"]

When HPC-optimized instances are queried, the RDMA IP addresses of each network interface are returned in a list format.

RdmaNetworkInterfaceDetails object[] Sample value: --

When you query HPC-optimized instances, information about each network interface is returned in list format.

This interface is in Beta. To request a trial, please contact the customer manager.

Gateway string Sample value: 26.xx.xx.46

The gateway address.

Ip string Sample value: 26.xx.xx.2

The IP address.

Mask string Sample value: 255.xx.xx.254

The subnet mask.

SwitchName string Sample value: HB****.VEGS0-0-01

The switch name.

SwitchPort string Sample value: ethernet1a

The switch port.

ScheduledInstanceId string Sample value: esi-ycmfqs85zrm0tqlp****

ESI order ID.

SpotPriceLimit float Sample value: 0.78

The maximum hourly price for spot instances. A maximum of three decimal places for the price is supported.

This argument can be returned only when SpotStrategy is set to SpotWithPriceLimit.

SpotStrategy string Sample value: NoSpot

The spot strategy for the instance billed in pay-as-you-go mode. Value:

NoSpot (default): Instances are billed in pay-as-you-go mode.

SpotAsPriceGo: The system automatically bids based on the current market price for the spot instance.

SpotWithPriceLimit: Spot instance with a price limit.

Status string Sample value: RUNNING

Instance state.

StoppedMode string Sample value: KeepCharging

Whether the instance enables economical mode. Value:

KeepCharging: Normal Mode. In this mode, after you stop the instance, charges continue and relevant resources are retained.

StopCharging: Economical Mode. For more information, refer to Economical mode for pay-as-you-go instances.

NotApplicable: indicates that this instance does not support economical mode.

Tags object[] Sample value: --

Information about tags associated with resources.

Key string Sample value: k1

Tag key of the instance.

Value string Sample value: v1

The tag value of the instance.

UpdatedAt string Sample value: 2021-06-29T18:11:46+08:00

Update time.

Uuid string Sample value: 4f35e8f7-f549-5c55-9531-5f43ca78****

The unique identifier of the instance. This information does not change with the instance status.

Volumes object[] Sample value: --

Information about the volume mounted to the instance.

VolumeId string Sample value: vol-3wbz8gzti84g6no9****

Volume ID.

VpcId string Sample value: vpc-3thbinq64t4bwb******

VPC ID.

ZoneId string Sample value: cn-beijing-a

The availability zone ID.

NextToken string Sample value: bHpwdXJja2RxemU1eG5sb3NzdGcW1-RCEq******

The pagination token returned by this call. If this value is empty, the current page is the last page.

Sample request

Sample response

Error codes

The table below lists the business-related error codes of the operation. For more information, refer to Common error codes.

Status code	Error codes	Error message	Description
400	InvalidArgument	The specified argument is invalid.	The specified parameter is invalid.
400	InvalidCpuOptionsCoreCount.Malformed	The specified cpu options core count is malformed.	The specified CoreCount argument is invalid.
400	InvalidCpuOptionsThreadsPerCore.Malformed	The specified cpu options threads per core is malformed.	The specified ThreadsPerCore argument is invalid.
400	InvalidTagFilterKey.Malformed	The specified TagFilterKey is malformed.	The format of the specified tag key for query is invalid.
400	InvalidTagFilterValue.Malformed	The specified TagFilterValue is malformed.	The format of the specified tag value for query is invalid.
400	LimitExceeded.MaximumAffinityGroupIds	The number of specified AffinityGroupIds exceeds the maximum limit.	The specified number of AffinityGroupIds exceeds the maximum limit.
400	LimitExceeded.MaximumDeploymentSetGroupNumbers	You've reached the limit on the number of DeploymentSetGroupNumbers that you can set.	The specified DeploymentSetGroupNumbers exceed the maximum limit.
400	LimitExceeded.MaximumDeploymentSetIds	You've reached the limit on the number of DeploymentSetIds that you can set.	The number of specified deployment sets exceeds the upper limit.
400	LimitExceeded.MaximumEipAddresses	The number of specified EipAddresses exceeds the maximum limit.	The number of specified EipAddresses exceeds the maximum limit.
400	LimitExceeded.MaximumInstanceIds	You've reached the limit on the number of InstanceIds that you can set.	The specified number of instance IDs exceeds the upper limit.
400	LimitExceeded.MaximumInstanceTypeFamilies	You've reached the limit on the number of InstanceTypeFamilies that you can set.	The specified number of InstanceTypeFamilies exceeds the maximum limit.
400	LimitExceeded.MaximumInstanceTypeIds	You've reached the limit on the number of InstanceTypeIds that you can set.	The specified number of InstanceTypeIds exceeds the maximum limit.
400	LimitExceeded.MaximumIpv6Addresses	The number of specified Ipv6Addresses exceeds the maximum limit.	The number of specified Ipv6Addresses exceeds the maximum limit.
400	LimitExceeded.MaximumTagFilterKeys	You've reached the limit on the number of TagFilterKeys that you can set.	The specified query tag key is out of range.
400	LimitExceeded.MaximumTagFilterResults	You've reached the limit on the number of resources that you can describe by TagFilters.	The number of resources filtered by tag exceeds the upper limit.
400	LimitExceeded.MaximumTagFilterValues	You've reached the limit on the number of TagFilterValues that you can set.	The value of the specified tag for query exceeds the value range.
400	LimitExceeded.PrimaryIpAddresses	You've reached the limit on the number of PrimaryIpAddresses that you can set.	The number of specified IP addresses exceeds the maximum limit.
404	InvalidActionOrVersion	Could not find operation %s for version %s.	The requested API does not exist.
404	InvalidProject.NotFound	The specified Project does not exist.	The specified project does not exist.
409	InvalidTagFilterKey.Conflict	The specified TagFilterKey already exists.	The specified tag filter key already exists.
429	FlowLimitExceeded	You've reached the limit on request rate of resources.	You have exceeded the rate limit for resource requests.
500	InternalError	An internal error has occurred.	An internal error occurred. Try again. If multiple attempts fail, submit a ticket.

Elastic Compute Service