Help Center/ Relational Database Service/ API Reference/ API v3 (Recommended)/ DB Instance Management/ Querying DB Instances
Updated on 2025-07-14 GMT+08:00
View PDF

Querying DB Instances

Function

This API is used to query DB instances according to search criteria.

  • Before calling an API, you need to understand the API in Authentication.

URI

  • URI format

    GET /v3/{project_id}/instances?id={id}&name={name}&type={type}&datastore_type={datastore_type}&vpc_id={vpc_id}&subnet_id={subnet_id}&offset={offset}&limit={limit}&tags={key}={value}

  • Parameter description
    Table 1 Parameter description

    Name

    Type

    Mandatory

    Description

    project_id

    String

    Yes

    Explanation:

    Project ID of a tenant in a region.

    For details about how to obtain the project ID, see Obtaining a Project ID.

    Constraints:

    N/A

    Value range:

    N/A

    Default value:

    N/A

    id

    String

    No

    Explanation:

    Instance ID.

    The asterisk (*) is reserved for the system. If the instance ID starts with *, it indicates that fuzzy match is performed based on the value following * Otherwise, the exact match is performed based on the instance ID. The value cannot contain only asterisks (*).

    Constraints:

    N/A

    Value range:

    N/A

    Default value:

    N/A

    name

    String

    No

    Explanation:

    Instance name.

    The asterisk (*) is reserved for the system. If the instance name starts with *, it indicates that fuzzy match is performed based on the value following * Otherwise, the exact match is performed based on the instance name. The value cannot contain only asterisks (*).

    Constraints:

    N/A

    Value range:

    N/A

    Default value:

    N/A

    type

    String

    No

    Explanation:

    Instance type.

    Constraints:

    N/A

    Value range:

    • Single: single-node instance
    • Ha: primary/standby instance
    • Replica: read replica
    • Enterprise: distributed instance (Enterprise Edition)

    Default value:

    N/A

    datastore_type

    String

    No

    Explanation:

    DB engine.

    Constraints:

    The value is case-sensitive.

    Value range:

    • MySQL
    • MariaDB
    • PostgreSQL

    Default value:

    N/A

    vpc_id

    String

    No

    Explanation:

    VPC ID. To obtain this parameter value, use either of the following methods:

    • Method 1: Log in to VPC console and view the VPC ID in the VPC details.
    • Method 2: See the "Querying VPCs" section in the Virtual Private Cloud API Reference.

    Constraints:

    N/A

    Value range:

    N/A

    Default value:

    N/A

    subnet_id

    String

    No

    Explanation:

    Subnet ID. To obtain this parameter value, use either of the following methods:

    • Method 1: Log in to the VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page.
    • Method 2: See the "Querying Subnets" section in the Virtual Private Cloud API Reference.

    Constraints:

    N/A

    Value range:

    N/A

    Default value:

    N/A

    offset

    Integer

    No

    Explanation:

    Index offset. The query starts from the next piece of data indexed by this parameter.

    Constraints:

    The value must be a non-negative number.

    Value range:

    An integer greater than or equal to 0

    Default value:

    0

    limit

    Integer

    No

    Explanation:

    Number of records to be queried.

    Constraints:

    N/A

    Value range:

    The default value is 100. The value cannot be a negative number. The minimum value is 1 and the maximum value is 100.

    Default value:

    100

    tags

    Array of objects

    No

    Explanation:

    Tag key-value pairs of the instance.

    • {key} indicates the tag key. It must be unique and cannot be empty.
    • {value} indicates the tag value, which can be left empty.

    To query instances with multiple tag keys and values, separate key-value pairs with commas (,). A maximum of 10 key-value pairs are supported.

    For details, see Table 2.

    Constraints:

    N/A

    Value range:

    N/A

    Default value:

    N/A
    Table 2 tags field data structure description

    Name

    Type

    Mandatory

    Description

    key

    String

    Yes

    Explanation:

    Tag key.

    Constraints:

    N/A

    Value range:

    It must consist of 1 to 128 Unicode characters.

    It can contain letters, digits, spaces, and special characters _.:=+-@. However, it cannot start or end with a space, or start with _sys_.

    Default value:

    N/A

    value

    String

    No

    Explanation:

    Tag value.

    Constraints:

    N/A

    Value range:

    It can be left blank or contain a maximum of 255 Unicode characters.

    It can contain letters, digits, spaces, and special characters _.:=+-@.

    Default value:

    N/A

Request

  • Request parameters

    None

Response

  • Normal response
    Table 3 Parameter description

    Name

    Type

    Description

    instances

    Array of objects

    Explanation:

    Indicates the DB instance information.

    For details, see Table 4.

    total_count

    Integer

    Explanation:

    Indicates the total number of records.

    Value range:

    N/A
    Table 4 instances field data structure description

    Name

    Type

    Description

    id

    String

    Explanation:

    Indicates the DB instance ID.

    Value range:

    N/A

    name

    String

    Explanation:

    Indicates the created DB instance name.

    Value range:

    N/A

    status

    String

    Explanation:

    Indicates the DB instance status.

    Value range:

    • BUILD: The instance is being created.
    • CREATE FAIL: The instance failed to be created.
    • ACTIVE: The instance is running properly.
    • FAILED: The instance is abnormal.
    • MODIFYING: The vCPU, memory, or storage space of the instance is being changed.
    • REBOOTING: The instance is being rebooted.
    • RESTORING: The instance is being restored.
    • MODIFYING INSTANCE TYPE: The instance is changing from single to primary/standby.
    • SWITCHOVER: The instance is performing a primary/standby switchover.
    • MIGRATING: The instance is being migrated.
    • BACKING UP: The instance is being backed up.
    • MODIFYING DATABASE PORT: The database port is being changed.

    alias

    String

    Explanation:

    Indicates the DB instance alias.

    Value range:

    N/A

    private_ips

    List<String>

    Explanation:

    Indicates the private IP address list. It is a blank string until an ECS is created.

    Value range:

    N/A

    private_dns_names

    List<String>

    Explanation:

    Indicates the private domain name list of the DB instance. After a DB instance is created, you need to manually apply for a private domain name, or the private domain name is left blank.

    Value range:

    N/A

    public_ips

    List<String>

    Explanation:

    Indicates the public IP address list.

    Value range:

    N/A

    port

    Integer

    Explanation:

    Indicates the database port number.

    Value range:

    • RDS for MySQL instances can use database ports 1024 to 65535, excluding 12017 and 33071, which are reserved for RDS system use.
    • RDS for MariaDB instances can use database ports 1024 to 65535, excluding 12017 and 33071, which are reserved for RDS system use.
    • RDS for PostgreSQL instances can use database ports 2100 to 9500.

    If this parameter is not set, the default value is as follows:

    • RDS for MySQL: 3306
    • RDS for MariaDB: 3306
    • RDS for PostgreSQL: 5432

    type

    String

    Explanation:

    Instance type.

    Value range:

    • Single: single-node instance
    • Ha: primary/standby instance
    • Replica: read replica
    • Enterprise: distributed instance (Enterprise Edition)

    ha

    Object

    Explanation:

    Indicates the primary/standby DB instance information. Returned only when you obtain a primary/standby DB instance list.

    For details, see Table 5.

    region

    String

    Explanation:

    Indicates the region where the DB instance is deployed.

    Value range:

    N/A

    datastore

    Object

    Explanation:

    Indicates the database information.

    For details, see Table 6.

    created

    String

    Explanation:

    Indicates the creation time.

    Value range:

    The value is in the "yyyy-mm-ddThh:mm:ssZ" format.

    T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100.

    The value is empty when the instance is being created. After the instance is created, the value is not empty.

    updated

    String

    Explanation:

    Indicates the update time.

    Value range:

    The format is the same as that of the created field.

    The value is empty when the instance is being created. After the instance is created, the value is not empty.

    db_user_name

    String

    Explanation:

    Indicates the default username.

    Value range:

    N/A

    vpc_id

    String

    Explanation:

    Indicates the VPC ID.

    Value range:

    N/A

    subnet_id

    String

    Explanation:

    Indicates the network ID of the subnet.

    Value range:

    N/A

    security_group_id

    String

    Explanation:

    Indicates the security group ID.

    Value range:

    N/A

    flavor_ref

    String

    Explanation:

    Indicates the specification code.

    Value range:

    N/A

    volume

    Object

    Explanation:

    Indicates instance storage.

    For details, see Table 7.

    switch_strategy

    String

    Explanation:

    Indicates the database failover priority.

    Value range:

    • reliability: Reliability is given priority during the failover.
    • availability: Availability is given priority during the failover.

    backup_strategy

    Object

    Explanation:

    Indicates the backup policy.

    For details, see Table 8.

    maintenance_window

    String

    Explanation:

    Indicates the start time of the maintenance time window in the UTC format.

    Value range:

    N/A

    nodes

    Array of objects

    Explanation:

    Indicates the primary/standby DB instance information.

    For details, see Table 9.

    related_instance

    Array of objects

    Explanation:

    Indicates all associated DB instances.

    For details, see Table 10.

    disk_encryption_id

    String

    Explanation:

    Indicates the disk encryption key ID.

    Value range:

    N/A

    time_zone

    String

    Explanation:

    Indicates the time zone.

    Value range:

    N/A

    tags

    Array of objects

    Explanation:

    Indicates the tag list. If there is no tag in the list, an empty array is returned.

    For details, see Table 11.
    Table 5 ha field data structure description

    Name

    Type

    Description

    replication_mode

    String

    Explanation:

    Indicates the replication mode for the standby instance.

    Value range:

    • For RDS for MySQL, the value is async or semisync.
    • For RDS for MariaDB, the value is async or semisync.
    • For RDS for PostgreSQL, the value is async or sync.
    NOTE:
    • async indicates the asynchronous replication mode.
    • semisync indicates the semi-synchronous replication mode.
    • sync indicates the synchronous replication mode.
    Table 6 datastore field data structure description

    Name

    Type

    Description

    type

    String

    Explanation:

    Indicates the DB engine. Its value can be any of the following and is case-insensitive:

    Value range:

    • MySQL
    • MariaDB
    • PostgreSQL

    version

    String

    Explanation:

    Indicates the database version.

    Value range:

    N/A
    Table 7 volume field data structure description

    Name

    Type

    Description

    type

    String

    Explanation:

    Storage type. The value is case-sensitive.

    size

    Integer

    Explanation:

    Storage space in GB.

    Value range:

    N/A
    Table 8 backup_strategy field data structure description

    Name

    Type

    Description

    start_time

    String

    Explanation:

    Indicates the backup time window. Automated backups will be triggered during the backup time window.

    The time is in the UTC format.

    Value range:

    N/A

    keep_days

    Integer

    Explanation:

    Indicates the number of days to retain the generated backup files.

    Value range:

    0–732 If the value is 0, the automated backup policy is not configured or has been disabled.
    Table 9 nodes field data structure description

    Name

    Type

    Description

    id

    String

    Explanation:

    Indicates the node ID.

    Value range:

    N/A

    name

    String

    Explanation:

    Indicates the node name.

    Value range:

    N/A

    role

    String

    Explanation:

    Indicates the node type.

    Value range:

    • master: primary node
    • slave: standby node
    • readreplica: read replica node

    status

    String

    Explanation:

    Indicates the node status.

    availability_zone

    String

    Explanation:

    Indicates the AZ.

    Value range:

    N/A
    Table 10 related_instance field data structure description

    Name

    Type

    Description

    id

    String

    Explanation:

    ID of the associated DB instance.

    Value range:

    N/A

    type

    String

    Explanation:

    Type of the associated DB instance.

    Value range:

    • replica_of: indicates a primary DB instance.
    • replica: indicates a read replica.
    Table 11 tags field data structure description

    Name

    Type

    Description

    key

    String

    Explanation:

    Indicates the tag key.

    Value range:

    N/A

    value

    String

    Explanation:

    Indicates the tag value.

    Value range:

    N/A
  • Example normal response

    Query DB instances based on search criteria.

    {
	"instances": [{
	"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01",
	"status": "ACTIVE",
	"name": "mysql-0820-022709-01",
	"port": 3306,
	"type": "Single",
	"region": "aaa",
	"datastore": {
		"type": "MySQL",
		"version": "5.7"

	},
	"created": "2018-08-20T02:33:49+0800",
	"updated": "2018-08-20T02:33:50+0800",
	"volume": {
		"type": "CLOUDSSD",
		"size": 100
	},
	"nodes": [{
		"id": "06f1c2ad57604ae89e153e4d27f4e4b8no01",
		"name": "mysql-0820-022709-01_node0",
		"role": "master",
		"status": "ACTIVE",
		"availability_zone": "bbb"
	}],
        "alias": "description",
	"private_ips": ["192.168.0.1"],
	"private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"],
	"public_ips": [],
	"db_user_name": "root",
	"vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7",
	"subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef",
	"security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97",
	"flavor_ref": "rds.mysql.s1.large",
 
 
	"switch_strategy": "",
	"backup_strategy": {
		"start_time": "19:00-20:00",
		"keep_days": 7
	},
	"maintenance_window": "02:00-06:00",
	"related_instance": [],
	"disk_encryption_id": "",
	"time_zone": ""
}], "total_count": 1
}
  • Query all DB instances. 
    {
	"instances": [{
		"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in01",
		"status": "ACTIVE",
		"name": "mysql-0820-022709-01",
		"port": 3306,
		"type": "Single",
		"region": "aaa",
		"datastore": {
			"type": "MySQL",
			"version": "5.7"

		},
		"created": "2018-08-20T02:33:49+0800",
		"updated": "2018-08-20T02:33:50+0800",
		"volume": {
			"type": "CLOUDSSD",
			"size": 100
		},
		"nodes": [{
			"id": "06f1c2ad57604ae89e153e4d27f4e4b8no01",
			"name": "mysql-0820-022709-01_node0",
			"role": "master",
			"status": "ACTIVE",
			"availability_zone": "bbb"
		}],
                "alias": "description",
		"private_ips": ["192.168.0.1"],
                
		"private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"],
		"public_ips": [],
		"db_user_name": "root",
		"vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7",
		"subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef",
		"security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97",
		"flavor_ref": "rds.mysql.s1.large",
		"switch_strategy": "",
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"disk_encryption_id": "",
		"time_zone": ""
	}, {
		"id": "ed7cc6166ec24360a5ed5c5c9c2ed726in02",
		"status": "ACTIVE",
		"name": "mysql-0820-022709-02",
		"port": 3306,
		"type": "Single",
		"region": "aaa",
		"datastore": {
			"type": "MySQL",
			"version": "5.7"
		},
		"created": "2018-08-20T02:33:49+0800",
		"updated": "2018-08-20T02:33:50+0800",
		"volume": {
			"type": "CLOUDSSD",
			"size": 100
		},
		"nodes": [{
			"id": "06f1c2ad57604ae89e153e4d27f4e4b8no01",
			"name": "mysql-0820-022709-01_node0",
			"role": "master",
			"status": "ACTIVE",
			"availability_zone": "bbb"
		}],
                "alias": "description",
		"private_ips": ["192.168.0.1"],
		"private_dns_names": ["ed7cc6166ec24360a5ed5c5c9c2ed726in01.internal.xxx.com"],
		"public_ips": [],
                
		"db_user_name": "root",
		"vpc_id": "b21630c1-e7d3-450d-907d-39ef5f445ae7",
		"subnet_id": "45557a98-9e17-4600-8aec-999150bc4eef",
		"security_group_id": "38815c5c-482b-450a-80b6-0a301f2afd97",
		"flavor_ref": "rds.mysql.s1.large",
                "cpu": "2",
                "mem": "4",
		"switch_strategy": "",
		"backup_strategy": {
			"start_time": "19:00-20:00",
			"keep_days": 7
		},
		"maintenance_window": "02:00-06:00",
		"related_instance": [],
		"disk_encryption_id": "",
		"time_zone": ""
	}],
	"total_count": 2
}
  • Abnormal response

    For details, see Abnormal Request Results.

Status Code

Error Code

For details, see Error Codes.

Parent topic: DB Instance Management