Queries instances - API Reference| Alibaba Cloud Documentation Center

You can use one of the following methods to check the response:

Method 1: Use the MaxResults parameter to specify the number of entries per page. Then, use the NextToken parameter to specify the token that is used to display the next page. The NextToken parameter is set to the value that is returned from the most recent call of the DescribeDBInstances operation for the NextToken parameter.

Note The first time you call the DescribeDBInstances operation to perform a paged query, you need to specify only the MaxResults parameter. In this case, the operation returns the data of the first page and the value of the NextToken parameter.
Method 2: Use the PageSize parameter to specify the number of entries per page. Then, use the PageNumber parameter to display the next page.

Note You can use only one of the preceding methods. If a large number of entries are returned, we recommend that you use Method 1 to increase the query speed.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	DescribeDBInstances	The operation that you want to perform. Set the value to DescribeDBInstances.
ClientToken	String	No	ETnLKlblzczshOTUbOCzxxxxxxx	The client token that is used to ensure the idempotence of the request. You can use the client to generate the value, but you must ensure that it is unique among different requests. The token can only contain ASCII characters and cannot exceed 64 characters in length.
proxyId	String	No	API	The ID of the proxy mode.
Engine	String	No	MySQL	The database engine that is run by the instances. Valid values: MySQL SQLServer PostgreSQL MariaDB By default, this operation returns the instances that run any of the supported database engines.
ZoneId	String	No	cn-hangzhou-a	The ID of the zone to which the instances belong.
ResourceGroupId	String	No	rg-acfmyxxxxx	The ID of the resource group to which the instances belong.
DBInstanceStatus	String	No	Running	The status of the instances. For more information, see Instance state table.
Expired	String	No	True	Specifies whether the instances have expired. Valid values: True: The instances have expired. False: The instances have not expired.
SearchKey	String	No	rm-uf6w	The keywords that are contained in the IDs or descriptions of the instances.
DBInstanceId	String	No	rm-uf6wjk5xxxxxxx	The ID of the instance. You can call the DescribeDBInstances operation to query the IDs of instances.
DBInstanceType	String	No	Primary	The role of the instances. Valid values: Primary: primary instance Readonly: read-only instance Guard: disaster recovery instance Temp: temporary instance By default, this operation returns the instances that assume any of the supported roles.
RegionId	String	Yes	cn-hangzhou	The ID of the region in which the instances reside. You can call the DescribeRegions operation to query the most recent region list.
PageSize	Integer	No	30	The number of entries to return on each page. Valid values: 1 to 100. Default value: 30.
PageNumber	Integer	No	1	The number of the page to return. Valid values: any non-zero positive integer. Default value: 1.
InstanceNetworkType	String	No	Classic	The network type of the instances. Valid values: VPC Classic By default, this operation returns the instances that reside in any of the supported types of networks.
VpcId	String	No	vpc-uf6f7l4fg90xxxxxxxxxx	The ID of the virtual private cloud (VPC) to which the instances belong.
VSwitchId	String	No	vsw-uf6adz52c2pxxxxxxxxxx	The ID of the vSwitch that is associated with the specified VPC.
DBInstanceClass	String	No	rds.mys2.small	The instance type of the instances. For information, see Primary ApsaraDB RDS instance types.
EngineVersion	String	No	5.7	The version of the database engine that is run by the instances.
PayType	String	No	Postpaid	The billing method of the instances. Valid values: Postpaid: pay-as-you-go Prepaid: subscription
ConnectionMode	String	No	Standard	The connection mode of the instance. Valid values: Standard: standard mode Safe: database proxy mode By default, this operation returns the instances that run in any of the supported connection modes.
Tags	String	No	{"key1":"value1"}	The tags that are added to the instances. Each tag is a key-value pair that consists of two parts: TagKey and TagValue. You can specify a maximum of five tags in the following format for each request: {"key1":"value1","key2":"value2"...}.
DedicatedHostGroupId	String	No	dhg-7a9xxxxxxxx	The ID of the dedicated cluster to which the instances belong.
DedicatedHostId	String	No	i-bpxxxxxxx	The ID of the host to which the instances belong in the specified dedicated cluster.
InstanceLevel	Integer	No	0	Specifies whether to return the RDS editions of the instances by using the Category parameter. Valid values: 0: You want the RDS editions of the instances to be returned. 1: You do not want the RDS editions of the instances to be returned.
ConnectionString	String	No	rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com	The endpoint of the instance. Specify this parameter only when you want to query a single instance.
NextToken	String	No	o7PORW5o2TJg**********	The token that is used to display the next page. This parameter is set to the value that is returned from the most recent call of the DescribeDBInstances operation for the NextToken parameter. If the returned entries are displayed on multiple pages, the next page can be displayed when you call this operation again with this parameter specified.
MaxResults	Integer	No	30	The number of entries to return on each page. Valid values: 1 to 100. Default value: 30. Note If you specify this parameter, the PageSize parameter and the PageNumber parameter are unavailable.

Response parameters


Parameter	Type	Example	Description
RequestId	String	1AD222E9-E606-4A42-BF6D-8A4442913CEF	The ID of the request.
PageNumber	Integer	1	The number of the returned page. Note If you specify the MaxResults parameter or the NextToken parameter, only the value 1 is returned. You can ignore the value 1.
PageRecordCount	Integer	10	The number of instances returned on the current page.
TotalRecordCount	Integer	100	The total number of entries. Note If you specify the MaxResults parameter or the NextToken parameter, only the number of entries on the current page is returned. You can ignore the number.
Items	Array of DBInstance		An array that consists of the information about the instances that are returned.
DBInstance
VpcId	String	vpc-uf6f7l4fg90xxxxxxx	The ID of the VPC to which the instance belongs.
DedicatedHostIdForLog	String	dh-bpxxxx	The ID of the host on which the logger instance resides.
CreateTime	String	2018-11-05T11:26:02Z	The time when the instance was created. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
PayType	String	Postpaid	The billing method of the instance. Valid values: Postpaid: pay-as-you-go Prepaid: subscription
DedicatedHostNameForLog	String	testlog	The name of the host on which the logger instance resides.
MutriORsignle	Boolean	true	Indicates whether the multi-zone deployment method is used for the instance. Valid values: true and false. Note If the multi-zone deployment method is used for the instance, the zone ID of the instance contains MAZ. Example: `cn-hangzhou-MAZ10(h,i)`.
DedicatedHostGroupName	String	testhostgroup	The name of the dedicated cluster to which the instance belongs.
EngineVersion	String	5.7	The version of the database engine that is run by the instance.
DedicatedHostGroupId	String	dhg-7a9xxxxxxxx	The ID of the dedicated cluster to which the instance belongs.
VpcName	String	test-huadong	The name of the VPC to which the instance belongs.
DedicatedHostZoneIdForMaster	String	cn-hangzhou-c	The ID of the zone to which the primary instance belongs.
ConnectionString	String	rm-uf6wjk5xxxxxxx.mysql.rds.aliyuncs.com	The endpoint of the instance.
InstanceNetworkType	String	Classic	The network type of the instance. Valid values: Classic VPC
MasterInstanceId	String	rm-uf6wjk5xxxxxxxxxx	The ID of the primary instance. If the value of this parameter is null, the instance is a primary instance.
ExpireTime	String	2019-02-27T16:00:00Z	The time at which the instance expires. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC. Note Pay-as-you-go instances never expire.
DestroyTime	String	2018-11-05T11:26:02Z	The time when the instance was destroyed. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time is displayed in UTC.
GuardDBInstanceId	String	rm-uf64zsuxxxxxxxxxx	The ID of the disaster recovery instance. This parameter is returned only when the instance is a primary instance and has a disaster recovery instance.
DedicatedHostNameForMaster	String	testmaster	The name of the host on which the primary instance resides.
ZoneId	String	cn-hangzhou-a	The ID of the zone to which the instance belongs.
TipsLevel	Integer	1	The severity level of the exception that is detected on the instance. This parameter is returned only when the instance runs MySQL on RDS Standard Edition and is created in a dedicated cluster. Valid values: 1: The instance is normal. 2: The specifications of the read-only instances do not match the specifications of the primary instance. You must adjust the specifications of these instances based on your business requirements.
DBInstanceId	String	rm-uf6wjk5xxxxxxxxxx	The ID of the instance.
DedicatedHostIdForMaster	String	dh-bpxxxx	The ID of the host on which the primary instance resides.
TempDBInstanceId	String	rm-uf64zsuxxxxxxxxxx	The ID of the temporary instance. This parameter is returned only when the instance is a primary instance and has a temporary instance.
DBInstanceStorageType	String	ModuleList.4.ModuleCode	The storage type of the instance.
ConnectionMode	String	Standard	The connection mode of the instance. Valid values: Standard: standard mode Safe: database proxy mode
LockMode	String	Unlock	Indicates whether the instance is locked. Valid values: Unlock: The instance is not locked. ManualLock: The instance is manually locked. LockByExpiration: The instance is automatically locked after it expires. LockByRestoration: The instance is automatically locked before it is rolled back. LockByDiskQuota: The instance is automatically locked after its storage capacity is exhausted. Released: The instance is released. After an instance is released, the instance cannot be unlocked. You can only restore the backup data of the instance to a new instance. This process requires a long period of time.
GeneralGroupName	String	TestGroup	The name of the dedicated cluster to which the instance belongs. This parameter is returned only when the instance runs MySQL on RDS Standard Edition and is created in a dedicated cluster.
VpcCloudInstanceId	String	rm-uf6wjk5xxxxxxx	The ID of the instance. This parameter is returned only when the instance resides in a VPC.
DedicatedHostZoneIdForSlave	String	cn-hangzhou-d	The ID of the zone to which the secondary instance belongs.
Tips	String	everything is fine.	The information about the exception that is detected on the instance. This parameter is returned only when the instance runs MySQL on RDS Standard Edition and is created in a dedicated cluster.
DedicatedHostZoneIdForLog	String	cn-hangzhou-b	The ID of the zone to which the logger instance belongs.
DedicatedHostNameForSlave	String	testslave	The name of the host to which the secondary instance belongs.
DBInstanceDescription	String	testdatabase	The description of the instance.
DBInstanceNetType	String	Internet	The type of network connection to the instance. Valid values: Internet: Internet Intranet: internal network
DBInstanceType	String	Primary	The role of the instance. Valid values: Primary: primary instance ReadOnly: read-only instance Guard: disaster recovery instance Temp: temporary instance
LockReason	String	instance_expired	The reason why the instance is locked.
DBInstanceStatus	String	Running	The status of the instance. For more information, see Instance state table.
RegionId	String	cn-hangzhou	The ID of the region where the instance resides.
VSwitchId	String	vsw-uf6adz52c2pxxxxxxx	The ID of the vSwitch that is associated with the specified VPC.
DedicatedHostIdForSlave	String	dh-bpxxxx	The ID of the host on which the secondary instance resides.
ResourceGroupId	String	rg-acfmyxxxxxxx	The ID of the resource group to which the instance belongs.
Category	String	Basic	The RDS edition of the instance. Valid values: Basic: Basic Edition HighAvailability: High-availability Edition Finance: Enterprise Edition
Engine	String	MySQL	The database engine that is run by the instance.
DBInstanceClass	String	rds.mys2.small	The instance type of the instance. For information, see Primary ApsaraDB RDS instance types.
SwitchWeight	Integer	100	Indicates whether the instance supports weight-based switchovers for high availability. This parameter is returned only when the instance runs MySQL on RDS Standard Edition and is created in a dedicated cluster. Valid values: 100: The instance supports weight-based switchovers for high availability. 0: The instance does not support weight-based switchovers for high availability.
ReadOnlyDBInstanceIds	Array of ReadOnlyDBInstanceId		An array that consists of the IDs of the read-only instances that are attached to the instance. This parameter is returned only when the instance is a primary instance.
ReadOnlyDBInstanceId
DBInstanceId	String	rr-uf6wjk5xxxxxxx	The ID of the read-only instance.
DeletionProtection	Boolean	false	Indicates whether the release protection feature is enabled for the read-only instance. Valid values: true: The release protection feature is enabled. false: The release protection feature is disabled.
NextToken	String	o7PORW5o2TJg**********	The token that is used to display the next page. If the returned entries are displayed on multiple pages, the next page can be displayed when you call this operation again with the NextToken parameter specified.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=DescribeDBInstances
&RegionId=cn-hangzhou
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<DescribeDBInstancesResponse>
    <TotalRecordCount>1</TotalRecordCount>
    <PageRecordCount>1</PageRecordCount>
    <RequestId>A436D75C-30B0-1F34-8544-4B46F4407CC1</RequestId>
    <NextToken>o7PORW5owHNg**********</NextToken>
    <PageNumber>1</PageNumber>
    <Items>
        <DBInstance>
            <EngineVersion>10.0</EngineVersion>
            <ZoneId>cn-hangzhou-h</ZoneId>
            <DBInstanceStatus>Running</DBInstanceStatus>
            <ResourceGroupId>rg-acfmyiu********</ResourceGroupId>
            <DBInstanceNetType>Intranet</DBInstanceNetType>
            <DBInstanceClass>pg.n2.small.2c</DBInstanceClass>
            <CreateTime>2021-02-02T09:14:48Z</CreateTime>
            <VSwitchId>vsw-bp10aqj6o4lcl********</VSwitchId>
            <TipsLevel>0</TipsLevel>
            <DBInstanceType>Primary</DBInstanceType>
            <PayType>Prepaid</PayType>
            <LockMode>Unlock</LockMode>
            <DeletionProtection>false</DeletionProtection>
            <MutriORsignle>false</MutriORsignle>
            <InstanceNetworkType>VPC</InstanceNetworkType>
            <InsId>1</InsId>
            <VpcId>vpc-bp1opxu1zkhn0********</VpcId>
            <DBInstanceId>pgm-bp10re7n********</DBInstanceId>
            <ConnectionMode>Standard</ConnectionMode>
            <ReadOnlyDBInstanceIds>
            </ReadOnlyDBInstanceIds>
            <VpcCloudInstanceId>pgm-bp10re7n********</VpcCloudInstanceId>
            <RegionId>cn-hangzhou</RegionId>
            <ConnectionString>pgm-bp10re7n**************.pg.rds.aliyuncs.com</ConnectionString>
            <ExpireTime>2021-02-03T09:14:48Z</ExpireTime>
            <Engine>PostgreSQL</Engine>
        </DBInstance>
    </Items>
</DescribeDBInstancesResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "TotalRecordCount" : 1,
  "PageRecordCount" : 1,
  "RequestId" : "A436D75C-30B0-1F34-8544-4B46F4407CC1",
  "NextToken" : "o7PORW5owHNg**********",
  "PageNumber" : 1,
  "Items" : {
    "DBInstance" : [ {
      "EngineVersion" : "10.0",
      "ZoneId" : "cn-hangzhou-h",
      "DBInstanceStatus" : "Running",
      "ResourceGroupId" : "rg-acfmyiu********",
      "DBInstanceNetType" : "Intranet",
      "DBInstanceClass" : "pg.n2.small.2c",
      "CreateTime" : "2021-02-02T09:14:48Z",
      "VSwitchId" : "vsw-bp10aqj6o4lcl********",
      "TipsLevel" : 0,
      "DBInstanceType" : "Primary",
      "PayType" : "Prepaid",
      "LockMode" : "Unlock",
      "DeletionProtection" : false,
      "MutriORsignle" : false,
      "InstanceNetworkType" : "VPC",
      "InsId" : 1,
      "VpcId" : "vpc-bp1opxu1zkhn0********",
      "DBInstanceId" : "pgm-bp10re7n********",
      "ConnectionMode" : "Standard",
      "ReadOnlyDBInstanceIds" : {
        "ReadOnlyDBInstanceId" : [ ]
      },
      "VpcCloudInstanceId" : "pgm-bp10re7n********",
      "RegionId" : "cn-hangzhou",
      "ConnectionString" : "pgm-bp10re7n**************.pg.rds.aliyuncs.com",
      "ExpireTime" : "2021-02-03T09:14:48Z",
      "Engine" : "PostgreSQL"
    } ]
  }
}

Error codes


HTTP status code	Error code	Error message	Description
400	Invalid.NextToken	The parameter NextToken is invalid.	The error message returned because the value of the NextToken parameter is invalid.
400	InvalidDBInstanceType.ValueNotSupport	The specified parameter"DBInstanceType" is not valid.	The error message returned because the specified instance type is invalid. Specify a valid instance type.

For a list of error codes, visit the API Error Center.