Help Center/ GeminiDB/ API Reference/ API v3/ Instances/ Querying Instances and Details

Updated on 2026-09-22 GMT+08:00

Querying Instances and Details

Function

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

Constraints

This API supports the following instances:

GeminiDB Cassandra
GeminiDB Influx
GeminiDB Redis
GeminiDB HBase
GeminiDB DynamoDB-Compatible

Authorization Information

Each account has permissions to call all APIs, but IAM users must have the required permissions specifically assigned.

If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.
If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

gaussdbfornosql:instance:list

Read

-

-

nosql:backup:list

-

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
gaussdbfornosql:instance:list	Read	-	-	nosql:backup:list	-

URI

GET /v3/{project_id}/instances

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID. Constraints N/A Range The value contains 32 characters. Only letters and digits are allowed. Default Value N/A

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
id	No	String	Definition Instance ID Constraints If you enter an instance ID starting with an asterisk (), fuzzy search results are returned. If you enter a valid instance ID, an exact result is returned. Range* N/A Default Value N/A
name	No	String	Definition Instance name Constraints If you enter an instance name starting with an asterisk (), fuzzy search results are returned. If you enter a valid instance name, an exact result is returned. Range* N/A Default Value N/A
datastore_type	No	String	Definition Database type Constraints N/A Range cassandra: GeminiDB Cassandra instances are queried. mongodb: GeminiDB Mongo instances are queried. influxdb: GeminiDB Influx instances are queried. redis: GeminiDB Redis instances are queried. dynamodb: GeminiDB DynamoDB-Compatible instances are queried. hbase: GeminiDB HBase instances are queried. Default Value If this parameter is not transferred, all types of instances are queried.
mode	No	String	Definition Instance type Constraints The system ignores this parameter if datastore_type is not transferred. Range Cluster: GeminiDB Cassandra cluster instance with classic storage CloudNativeCluster: GeminiDB Cassandra cluster instance with cloud native storage Cluster: GeminiDB Influx cluster instance with classic storage CloudNativeCluster: GeminiDB Influx cluster (performance-enhanced) instance with cloud native storage EnhancedCluster: GeminiDB Influx cluster (performance-enhanced) instance with classic storage InfluxdbSingle: single-node GeminiDB Influx instance Cluster: proxy cluster GeminiDB Redis instance with classic storage CloudNativeCluster: GeminiDB Redis cluster instance with cloud native storage RedisCluster: Redis Cluster GeminiDB Redis instance with classic storage. For more information about the Redis Cluster GeminiDB Redis instance, see Creating an Instance. Replication: primary/standby GeminiDB Redis instance with classic storage Cluster: GeminiDB DynamoDB-Compatible cluster instance with classic storage CloudNativeCluster: GeminiDB DynamoDB-Compatible cluster instance with cloud native storage Cluster: GeminiDB HBase cluster instance with classic storage CloudNativeCluster: GeminiDB HBase cluster instance with cloud native storage ReplicaSet: GeminiDB Mongo instance in a replica set Default Value N/A
vpc_id	No	String	Definition VPC ID. You can obtain the value with either of the following methods: Method 1: Log in to the VPC console and find the VPC ID on the VPC details page. Method 2: Query the VPC ID using the VPC API. For details, see Querying VPCs. Constraints N/A Range N/A Default Value N/A
subnet_id	No	String	Definition Subnet ID. You can obtain the subnet ID with either of the following methods: Method 1: Log in to the VPC console, click a subnet under the VPC, and find the network ID on the subnet details page. Method 2: Query the subnet ID using the VPC API. For details, see Querying Subnets. Constraints N/A Range N/A Default Value N/A
offset	No	Integer	Definition 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. Constraints N/A Range The value must be no less than 0. Default Value If this parameter is not transferred, the index offset is 0 by default, indicating that the query starts from the latest created instance.
limit	No	Integer	Definition Maximum number of instances that can be queried. Constraints N/A Range 1 to 100 Default Value If this parameter is not transferred, the first 100 instances are queried by default.

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token You can obtain the token by calling the IAM API by following Obtaining a User Token Through Password Authentication. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
instances	Array of ListInstancesResult objects	Definition Instance information.
total_count	Integer	Definition Total number of records. Range N/A

**Table 5** ListInstancesResult
Parameter	Type	Description
id	String	Definition Instance ID Range N/A
name	String	Definition Instance name Range N/A
status	String	Definition Instance status Range normal: An instance is available. abnormal: An instance is abnormal. creating: An instance is being created. frozen: An instance is frozen. data_disk_full: An instance disk is full. createfail: An instance failed to be created. enlargefail: Instance nodes failed to be added.
port	String	Definition Database port Range N/A
mode	String	Definition Instance type Range This parameter is the same as the corresponding request parameter.
product_type	String	Definition Product type used for GeminiDB Redis instances with cloud native storage Range Capacity: capacity-oriented Performance: performance-enhanced
region	String	Definition Region where an instance is deployed Range N/A
datastore	ListInstancesDatastoreResult object	Definition Database information
engine	String	Definition Storage engine Range rocksDB
created	String	Definition Instance creation time Range N/A
updated	String	Definition Time when an instance is updated Range N/A
db_user_name	String	Definition Default username Range rwuser
vpc_id	String	Definition VPC ID Range N/A
subnet_id	String	Definition Subnet ID Range One GeminiDB Cassandra instance may use multiple subnets. For the subnet ID, see Table 11.
security_group_id	String	Definition Security group ID Range N/A
backup_strategy	ListInstancesBackupStrategyResult object	Definition Backup policy
pay_mode	String	Definition Billing mode Range 0: The instance is billed on a pay-per-use basis. 1: The instance is billed on a yearly/monthly basis.
maintenance_window	String	Definition Maintenance time window Range N/A
backup_space_usage	Table 6 object	Definition Backup space usage.
groups	Array of ListInstancesGroupResult objects	Definition Group information
enterprise_project_id	String	Definition Enterprise project ID Range 0: default enterprise project
time_zone	String	Definition Time zone Range N/A
actions	Array of strings	Definition Actions that are being executed on an instance CREATE: The instance is being created. REBOOT: The instance is being restarted. RESTORE: The instance is being restored.
dedicated_resource_id	String	Definition Dedicated resource ID. This parameter is returned only when the instance belongs to a dedicated resource pool. Range N/A
disk_encryption_id	String	Definition Key ID used for disk encryption Range N/A
lb_ip_address	String	Definition Load balancer IP address Range N/A
lb_port	String	Definition Load balancer port Range N/A
availability_zone	String	Definition AZ Range N/A
dr_instance_id	String	Definition DR instance ID Range N/A
dual_active_info	DualActiveInfo object	Definition Active-active instance information
ccm_cert_info	CertInfoOption object	Definition CCM certificate information If this parameter is not specified after SSL is enabled, the default certificate is used.
ssl	String	Definition Whether SSL connection is enabled Range 0: disabled 1: enabled

**Table 6** ListInstancesBackupSpaceUsageResult
Parameter	Type	Description
backup_usage	Long	Definition Used backup space in KB. Range N/A

**Table 7** ListInstancesDatastoreResult
Parameter	Type	Description
type	String	Definition Database API Range cassandra: GeminiDB Cassandra instance mongodb: GeminiDB Mongo instance influxdb: GeminiDB Influx instance redis: GeminiDB Redis instance
version	String	Definition Database version Range N/A
patch_available	Boolean	Definition Whether the current instance can be patched Range true: A database can be upgraded through a patching API. false: A database cannot be upgraded through a patching API.
whole_version	String	Definition Whole version of a GeminiDB Cassandra and Redis instance Range N/A

**Table 8** ListInstancesBackupStrategyResult
Parameter	Type	Description
start_time	String	Definition Backup time window. Automated backup will be triggered during the backup time window. The current time is the UTC time. Range N/A
keep_days	Integer	Definition Backup retention days Range 0–35

**Table 9** ListInstancesGroupResult
Parameter	Type	Description
id	String	Definition Group ID Range N/A
status	String	Definition Group status Range normal: A group is normal. abnormal: A group is abnormal. creating: A group is being created. createfail: A group failed to be created. deleted: A group is deleted. resizefailed: The group specifications failed to be modified. enlargefail: A group failed to be scaled out.
volume	Volume object	Definition Volume information
nodes	Array of ListInstancesNodeResult objects	Definition Node information

**Table 10** Volume
Parameter	Type	Description
size	String	Definition Storage (GB) Range N/A
used	String	Definition Used storage (GB) Range N/A
gift_size	String	Definition Free storage space in GB. Range N/A

**Table 11** ListInstancesNodeResult
Parameter	Type	Description
id	String	Definition Node ID Range N/A
name	String	Definition Node name Range N/A
status	String	Definition Node status Range normal: A node is normal. abnormal: A node is abnormal. creating: A node is being created. createfail: A node failed to be created. deleted: A node is deleted. resizefailed: Node specifications failed to be changed. enlargefail: Nodes failed to be added.
role	String	Definition Node role. This parameter is available only for GeminiDB Mongo API replica set instances. Range N/A
subnet_id	String	Definition ID of the subnet where the instance node is deployed Range N/A
private_ip	String	Definition Private IP address of a node This parameter value is available after an ECS is created. Otherwise, the value is "". Range N/A
public_ip	String	Definition Bound EIP This parameter is valid only for nodes bound with EIPs. Range N/A
spec_code	String	Definition Resource specification code. For the code, see the value of parameter flavors.spec_code in Querying Instance Specifications. Range N/A
availability_zone	String	Definition AZ Range N/A
support_reduce	Boolean	Definition Whether instance nodes can be deleted Range true: Instance nodes can be deleted. false: Instance nodes cannot be deleted.

**Table 12** DualActiveInfo
Parameter	Type	Description
role	String	Definition Active-active role Range N/A
status	String	Definition Active-active status Range normal: The active-active status is normal. abnormal: The active-active status is abnormal.
destination_instance_id	String	Definition ID of the peer instance in the active-active pair. Range N/A
destination_region	String	Definition Peer region of the active-active pair Range N/A
destination_instance_name	String	Definition Name of the peer instance in the active-active pair Range N/A
destination_instance_node_num	Integer	Definition Number of nodes in the peer instance in the active-active pair Range N/A
destination_instance_spec_code	String	Definition Specifications of the peer instance in the active-active pair Range N/A

**Table 13** CertInfoOption
Parameter	Type	Description
cert_id	String	Definition Certificate ID, which can be obtained by calling the API for querying CCM certificates. Range N/A
cert_type	String	Definition Certificate type Range PCA: CCM PCA certificate SSL: CCM SSL certificate

Example Requests

Querying all instances and details

GET https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances

Querying instances and details based on specified conditions

GET https://{Endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/instances?offset=0&limit=10&id=ed7cc6166ec24360a5ed5c5c9c2ed726in06&name=hy&mode=Cluster&datastore_type=cassandra&vpc_id=19e5d45d-70fd-4a91-87e9-b27e71c9891f&subnet_id=bd51fb45-2dcb-4296-8783-8623bfe89bb7

Example Responses

Status code: 200

Success

Scenarios without DR and active-active instances

{
  "instances" : [ {
    "id" : "8436a91546294036b75931e879882200in06",
    "name" : "nosql-efa6",
    "status" : "normal",
    "port" : "8635",
    "mode" : "Cluster",
    "region" : "aaa",
    "datastore" : {
      "type" : "cassandra",
      "version" : "3.11",
      "whole_version" : "3.11.3.11204", 
      "patch_available" : false
    },
    "engine" : "rocksDB",
    "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" : [ {
      "id" : "0b0ff12541794e1084f6827e424be2d6gr06",
      "status" : "creating",
      "volume" : {
        "size" : "10",
        "used" : "0.33"
      },
      "nodes" : [ {
        "id" : "233eaac9c6f245c0bb9c2d21eea12d1bno06",
        "name" : "nosql-efa6_priam_node_1",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.174",
        "spec_code" : "geminidb.redis.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "d57d76d6320a4a7b86db82c317550c4ano06",
        "name" : "nosql-efa6_priam_node_2",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.175",
        "spec_code" : "geminidb.redis.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "f46b0a1cf4d9400e9fd7af17f8742d37no06",
        "name" : "nosql-efa6_priam_node_3",
        "status" : "normal",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.176",
        "spec_code" : "geminidb.redis.xlarge.4",
        "availability_zone" : "bbb"
      } ]
    } ],
      "enterprise_project_id" : "0",
      "availability_zone": "cn-north-4a,cn-north-4b,cn-north-4c",
      "time_zone" : "",
      "actions" : [ "CREATE" ],
      "lb_ip_address" : "192.168.11.145",
      "lb_port" : "8635"
  }, {
    "id" : "1236a91546294036b75931e879882200in02",
    "name" : "nosql-efa7",
    "status" : "normal",
    "port" : "8635",
    "mode" : "ReplicaSet",
    "region" : "aaa",
    "datastore" : {
      "type" : "mongodb",
      "version" : "4.0",
      "patch_available" : false
    },
    "engine" : "rocksDB",
    "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" : [ {
      "id" : "0b0ff12541794e1084f6827e424be2d1gr02",
      "status" : "normal",
      "volume" : {
        "size" : "100",
        "used" : "0.003"
      },
      "nodes" : [ {
        "id" : "233eaac9c6f245c0bb9c2d21eea12d1bno02",
        "name" : "nosql-efa7_replica_node_2",
        "status" : "normal",
        "role" : "Primary",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.174",
        "public_ip" : "10.154.217.134",
        "spec_code" : "geminidb.mongodb.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "d57d76d6320a4a7b86db82c317550c4ano02",
        "name" : "nosql-efa7_replica_node_1",
        "status" : "normal",
        "role" : "Secondary",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.39",
        "spec_code" : "geminidb.mongodb.xlarge.4",
        "availability_zone" : "bbb"
      }, {
        "id" : "f46b0a1cf4d9400e9fd7af17f8742d37no02",
        "name" : "nosql-efa7_replica_node_3",
        "status" : "normal",
        "role" : "Secondary",
        "subnet_id" : "f1df08c5-71d1-406a-aff0-de435a51007b",
        "private_ip" : "192.168.0.176",
        "spec_code" : "geminidb.mongodb.xlarge.4",
        "availability_zone" : "bbb"
      } ]
    } ],
      "enterprise_project_id" : "0", 
      "availability_zone": "cn-north-4a,cn-north-4b,cn-north-4c",
      "time_zone" : "",
      "actions" : [ ]
  } ],
  "total_count" : 2
}

Scenarios with DR and active-active instances

{
    "instances": [
        {
            "id": "e3cb7981fab74fa3aa930333e8c12a7cin06",
            "name": "geminidb-78a2-gsm-master",
            "status": "normal",
            "port": "8635",
            "mode": "CloudNativeCluster",
            "region": "cn-southwest-244",
            "datastore": {
                "type": "cassandra",
                "version": "3.11",
                "patch_available": false,
                "whole_version": null
            },
            "engine": "rocksDB",
            "created": "2026-03-06T09:30:52",
            "updated": "2026-03-10T13:20:28",
            "db_user_name": "rwuser",
            "ssl" : "1", 
            "vpc_id": "f457aa28-72de-42b8-8517-d9c6e14b9d09",
            "subnet_id": "c0650bbe-4c89-4f2a-8cd2-3e2171b96d99",
            "security_group_id": "17157fcb-8357-4ea5-9619-c07cb1610334",
            "backup_strategy": {
                "start_time": "19:00-20:00",
                "keep_days": 7
            },
            "pay_mode": "0",
            "maintenance_window": "02:00-06:00",
            "backup_space_usage": {
                "backup_usage": 65965656
            },
            "groups": [
                {
                    "id": "0b0d3c0cbfd941a182ca3676cc4b7f37gr06",
                    "status": "normal",
                    "volume": {
                        "size": "10",
                        "used": "0.004",
                        "gift_size": "0"
                    },
                    "nodes": [
                        {
                            "id": "ad92f186b46543bd961c4ae14180d3d7no06",
                            "name": "geminidb-78a2-gsm-master_g9tv_priam_node_3",
                            "status": "normal",
                            "subnet_id": "c0650bbe-4c89-4f2a-8cd2-3e2171b96d99",
                            "private_ip": "192.168.192.66",
                            "spec_code": "geminidb.cassandra-geminifs.large.4",
                            "availability_zone": "cn-southwest-244d",
                            "support_reduce": false
                        },
                        {
                            "id": "cca92a2ea84a49b6a30d5b9b8f64e053no06",
                            "name": "geminidb-78a2-gsm-master_g9tv_priam_node_2",
                            "status": "normal",
                            "subnet_id": "c0650bbe-4c89-4f2a-8cd2-3e2171b96d99",
                            "private_ip": "192.168.135.148",
                            "spec_code": "geminidb.cassandra-geminifs.large.4",
                            "availability_zone": "cn-southwest-244c",
                            "support_reduce": false
                        },
                        {
                            "id": "fa083404f965476b97ce73c76930db5fno06",
                            "name": "geminidb-78a2-gsm-master_g9tv_priam_node_1",
                            "status": "normal",
                            "subnet_id": "c0650bbe-4c89-4f2a-8cd2-3e2171b96d99",
                            "private_ip": "192.168.240.254",
                            "spec_code": "geminidb.cassandra-geminifs.large.4",
                            "availability_zone": "cn-southwest-244b",
                            "support_reduce": false
                        }
                    ]
                }
            ],
            "enterprise_project_id": "0",
            "time_zone": "",
            "actions": [],
            "availability_zone": "cn-southwest-244b,cn-southwest-244c,cn-southwest-244d",
            "ccm_cert_info": {},
            "dr_instance_id": "7a0c5367976f4188aa17d70528a7b386in06",
            "dual_active_info": {
                "status": "normal",
                "destination_region": "cn-southwest-244",
                "destination_instance_id": "be3eaef8555442a399046fd8ac02c392in06",
                "destination_instance_name": "geminidb-8779-gsm-biactive",
                "destination_instance_node_num": 2,
                "destination_instance_spec_code": "geminidb.cassandra-geminifs.large.4"
            }
        }
    ],
    "total_count": 1
}

Status Codes

For details, see Status Codes.

Error Codes

For details, see Error Codes.

Parent topic: Instances

Previous topic: Deleting an Instance

Next topic: Scaling Up Storage Space of an Instance