Updated on 2025-07-11 GMT+08:00

Querying DB Instances

Function

This API is used to query DB instances based on specified criteria. Before calling this API:

URI

GET /v3.1/{project_id}/instances

Table 1 URI parameter

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:

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, exact match is performed based on the instance ID. The value cannot contain only asterisks (*).

Range:

N/A

Default value:

N/A

name

No

String

Definition:

Instance name.

Constraints:

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, exact match is performed based on the instance name. The value cannot contain only asterisks (*).

Range:

N/A

Default value:

N/A

type

No

String

Definition:

Instance type.

Constraints:

Currently, only the cluster type is supported.

Range:

Cluster

Default value:

Cluster

datastore_type

No

String

Definition:

Database type.

Constraints:

Only gaussdb-mysql is supported.

Range:

gaussdb-mysql

Default value:

gaussdb-mysql

vpc_id

No

String

Definition:

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

  • Method 1: Log in to the VPC console and view the VPC ID on the VPC details page.

Constraints:

N/A

Range:

N/A

Default value:

N/A

subnet_id

No

String

Definition:

Subnet ID. To obtain this 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 subnet ID on the displayed page.

Constraints:

N/A

Range:

N/A

Default value:

N/A

private_ip

No

String

Definition:

Private IP address.

Constraints:

N/A

Range:

N/A

Default value:

N/A

readonly_private_ip

No

String

Definition:

Private IP address for read.

Constraints:

N/A

Range:

N/A

Default value:

N/A

proxy_ip

No

String

Definition:

Proxy IP address.

Constraints:

N/A

Range:

N/A

Default value:

N/A

offset

No

Integer

Definition:

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

Constraints:

The value cannot be a negative number.

Range:

≥ 0

Default value:

0

limit

No

Integer

Definition:

Number of records to be queried.

Constraints:

The value cannot be a negative number.

Range:

1–100

Default value:

100

tags

No

String

Definition:

Tag key–value pairs of the instance.

  • {key} indicates the tag key.

  • {value} indicates the tag value.

Constraints:

To query instances with multiple tag keys and values, separate key-value pairs with commas (,). The key must be unique. Multiple keys are in AND relationship.

Range:

N/A

Default value:

N/A

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition:

User token. To obtain this value, call the IAM API for obtaining a user token.

The value of X-Subject-Token in the response header is the token value.

Constraints:

N/A

Range:

N/A

Default value:

N/A

X-Language

No

String

Definition:

Request language type.

Constraints:

N/A

Range:

  • en-us

  • zh-cn

Default value:

en-us

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

instances

Array of MysqlInstanceListInfoUnifyStatus objects

Definition:

Instance list.

total_count

Integer

Definition:

Total number of records.

Range:

N/A

Table 5 MysqlInstanceListInfoUnifyStatus

Parameter

Type

Description

id

String

Definition:

Instance ID.

Range:

The value contains 36 characters with a suffix of in07. Only letters and digits are allowed.

name

String

Definition:

Instance name.

Range:

N/A

status

String

Definition:

Instance status.

Range:

  • creating: An instance is being created.

  • normal: An instance is available.

  • abnormal: An instance is abnormal.

  • createfail: An instance failed to be created.

private_ips

Array of strings

Definition:

Private IP addresses for write of instances. This parameter is left blank until an ECS is created.

Range:

N/A

proxy_ips

Array of strings

Definition:

Proxy IP addresses. This parameter is left blank until proxy instances are created for a DB instance.

Range:

N/A

readonly_private_ips

Array of strings

Definition:

Private IP addresses for read of instances. This parameter is left blank until an ECS is created.

Range:

N/A

public_ips

Array of strings

Definition:

Public IP addresses.

Range:

N/A

port

String

Definition:

Database port.

Range:

1024 to 65535, excluding 5342 to 5345, 12017, 20000, 20201, 20202, 33062, and 33071

type

String

Definition:

Instance type.

Range:

Cluster

region

String

Definition:

Region where an instance is deployed.

Range:

N/A

datastore

MysqlDatastoreWithKernelVersion object

Definition:

Database information.

created

String

Definition:

Creation time 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.

Range:

N/A

updated

String

Definition:

Update time 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.

Range:

N/A

db_user_name

String

Definition:

Default username.

Range:

N/A

vpc_id

String

Definition:

VPC ID.

Range:

N/A

subnet_id

String

Definition:

Subnet ID.

Range:

N/A

security_group_id

String

Definition:

Security group ID.

Range:

N/A

flavor_ref

String

Definition:

Specification code.

Range:

N/A

flavor_info

MysqlFlavorInfo object

Definition:

Flavor information.

Range:

N/A

volume

MysqlVolumeInfo object

Definition:

Storage disk information.

backup_strategy

MysqlBackupStrategy object

Definition:

Automated backup policy.

Constraints:

N/A

enterprise_project_id

String

Definition:

Enterprise project ID.

Range:

N/A

time_zone

String

Definition:

Time zone.

Range:

N/A

charge_info

MysqlChargeInfo object

Definition:

Billing mode, which is yearly/monthly or pay-per-use (default setting).

tags

Array of InstanceTagItem objects

Definition:

Tag list.

Table 6 MysqlDatastoreWithKernelVersion

Parameter

Type

Description

type

String

Definition:

DB engine.

Range:

gaussdb-mysql

version

String

Definition:

DB version.

Range:

N/A

Table 7 MysqlFlavorInfo

Parameter

Type

Description

vcpus

String

Definition:

Number of vCPUs.

Range:

N/A

ram

String

Definition:

Memory size, in GB.

Range:

N/A

Table 8 MysqlVolumeInfo

Parameter

Type

Description

type

String

Definition:

Disk type.

Range:

N/A

size

String

Definition:

Used disk size, in GB.

Range:

N/A

Table 9 MysqlBackupStrategy

Parameter

Type

Description

start_time

String

Definition:

Automated backup start time. An automated backup will be triggered within one hour after the time specified by this parameter.

Constraints:

N/A

Range:

The value cannot be empty. It must be a valid value in the "hh:mm-HH:MM" format. The current time is the UTC time.

  1. The HH value must be 1 greater than the hh value.

  2. The values of mm and MM must be the same and must be set to 00.

Default value:

N/A

keep_days

String

Definition:

Retention days of automated backups.

Constraints:

The value must be a positive integer.

Range:

1–732

Default value:

N/A

Table 10 MysqlChargeInfo

Parameter

Type

Description

charge_mode

String

Definition:

Billing mode.

Constraints:

N/A

Range:

  • prePaid: yearly/monthly

  • postPaid: pay-per-use

Default value:

postPaid

period_type

String

Definition:

Subscription period type in yearly/monthly mode.

Constraints:

This parameter is only valid and mandatory when charge_mode is set to prePaid.

Range:

  • month: The service is subscribed by month.

  • year: The service is subscribed by year.

Default value:

N/A

period_num

Integer

Definition:

Subscription period in yearly/monthly mode.

Constraints:

This parameter is only valid and mandatory when charge_mode is set to prePaid.

Range:

  • When period_type is set to month, the value range is 1 to 9.

  • When period_type is set to year, the value range is 1 to 3.

Default value:

N/A

is_auto_renew

String

Definition:

Whether automatic renewal is enabled for yearly/monthly instances. The renewal period is the same as the original period and the order will be automatically paid during the subscription renewal.

Constraints:

This parameter is only valid when charge_mode is set to prePaid.

Range:

  • true: Automatic renewal is enabled.

  • false: Automatic renewal is disabled.

Default value:

false

is_auto_pay

String

Definition:

Whether the order will be automatically paid after yearly/monthly instances are created. This parameter does not affect the payment method of automatic renewal.

Constraints:

This parameter is only valid when charge_mode is set to prePaid.

Range:

  • true: The order will be automatically paid.

  • false: The order will be manually paid.

Default value:

true

Table 11 InstanceTagItem

Parameter

Type

Description

key

String

Definition:

Tag key.

Range:

N/A

value

String

Definition:

Tag value.

Range:

N/A

Status code: 400

Table 12 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 13 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Request

Querying TaurusDB instances whose private IP addresses are 192.*.*.*

GET https://{endpoint}/v3.1/054e292c9880d4992f02c0196d3ea468/instances?id=61a4ea66210545909d74a05c27a7179ein07&name=gaussdb-mysql-instance01&type=Cluster&datastore_type=gaussdb-mysql&vpc_id=3cedfc54-b105-4652-a4e0-847b11576b58&subnet_id=c1cfa53c-65d3-431e-8552-326bf310c7ad&private_ip=192.*.*.*&offset=0&limit=10&tags=taurusKey1=value1

Example Response

Status code: 200

Success.

{
  "total_count" : 1,
  "instances" : [ {
    "id" : "61a4ea66210545909d74a05c27a7179ein07",
    "name" : "gaussdb-mysql-instance01",
    "status" : "normal",
    "port" : 3306,
    "type" : "Cluster",
    "private_ips" : [ "192.*.*.*" ],
    "readonly_private_ips" : [ "192.*.*.*", "192.*.*.*" ],
    "proxy_ips" : [ "192.*.*.*" ],
    "db_user_name" : "root",
    "region" : "region-1",
    "datastore" : {
      "type" : "gaussdb-mysql",
      "version" : "8.0",
     
    },
    "created" : "2018-08-20T02:33:49_0800",
    "updated" : "2018-08-20T02:33:49_0800",
    "volume" : {
      "type" : "POOL",
      "size" : 100
    },
    "vpc_id" : "3cedfc54-b105-4652-a4e0-847b11576b58",
    "subnet_id" : "c1cfa53c-65d3-431e-8552-326bf310c7ad",
    "security_group_id" : "fc577a1a-f202-424a-977f-24faec3fdd55",
    "flavor_ref" : "gaussdb.mysql.c3.small.4",
    "flavor_info" : {
      "vcpus" : 8,
      "ram" : 16
    },
    "backup_strategy" : {
      "start_time" : "19:00-20:00",
      "keep_days" : 7
    },
    "charge_info" : {
      "charge_mode" : "postPaid"
    },
    "enterprise_project_id" : 0,
    "time_zone" : "UTC",
    "tags" : [ {
      "key" : "Key1",
      "value" : "value1"
    } ]
  } ]
}

Status Code

Status Code

Description

200

Success.

400

Client error.

500

Server error.

Error Code

For details, see Error Codes.