Call DescribeInstances to query instance details - ENS - Alibaba Cloud - ENS

Retrieves details of one or more instances.

Operation description

API call rate: 800 requests/second.
Single-user API call rate: 100 requests/second.
Request parameters act as filters and are combined with a logical AND. Unspecified parameters are ignored. However, an empty JSON array for InstanceIds is a valid filter that returns an empty result set.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

ens:DescribeInstances

list

*Instance

acs:ens:*:{#accountId}:instance/{#InstanceId}

None

Request parameters

Parameter	Type	Required	Description	Example
EnsRegionId	string	No	The ID of the region.	cn-beijing-cmcc
InstanceId	string	No	The ID of the instance.	i-5iqczfxps7csjrxeca****
EnsRegionIds	string	No	A JSON array of node IDs. You can specify a maximum of 100 IDs.	["cn-suzhou-telecom","cn-chengdu-telecom"]
InstanceIds	string	No	A JSON array of instance IDs. You can specify a maximum of 100 IDs.	["i-5iqczfxps7csjrxeca07**", "i-5iqczfxps7csjrxeca07**"]
InstanceName	string	No	The name of the instance.	TestName
ImageId	string	No	The ID of the image.	centos_6_08_64_20G_alibase_****
PageNumber	integer	No	The page number. Pages start from 1. Default value: 1.	1
PageSize	string	No	The number of entries to return on each page. Maximum value: 100. Default value: 10.	10
Status	string	No	The status of the instance. Valid values: Running: The instance is running. Stopped: The instance is stopped. Expired: The instance has expired.	Running
OrderByParams	string	No	The sorting criteria, in JSON format. You can sort the results by instance name, expiration time, node ID, or creation time. You can combine multiple sort keys.	{ "InstanceNameSort": "asc", "ExpireTimeSort": "asc", "CreationTimeSort": "desc", "EnsRegionId": "desc" }
EnsServiceId	string	No	The ID of the edge service. If this parameter is specified, the operation returns only the instances that are created for the edge service.	ens-20190730202316s****
InstanceResourceType	string	No	The resource type. Valid values: EnsInstance: subscription instance. EnsService: edge service instance. BuildMachine: image building machine. EnsPostPaidInstance: pay-as-you-go instance.	EnsService
SearchKey	string	No	The keyword for the query. You can use this parameter to search for instances by ip, InstanceName, or InstanceId.	Joshua
NetworkId	string	No	The ID of the network.	n-2zeuphj08tt7q3brd****
VSwitchId	string	No	The ID of the vSwitch.	vsw-2zeh0r1pabwtg6wcs****
SecurityGroupId	string	No	The ID of the security group.	sg-5kyicq2kfcapxrdds6tar7jqb
IntranetIp	string	No	The private IP address.	47.100.XX.XX
Tags	array<object>	No	The tags of the resource. This parameter is not returned. You can call the operations of the Tag service.
	object	No	The tags of the instance. This parameter is not returned. You can call the operations of the Tag service.
Key	string	No	The key of tag N of the instance. Valid values of N: 1 to 20.	tag
Value	string	No	The value of tag N of the instance. Valid values of N: 1 to 20.	2
InstanceType	string	No	The instance type.	ens.se1.tiny
ServiceStatus	array	No	The business status of the instance. This status does not represent the actual running state of the instance.
	string	No	The business status of the instance. This status does not represent the actual running state of the instance. Expired Arrears	Expired
EipAddresses	array	No
	string	No

Response elements

Element	Type	Description	Example
	object
Code	integer	The response code. A value of 0 indicates that the request was successful.	0
PageSize	integer	The number of entries per page.	60
PageNumber	integer	The page number of the returned results.	1
RequestId	string	The request ID.	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E
TotalCount	integer	The total number of instances that match the query.	2
Instances	object
Instance	array<object>	An array of `InstanceAttributesType` objects, where each object contains the details of an instance.
	array<object>	The details of an instance.
CreationTime	string	The time when the instance was created. The time is in UTC and uses the ISO 8601 format: `yyyy-MM-ddTHH:mm:ssZ`.	2019-07-26T06:40:43Z
Status	string	The status of the instance. Valid values: `Running`: The instance is running. `Expired`: The instance has expired. `Stopped`: The instance is stopped.	Running
SpecName	string	The instance type.	ens.sn1.stiny
InstanceTypeFamily	string	The instance type family. Valid values: `x86_vm`: X86 compute `x86_pm`: X86 bare metal `x86_bmi`: X86 bare metal instance `x86_bm`: Smart NIC bare metal `pc_bmi`: Heterogeneous bare metal instance `pc_vm`: Heterogeneous virtual machine `arm_bmi`: ARM compute	x86_vm
InstanceResourceType	string	The resource type of the instance. Valid values: `EnsInstance`: A standalone instance. `EnsService`: An edge service instance. `BuildMachine`: An image build machine. `EnsPostPaidInstance`: A standalone pay-as-you-go instance.	EnsService
HostName	string	The hostname of the instance. A period (.) or hyphen (-) cannot be the first or last character, and cannot be used consecutively. For Windows instances, the hostname must be 2 to 15 characters long, consisting of letters, digits, and hyphens (-). It cannot contain periods (.) or be composed solely of digits. For other instance types (such as Linux), the hostname must be 2 to 64 characters long. You can use periods (.) to separate the name into segments. Each segment can consist of letters, digits, and hyphens (-).	testHostName
InstanceId	string	The ID of the instance.	i-instanc****
InternetMaxBandwidthIn	integer	The maximum inbound public bandwidth. Unit: Mbit/s.	40
InternetMaxBandwidthOut	integer	The maximum outbound public bandwidth. Unit: Mbit/s.	100
EnsRegionId	string	The ID of the instance's region.	cn-hangzhou-telecom
Cpu	string	The number of vCPU cores.	2
ExpiredTime	string	The expiration time. The time is in UTC and uses the ISO 8601 format: `yyyy-MM-ddTHH:mm:ssZ`.	2119-07-13T02:38:57Z
InstanceName	string	The name of the instance.	i-5itef0f28t17bcdw9deu6meub
Disk	integer	The total size of the disks. Unit: MiB.	71680
OSName	string	The name of the image.	centos 6.8 x86_64
Memory	integer	The memory size. Unit: MB.	2048
ImageId	string	The ID of the image.	m-****
DataDisk	object
DataDisk	array<object>	The information about the data disks.
	object	The details of a data disk.
device_type	string	The disk category. Valid values: file: local disk. pangu: Efficiency Cloud Disk. local_hdd: local HDD.	pangu
disk_type	string	The type of the cloud disk or local disk. Valid values: system: system disk. data: data disk.	system
Size	integer	The size of the disk. Unit: MiB.	51200
DiskName	string	The name of the disk.	DiskName
uuid	string	The UUID.	5431f898-1323-4e64-8ce1-6cad50ed****
storage	integer	The size of the disk. Unit: MiB.	20480
DiskId	string	The ID of the disk.	d-5ip4c2dhmas0vjd5u1r****
Category	string	The category of the cloud disk or local disk. Valid values: file: local disk. pangu: Efficiency Cloud Disk. local_hdd: local HDD.	file
name	string	The name of the disk.	name
DiskSize	integer	The size of the disk. Unit: GiB.	100
EncryptKeyId	string	The ID of the KMS key used for the cloud disk.	0e478b7a-4262-4802-b8cb-00d3fxxxxx
Encrypted	boolean	Indicates whether the cloud disk is encrypted.	true
PublicIpAddresses	object
PublicIpAddress	array<object>	The information about the public IP addresses.
	object	The information about the public IP addresses.
Ip	string	The IP address.	119.147.xx.xx
GateWay	string	The gateway.	119.147.xx.xx
Isp	string	The ISP.	unicom
PrivateIpAddresses	object
PrivateIpAddress	array<object>	The information about the private IP addresses of the instance.
	object
Ip	string	The IP address.	119.147.xx.xx
GateWay	string	The gateway.	119.147.xx.xx
Isp	string	The ISP.	cmcc
SecurityGroupIds	object
SecurityGroupId	array	The security group ID.
	string	The security group ID.	sg-5kyicq2kfcapxrdds6ta****
InnerIpAddress	object
IpAddress	array	The private IP address of the instance.
	string	A private IP address of the instance.	10.170.xx.xx
PublicIpAddress	object
IpAddress	array	The public IP address.
	string	A public IP address.	119.147.xx.xx
SystemDisk	object	The details of the system disk.
device_type	string	The disk category. Valid values: file: local disk. pangu: Efficiency Cloud Disk. local_hdd: local HDD.	pangu
disk_type	string	The type of the cloud disk or local disk. Valid values: system: system disk. data: data disk.	system
Size	integer	The size of the disk. Unit: MiB.	51200
DiskName	string	The name of the disk.	DiskName
uuid	string	The UUID.	5431f898-1323-4e64-8ce1-6cad50ed****
storage	integer	The disk capacity. Unit: MiB.	20480
DiskId	string	The ID of the disk.	d-5ip4c2dhmas0rn7rt0p9****
Category	string	The category of the cloud disk or local disk. Valid values: file: local disk. pangu: Efficiency Cloud Disk. local_hdd: local HDD.	file
name	string	The name of the disk.	DiskName
NetworkAttributes	object	The network information.
NetworkId	string	The network ID.	n-2zeuphj08tt7q3brd****
VSwitchId	string	The ID of the VSwitch.	vsw-2zeh0r1pabwtg6wcs****
PrivateIpAddress	object
IpAddress	array	The information about the private IP addresses of the instance.
	string	The private IP address of the instance. You can specify only one private IP address. The IP address must be an available address within the CIDR block of the specified VSwitch (`VSwitchId`).	172.17..
Tags	object
Tags	array<object>	The tags of the instance. Important This operation does not return tag information. To retrieve tags, you must call a dedicated tagging API.
	object	The tag information. Important This operation does not return tag information. To retrieve tags, you must call a dedicated tagging API.
TagValue	string	The value of the tag.	value1
TagKey	string	The key of the tag.	key1
AutoReleaseTime	string	The time when the instance is automatically released.	2023-06-28T14:38:52Z
SpotStrategy	string	The bidding policy for the spot instance.	NoSpot
KeyPairName	string	The name of the key pair.	TestKeyPairName
NetworkInterfaces	object
NetworkInterfaces	array<object>	A list of elastic network interfaces.
	array<object>	Details of an elastic network interface.
Type	string	The type of the elastic network interface. Valid values: `Primary`: The primary network interface. `Secondary`: The secondary network interface.	Primary
MacAddress	string	The MAC address of the elastic network interface.	00:16:XXX:XXX:60:0a
PrimaryIpAddress	string	The primary private IP address.	10.XXX.XXX.25
NetworkInterfaceId	string	The ID of the elastic network interface.	eni-53afk8a0t5lklbi8m7j8iczdg
PrivateIpSets	object
PrivateIpSet	array<object>	A collection of `PrivateIpSet` objects.
	object	A collection of `PrivateIpSet` objects.
PrivateIpAddress	string	The private IP address.	192.XXX.XXX.130
Primary	boolean	Indicates whether the IP address is the primary private IP address. Valid values: `true`: The IP address is the primary private IP address. `false`: The IP address is a secondary private IP address.	true
Ipv6Sets	object
Ipv6Set	array<object>	A collection of IPv6 addresses assigned to the elastic network interface.
	object	A collection of IPv6 addresses assigned to the elastic network interface.
Ipv6Address	string	The IPv6 address assigned to the elastic network interface.	2605:340:cdb1:XXXX:XXXX:XXXX:XXXX:e2d6
VpdVSwitchId	string
VpdId	string
ServiceStatus	string	The service status of the instance, instead of the running status.	Expired
DeletionProtection	boolean

Examples

Success response

JSON format

{
  "Code": 0,
  "PageSize": 60,
  "PageNumber": 1,
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
  "TotalCount": 2,
  "Instances": {
    "Instance": [
      {
        "CreationTime": "2019-07-26T06:40:43Z",
        "Status": "Running",
        "SpecName": "ens.sn1.stiny",
        "InstanceTypeFamily": "x86_vm",
        "InstanceResourceType": "EnsService",
        "HostName": "testHostName",
        "InstanceId": "i-instanc****",
        "InternetMaxBandwidthIn": 40,
        "InternetMaxBandwidthOut": 100,
        "EnsRegionId": "cn-hangzhou-telecom",
        "Cpu": "2",
        "ExpiredTime": "2119-07-13T02:38:57Z",
        "InstanceName": "i-5itef0f28t17bcdw9deu6meub",
        "Disk": 71680,
        "OSName": "centos 6.8 x86_64",
        "Memory": 2048,
        "ImageId": "m-****",
        "DataDisk": {
          "DataDisk": [
            {
              "device_type": "pangu",
              "disk_type": "system",
              "Size": 51200,
              "DiskName": "DiskName",
              "uuid": "5431f898-1323-4e64-8ce1-6cad50ed****",
              "storage": 20480,
              "DiskId": "d-5ip4c2dhmas0vjd5u1r****",
              "Category": "file",
              "name": "name",
              "DiskSize": 100,
              "EncryptKeyId": "0e478b7a-4262-4802-b8cb-00d3fxxxxx",
              "Encrypted": true
            }
          ]
        },
        "PublicIpAddresses": {
          "PublicIpAddress": [
            {
              "Ip": "119.147.xx.xx",
              "GateWay": "119.147.xx.xx",
              "Isp": "unicom"
            }
          ]
        },
        "PrivateIpAddresses": {
          "PrivateIpAddress": [
            {
              "Ip": "119.147.xx.xx",
              "GateWay": "119.147.xx.xx",
              "Isp": "cmcc"
            }
          ]
        },
        "SecurityGroupIds": {
          "SecurityGroupId": [
            "sg-5kyicq2kfcapxrdds6ta****"
          ]
        },
        "InnerIpAddress": {
          "IpAddress": [
            "10.170.xx.xx"
          ]
        },
        "PublicIpAddress": {
          "IpAddress": [
            "119.147.xx.xx"
          ]
        },
        "SystemDisk": {
          "device_type": "pangu",
          "disk_type": "system",
          "Size": 51200,
          "DiskName": "DiskName",
          "uuid": "5431f898-1323-4e64-8ce1-6cad50ed****",
          "storage": 20480,
          "DiskId": "d-5ip4c2dhmas0rn7rt0p9****",
          "Category": "file",
          "name": "DiskName"
        },
        "NetworkAttributes": {
          "NetworkId": "n-2zeuphj08tt7q3brd****",
          "VSwitchId": "vsw-2zeh0r1pabwtg6wcs****",
          "PrivateIpAddress": {
            "IpAddress": [
              "172.17.**.**"
            ]
          }
        },
        "Tags": {
          "Tags": [
            {
              "TagValue": "value1",
              "TagKey": "key1"
            }
          ]
        },
        "AutoReleaseTime": "2023-06-28T14:38:52Z",
        "SpotStrategy": "NoSpot",
        "KeyPairName": "TestKeyPairName",
        "NetworkInterfaces": {
          "NetworkInterfaces": [
            {
              "Type": "Primary",
              "MacAddress": "00:16:XXX:XXX:60:0a",
              "PrimaryIpAddress": "10.XXX.XXX.25",
              "NetworkInterfaceId": "eni-53afk8a0t5lklbi8m7j8iczdg",
              "PrivateIpSets": {
                "PrivateIpSet": [
                  {
                    "PrivateIpAddress": "192.XXX.XXX.130",
                    "Primary": true
                  }
                ]
              },
              "Ipv6Sets": {
                "Ipv6Set": [
                  {
                    "Ipv6Address": "2605:340:cdb1:XXXX:XXXX:XXXX:XXXX:e2d6"
                  }
                ]
              },
              "VpdVSwitchId": "",
              "VpdId": ""
            }
          ]
        },
        "ServiceStatus": "Expired",
        "DeletionProtection": false
      }
    ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	MissingParameter	The input parameter domainName that is mandatory for processing this request is not supplied.
400	InstanceIdNotFound	The input parameter instancdId that is not found.	The specified instance ID does not exist.
400	NoPermission	Permission denied.
400	CallInterface	Call Interface Happen Error.	An error occurred when you call the operation.
400	InvalidParameter.%s	The specified field %s invalid. Please check it again.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.