Help Center/ Document Database Service/ API Reference/ APIs V3.0 (Recommended)/ DB Instance Management/ Querying Instances and Details
Updated on 2025-10-27 GMT+08:00
View PDF

Querying Instances and Details

Function

This API is used to query instances and details based on specified conditions.

URI

  • URI format

    GET /v3/{project_id}/instances

Table 1 Parameter description

Name

Mandatory

Type

Description

project_id

Yes

String

Project ID of a tenant in a region. To obtain the project ID, see Obtaining a Project ID.

id

No

String

The instance ID, which can be obtained by calling the API that is used for querying instances and details. If you do not have an instance, you can call the API used for creating an instance.

name

No

String

The DB instance name.

If you use asterisk (*) at the beginning of the name, fuzzy search results are returned. Otherwise, the exact results are returned.

NOTE:

The asterisk (*) is a reserved character in the system and cannot be used alone.

mode

No

String

The instance type.

  • Sharding indicates the cluster instance.
  • ReplicaSet indicates the replica set instance.
  • Single indicates the single node instance.

datastore_type

No

String

The database type. The value is DDS-Community.

vpc_id

No

String

The 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 on the VPC details page.
  • Method 2: Query the VPC ID through the VPC API. For details, see Querying VPCs.

subnet_id

No

String

The network ID of the subnet. To obtain this parameter value, use either of the following methods:

  • Method 1: Log in to VPC console and click the target subnet on the Subnets page. You can view the network ID on the displayed page.
  • Method 2: Query the network ID through the VPC API. For details, see Querying Subnets.

offset

No

Integer

The index position. The query starts from the next instance creation time indexed by this parameter under a specified project. If offset is set to N, the resource query starts from the N+1 piece of data.

The value must be greater than or equal to 0. If this parameter is not transferred, offset is set to 0 by default, indicating that the query starts from the latest created DB instance.

limit

No

Integer

The maximum allowed number of DB instances.

The value ranges from 1 to 100. If this parameter is not transferred, the first 100 DB instances are queried by default.

tags

No

String

Query based on the instance tag key and value.

{key} indicates the tag key, and {value} indicates the tag value. A maximum of 20 key-value pairs are supported. The key cannot be empty or duplicate, but the value can be empty.

To query instances with multiple tag keys and values, separate key-value pairs with commas (,).

Request Parameters

Table 2 Request header parameters

Name

Mandatory

Type

Description

X-Auth-Token

Yes

string

User token obtained from IAM. For details, see Authentication.

Response Parameters

Table 3 Response body parameters

Name

Mandatory

Type

Description

instances

Yes

Array of objects

The DB instance information. For more information, see Table 4.

total_count

Yes

Integer

The total number of queried records.
Table 4 Data structure of the instances field

Name

Mandatory

Type

Description

id

Yes

String

The DB instance ID.

name

Yes

String

The DB instance name.

remark

Yes

String

Instance remarks

status

Yes

String

The DB instance status.

Valid value:

  • normal: indicates that the instance is running properly.
  • abnormal: indicates that the instance is abnormal.
  • creating: indicates that the instance is being created.
  • frozen: indicates that the instance is frozen.
  • data_disk_full: The storage space is full.
  • createfail: indicates that the instance failed to be created.
  • enlargefail: indicates that nodes failed to be added to the instance.
NOTE:

Actions that are being executed on an instance, for example, rebooting, are essentially different from the instance status. For details, see the actions field in this table.

port

Yes

String

The database port. The port range is 2100 to 9500.

mode

Yes

String

The instance type, which is the same as the request parameter.

region

Yes

String

The region where the DB instance is deployed.

datastore

Yes

Object

The database information.

For more information, see Table 5.

engine

Yes

String

The storage engine. DDS supports the WiredTiger and RocksDB storage engines.

  • If the database version is 4.2 or later, the storage engine is RocksDB and the value is rocksDB.
  • If the database version is 4.0 or 3.4, the storage engine is WiredTiger and the value is wiredTiger.

created

Yes

String

The DB instance creation time.

updated

Yes

String

The time when a DB instance is updated.

db_user_name

Yes

String

The default username. The value is rwuser.

ssl

Yes

Integer

Whether SSL is enabled.

  • 1: indicate that SSL is enabled.
  • 0: indicate that SSL is disabled.

vpc_id

Yes

String

The VPC ID.

subnet_id

Yes

String

The network ID of the subnet.

security_group_id

Yes

String

Security group ID list. If an instance is associated with multiple security groups, use commas (,) to separate multiple security group IDs.

backup_strategy

Yes

Object

The backup policy.

For more information, see Table 6.

pay_mode

No

String

The billing mode.

  • 0: indicates the pay-per-use billing mode.
  • 1: indicates the yearly/monthly billing mode.

maintenance_window

Yes

String

The maintenance time window.

groups

Yes

Array of objects

Group information.

For more information, see Table 7.

disk_encryption_id

Yes

String

The disk encryption key ID. This parameter is returned only when the instance disk is encrypted.

enterprise_project_id

Yes

String

Enterprise project ID.

If the value is 0, the resource belongs to the default enterprise project.

time_zone

Yes

String

The time zone.

dss_pool_id

No

String

The DSS storage pool ID of the DeC user.

actions

Yes

Array of strings

Action that is being executed on an instance.

Valid value:

  • RESTARTING: The instance is being restarted.
  • RESTORE: The instance is being restored.
  • RESIZE_FLAVOR: The specifications are being changed.
  • RESTORE_TO_NEW_INSTANCE: The instance is being restored.
  • MODIFY_VPC_PEER: Cross-subnet access is being configured.
  • CREATE: The instance is being created.
  • FROZEN: The instance is frozen.
  • RESIZE_VOLUME: The storage is being scaled up.
  • RESTORE_CHECK: The restoration is being checked.
  • RESTORE_FAILED_HANGUP: The restoration failed.
  • CLOSE_AUDIT_LOG: The audit policy is being disabled.
  • OPEN_AUDIT_LOG: The audit policy is being enabled.
  • PERIOD_RESOURCE_SPEC_CHG: The yearly/monthly resource changes are being checked.
  • CREATE_IP_SHARD: The shard IP address is being enabled.
  • CREATE_IP_CONFIG: The config IP address is being enabled.
  • GROWING: The node is being scaled up.
  • SET_CONFIGURATION: Parameters are being modified.
  • RESTORE_TABLE: The table is being restored.
  • MODIFY_SECURITYGROUP: A security group is being changed.
  • BIND_EIP: The EIP is being changed.
  • UNBIND_EIP: The EIP is being unbound.
  • SWITCH_SSL: The SSL is being switched.
  • SWITCH_PRIMARY: A primary/standby switchover is being performed.
  • CHANGE_DBUSER_PASSWORD: The password is being changed.
  • MODIFY_PORT: The port is being changed.
  • MODIFY_IP: The private IP address is being changed.
  • DELETE_INSTANCE: The instance is being deleted.
  • REBOOT: The instance is being restarted.
  • BACKUP: The backup is in progress.
  • MIGRATE_AZ: The AZ is being changed.
  • PWD_RESETING: The password is being reset.
  • UPGRADE_DATABASE: The patch is being upgraded.
  • DATA_MIGRATION: Data is being migrated.
  • SHARD_GROWING: The shard is being scaled out.
  • APPLY_CONFIGURATION: A parameter group is being changed.
  • RESET_PASSWORD: The password is being reset.
  • GROWING_REVERT: Nodes are being deleted.
  • SHARD_GROWING_REVERT: Shards are being deleted.
  • ONDEMAND_TO_PERIOD: The billing mode is being changed to yearly/monthly.
  • LOG_PLAINTEXT_SWITCH: The slow query log configuration is being modified.
  • CREATE_DATABASE_USER: The database user is being created.
  • CREATE_DATABASE_ROLE: The database role is being created.
  • MODIFY_NAME: The name is being changed.
  • MODIFY_PRIVATE_DNS: The private zone is being modified.
  • MODIFY_OP_LOG_SIZE: The oplog size is being changed.
  • ADD_READONLY_NODES: Read replicas are being scaled up.

order_id

No

String

Order ID, which is returned only when an instance is billed on a yearly/monthly basis.

tags

Yes

Array of objects

Tag list

For details, see Table 10.
Table 5 Data structure of the datastore field

Name

Mandatory

Type

Description

type

Yes

String

The DB engine.

version

Yes

String

The database version. Versions 5.0, 4.4, 4.2, 4.0, and 3.4 are supported. The value can be 5.0, 4.4, 4.2, 4.0, or 3.4.

whole_version

Yes

String

Complete version number.

patch_available

Yes

Boolean

Whether there is an available patch for upgrade. If true is returned, you can install the patch to upgrade the instance.
Table 6 backup_strategy field data structure description

Name

Mandatory

Type

Description

start_time

Yes

String

The backup time window. Automated backups will be triggered during the backup time window. The current time is the UTC time.

keep_days

Yes

Integer

The number of days to retain the generated backup files. The value range is from 0 to 732.
Table 7 groups field data structure description

Name

Mandatory

Type

Description

type

Yes

String

The node type.

Valid value:
  • shard
  • config
  • mongos
  • replica
  • single
  • readonly

id

Yes

String

The group ID. This parameter is valid only when the node type is set to shard, config, or readonly.

name

Yes

String

The group name. This parameter is valid only when the node type is set to shard, config, or readonly.

status

Yes

String

The group status. This parameter is valid only when the node type is set to shard, config, or readonly.

volume

Yes

Object

The volume information. For more information, see Table 8. This parameter is valid only when the node type is set to shard, config, or replica.

nodes

Yes

Array of objects

The node information. For more information, see Table 9.
Table 8 Data structure description of the volume field

Name

Mandatory

Type

Description

size

Yes

String

The disk size. Unit: GB

used

Yes

String

The disk usage. Unit: GB
Table 9 nodes field data structure description

Name

Mandatory

Type

Description

id

Yes

String

The node ID.

name

Yes

String

The node name.

status

Yes

String

The node status.

role

Yes

String

The node role.

Valid value:
  • master: This value is returned for the mongos node.
  • Primary: This value is returned for the primary shard and config nodes, and the primary node of a replica set.
  • Secondary: This value is returned for the secondary shard and config nodes, and the secondary node of a replica set.
  • Hidden: This value is returned for the hidden shard and config nodes, and the hidden node of a replica set.
  • unknown. This value is returned when the node is abnormal.

private_ip

Yes

String

The private IP address of a node. By default, this parameter is valid only for mongos nodes and replica set instances. The value exists after the ECS is created successfully. Otherwise, the value is "".

CAUTION:

After the shard or config IP address is enabled, private IP addresses are assigned to the primary and secondary shard or config nodes of the cluster instance.

public_ip

Yes

String

The EIP that has been bound. This parameter is valid only for mongos nodes of cluster instances and the primary and secondary nodes of replica set instances.

spec_code

Yes

String

The resource specification code. For details about the instance specifications, see the value of the flavors.spec_code parameter in Querying Database Specifications.

availability_zone

Yes

String

AZ.
Table 10 Description of the tag field

Name

Mandatory

Type

Description

key

Yes

String

Tag key

value

Yes

String

Tag value

The values of region and availability_zone are used as examples.

Example Requests

  • Querying all instances and details 
    https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances
  • Querying instances and details based on search criteria 
    https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances?offset=0&limit=10&id=ed7cc6166ec24360a5ed5c5c9c2ed726in02&name=hy&mode=ReplicaSet&datastore_type=DDS-Community&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7&tags=key1=value1,key2=value2

Example Responses

{
  "instances": [
    {
      "id": "8436a91546294036b75931e879882200in02",
      "name": "dds-efa6",
      "remark": "test",
      "status": "normal",
      "port": "8635",
      "mode": "ReplicaSet",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:05:52",
      "updated": "2019-01-17T07:05:47",
      "db_user_name": "rwuser",
      "ssl": 1,
      "vpc_id": "674e9b42-cd8d-4d25-a2e6-5abcc565b961",
      "subnet_id": "f1df08c5-71d1-406a-aff0-de435a51007b",
      "security_group_id": "7aa51dbf-5b63-40db-9724-dad3c4828b58",
      "backup_strategy": {
        "start_time": "16:00-17:00",
        "keep_days": 7
      },
      "pay_mode": 0,
      "maintenance_window": "02:00-06:00",
      "groups": [{
        "type": "replica",
        "volume": {
          "size": "10",
          "used": "0.33"
        },
        "nodes": [
          {
            "id": "233eaac9c6f245c0bb9c2d21eea12d1bno02",
            "name": "dds-efa6_replica_node_2",
            "status": "normal",
            "role": "Primary",
            "private_ip": "192.168.0.174",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          },
          {
            "id": "d57d76d6320a4a7b86db82c317550c4ano02",
            "name": "dds-efa6_replica_node_1",
            "status": "normal",
            "role": "Hidden",
            "private_ip": "192.168.0.39",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          },
          {
            "id": "f46b0a1cf4d9400e9fd7af17f8742d37no02",
            "name": "dds-efa6_replica_node_3",
            "status": "normal",
            "role": "Secondary",
            "private_ip": "192.168.0.176",
            "public_ip": "",
            "spec_code": "dds.s2.medium.4.shard",
            "availability_zone": "bbb"
          }
        ]
      }],
      "enterprise_project_id": "0",
      "time_zone": "",
      "dss_pool_id": "f5f84ed7-6f19-4bd4-99d7-b450ad6cc4dd",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    },
    {
      "id": "d77905385f114217b75ae7d6ab9a7588in02",
      "name": "dds-5699",
      "status": "normal",
      "remark": "Test",
      "port": "8635",
      "mode": "Single",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:04:39",
      "updated": "2019-01-17T07:04:33",
      "db_user_name": "rwuser",
      "ssl": 1,
      "vpc_id": "674e9b42-cd8d-4d25-a2e6-5abcc565b961",
      "subnet_id": "f1df08c5-71d1-406a-aff0-de435a51007b",
      "security_group_id": "7aa51dbf-5b63-40db-9724-dad3c4828b58",
      "backup_strategy": {
        "start_time": "17:00-18:00",
        "keep_days": 7
      },
      "pay_mode": 0,
      "maintenance_window": "02:00-06:00",
      "groups": [{
        "type": "single",
        "volume": {
          "size": "10",
          "used": "0.33"
        },
        "nodes": [
          {
            "id": "bd4dccbd53ae48d5bd3046bebf715079no02",
            "name": "dds-5699_single_node_1",
            "status": "normal",
            "role": "Primary",
            "private_ip": "192.168.0.9",
            "public_ip": "",
            "spec_code": "dds.mongodb.c6.medium.4.single",
            "availability_zone": "bbb"
          }
        ]
      }],
      "enterprise_project_id": "0",
      "time_zone": "",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    },
    {
      "id": "9136fd2a9fcd405ea4674276ce36dae8in02",
      "name": "dds-32f4",
      "remark": 123,
      "status": "normal",
      "port": "8635",
      "mode": "Sharding",
      "region": "cn-xianhz-1",
      "datastore": {
        "type": "DDS-Community",
        "version": "3.4",
        "patch_available": false
      },
      "engine": "wiredTiger",
      "created": "2019-01-17T07:04:37",
      "updated": "2019-01-17T07:04:31",
      "db_user_name": "rwuser",
      "ssl": 1,
      "vpc_id": "674e9b42-cd8d-4d25-a2e6-5abcc565b961",
      "subnet_id": "f1df08c5-71d1-406a-aff0-de435a51007b",
      "security_group_id": "7aa51dbf-5b63-40db-9724-dad3c4828b58",
      "backup_strategy": {
        "start_time": "19:00-20:00",
        "keep_days": 7
      },
      "pay_mode": 0,
      "maintenance_window": "02:00-06:00",
      "groups": [
        {
          "type": "mongos",
          "nodes": [
            {
              "id": "a742c13a284949adad177672e8a0f01cno02",
              "name": "dds-32f4_mongos_node_1",
              "status": "normal",
              "role": "Primary",
              "private_ip": "192.168.0.56",
              "public_ip": "",
              "spec_code": "dds.mongodb.c6.medium.4.mongos",
              "availability_zone": "bbb"
            },
            {
              "id": "d4f66666b1d64ab28719da0526341c7eno02",
              "name": "dds-32f4_mongos_node_2",
              "status": "normal",
              "role": "Primary",
              "private_ip": "192.168.0.185",
              "public_ip": "",
              "spec_code": "dds.mongodb.c6.medium.4.mongos",
              "availability_zone": "bbb"
            }
          ]
        },
        {
          "type": "shard",
          "volume": {
            "size": "10",
            "used": "0.33"
          },
          "nodes": [
            {
              "id": "0e9abaebe5974b63a5b221de6ee34cfeno02",
              "name": "dds-32f4_shard_2_node_3",
              "status": "normal",
              "role": "Primary",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            },
            {
              "id": "1d7f4c5476c04cc187f920925c2b601fno02",
              "name": "dds-32f4_shard_2_node_2",
              "status": "normal",
              "role": "Hidden",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            },
            {
              "id": "3dd2cce03da54fc08f10651cbfea778dno02",
              "name": "dds-32f4_shard_2_node_1",
              "status": "normal",
              "role": "Secondary",
              "spec_code": "dds.mongodb.c6.medium.4.shard",
              "availability_zone": "bbb"
            }
          ]
        },
        {
          "type": "config",
          "volume": {
            "size": "10",
            "used": "0.33"
          },
          "nodes": [
            {
              "id": "7422f7331b714ac39aa647a1ec968d33no02",
              "name": "dds-32f4_config_node_2",
              "status": "normal",
              "role": "Primary",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            },
            {
              "id": "9e3b343151044eda91ddb8a42ae5cbefno02",
              "name": "dds-32f4_config_node_3",
              "status": "normal",
              "role": "Hidden",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            },
            {
              "id": "c0053ca460ac4889841ffb14a886ec54no02",
              "name": "dds-32f4_config_node_1",
              "status": "normal",
              "role": "Secondary",
              "spec_code": "dds.mongodb.c6.large.2.config",
              "availability_zone": "bbb"
            }
          ]
        }
      ],
      "enterprise_project_id": "0",
      "time_zone": "",
      "actions": [
        "CREATE"
      ],
      "tags": [
        {
          "key": "dds001",
          "value": "dds001"
        }
      ]
    }
  ],
  "total_count": 3
}

Status Code

For more information, see Status Code.

Error Code

For more information, see Error Code.

Parent topic: DB Instance Management