DescribeInstances|OceanBase Cloud| docs|Distributed Database

DescribeInstances

Last Updated：2025-11-26 03:33:16 Updated

Overview

You can call this API to query the list of OceanBase clusters.

API details

Constraints

The caller must have an AccessKey for accessing APIs of OceanBase Cloud. For information about how to obtain the AccessKey ID and AccessKey secret, see Manage AccessKeys.

Request path

GET /api/v2/instances

Request parameters

Query

Parameter	Type	Required	Description	Example value
instanceName	String	No	The name of the cluster.	test
instanceId	String	No	The ID of the cluster.	ob677efwh8******
tagList	String	No	The tag list of the cluster.
pageNumber	Integer	No	The page number, which starts from 1.	1
pageSize	Integer	No	The number of records per page.	10

Body

Parameter	Type	Required	Description	Example value
None

Response parameters

Parameter	Type	Description	Example value
data	Object	The information about the clusters, including the dataList parameter.
dataList	Array	The list of information about the clusters, including the following parameters.
expireTime	String	The time at which the cluster expires.
managementMode	String	The management mode of the cluster. Valid value: DBaaS: the normal mode.	DBaaS
availableZones	Array	The number of available zones of the cluster.	["4"]
version	String	The version of OceanBase Database.	4.2.3
obRpmVersion	String	The detailed information about the OceanBase Database version.	4.2.3.0-100000232024042317
cloudProvider	String	The name of the cloud service provider. Valid values: ALIYUN: Alibaba Cloud. QCLOUD: Tencent Cloud. AWS: Amazon Web Services (AWS). AWSCN: AWS China. HUAWEI: Huawei Cloud. GCP: Google Cloud Platform.	QCLOUD
createTime	String	The time in UTC when the cluster was created.	2023-08-28T08:30:54Z
deployMode	String	The data replica distribution mode of the cluster. The integer n is the number of OBServer nodes in each IDC. n: the single-IDC mode. n-n: the dual-IDC mode. n-n-n: the multi-IDC mode.	1-1-1
deployType	String	The deployment type of the cluster. Valid values: multiple: multi-IDC deployment. single: single-IDC deployment. dual: dual-IDC deployment.	multiple
instanceClass	String	The specification of the cluster. The following specification plans are supported: 2C4GB 4C8GB 4C16GB 8C16GB 8C32GB 16C32GB 16C70GB 16C96GB 32C70GB 32C180GB 62C400GB 64C180GB 64C400GB	4C16G
instanceId	String	The ID of the OceanBase cluster.	ob5******
instanceName	String	The name of the OceanBase cluster.	ob******
instanceRole	String	The role of the OceanBase cluster.	NORMAL
instanceType	String	The type of the cluster. Valid values: DEDICATED: a cluster instance in exclusive mode. SHARED: a cluster instance in shared mode. CLUSTER: a normal cluster instance. PRIMARY_STANDBY_CLUSTER: a standby cluster instance. K8s_DEDICATED: a Kubernetes cluster instance in exclusive mode. ANALYTICAL_CLUSTER: an analytical instance. K8s_SHARED: a Kubernetes cluster instance in shared mode. KV_CLUSTER: an OBKV cluster instance. SHARED_STORAGE_CLUSTER: a cluster instance using shared storage.	CLUSTER
payType	String	The billing method for the OceanBase cluster. Valid values: PREPAY: the subscription billing method. POSTPAY: the pay-as-you-go billing method.	POSTPAY
region	String	The region.	ap-guangzhou
saleChannel	String	The sales channel. Valid values: domestic: channels provided by OceanBase Cloud in the Chinese mainland. aliyun_domestic: aliyun.com. huawei_mp_domestic: huaweicloud.com. aws_mp_domestic: amazonaws.cn. aws-mp: aws.amazon.com. aliyun_overseas: alibabacloud.com. gcp_mp: GCP Marketplace	domestic
vpcId	String	The ID of the VPC.	vpc-xxxxx
status	String	The status of the cluster. Valid values: PENDING_CREATE: The cluster is being created. ONLINE: The cluster is running. TENANT_CREATING: The tenant is being created. TENANT_SPEC_MODIFYING: The tenant specifications are being modified. EXPANDING: Nodes are being added to the cluster for scale-out. REDUCING: Nodes are being removed from the cluster for scale-in. SPEC_UPGRADING: The specification plan is being upgraded. DISK_UPGRADING: The storage space is being scaled out. WHITE_LIST_MODIFYING: The allowlist is being modified. PARAMETER_MODIFYING: Parameters are being modified. SSL_MODIFYING: The SSL certificate is being changed. PREPAID_EXPIRE_CLOSED: The payment is overdue. This parameter value is valid for a cluster whose billing method is set to PREPAY. ARREARS_CLOSED: The payment is overdue. This parameter value is valid for a cluster whose billing method is set to POSTPAY. PENDING_DELETE: The cluster is being deleted. Generally, the cluster is in the ONLINE state.	ONLINE
series	String	The series of the OceanBase cluster. Valid values are NORMAL, which indicates Standard Cluster Edition (Cloud Disk), and NORMAL_KV, which indicates Standard Cluster Edition (key-value). The default value is NORMAL.	NORMAL
primaryInstanceId	String	The ID of the primary cluster.
standbyInstanceIds	Array	The IDs of standby clusters.	["xxx","xxxx"]
cpuArchitecture	String	The CPU architecture, which can be X86 or ARM.	X86
cpu	Integer	The number of CPU cores of the cluster.	8
mem	Long	The size of memory of the cluster, in GiB.	32
diskSize	Long	The size of the storage space, in GiB.	100
diskType	String	The type of the storage disk where the cluster is deployed.	cloud_essd
state	String	The status of the instance.	ONLINE
usedDiskSize	Long	The size of used storage space of the cluster, in GiB.	1
stopTime	String	The time when the service is unavailable.
resource	Object	The information about cluster resources.
cpu	Object	The information about the CPU resources of the cluster.
totalCpu	Long	The total number of CPU cores of the cluster.	4.0
usedCpu	Long	The number of CPU cores in use by the cluster.	1.0
disk	Object	The information about the storage resources of the cluster.
totalDiskSize	Long	The total size of the disk.	100.0
usedDiskSize	Long	The size of occupied disk space.	1.0
memory	Object	The information about the memory resources of the cluster.
totalMemory	Long	The total memory size.	16.0
usedMemory	Long	The size of occupied memory space.	4.0
tagList	Array	The tag list of the cluster instance.
tagKey	String	The key of the tag.
tagValue	String	The value of the tag.
success	Boolean	Indicates whether the request is successful.	true or false
requestId	String	The ID of the request.	dc302d76-66b5-48d8-ab53-a035****** (64-bit)

Examples

Request example

curl  --request GET  \
--digest   -u 'ak:sk' \
-H 'X-Ob-Project-Id':'projectId' \
--url https://api-cloud.oceanbase.com/api/v2/instances
-G -d 'pageNumber=0' -d 'pageSize=20' -d'instanceName=xxx' -d'instanceId=xxx'

Note

A project ID uniquely identifies a project. For information about how to obtain the project ID of an instance, see Manage projects.

Response example

Here is a response example when the request is successful:

{
    "data":{
        "dataList":[
            {
                "availableZones":[
                    "4"
                ],
                "cloudProvider":"QCLOUD",
                "cpu":4,
                "cpuArchitecture":"X86",
                "createTime":"2024-11-12T08:12:35Z",
                "deployMode":"1-1-1",
                "deployType":"single",
                "diskSize":0,
                "diskType":"cloud_essd",
                "instanceClass":"4C16G",
                "instanceId":"ob68gu********",
                "instanceName":"ob68gu********",
                "instanceRole":"NORMAL",
                "instanceType":"cluster",
                "managementMode":"DBaaS",
                "mem":16,
                "obRpmVersion":"4.2.0.0-100000052023073123",
                "payType":"POSTPAY",
                "region":"ap-beijing",
                "resource":{
                    "cpu":{
                        "totalCpu":4.0,
                        "usedCpu":0.0
                    },
                    "disk":{
                        "totalDiskSize":100.0,
                        "usedDiskSize":1.0
                    },
                    "memory":{
                        "totalMemory":16.0,
                        "usedMemory":0.0
                    }
                },
                "saleChannel":"domestic",
                "series":"NORMAL",
                "standbyInstanceIds":[],
                "state":"STOPPED",
                "status":"STOPPED",
                "stopTime":"2024-11-12T08:39:43Z",
                "tagList":[],
                "usedDiskSize":1,
                "version":"4.2.0",
                "vpcId":"vpc-********"
            },
            {
                "availableZones":[
                    "d",
                    "e"
                ],
                "cloudProvider":"HUAWEI",
                "cpu":4,
                "cpuArchitecture":"X86",
                "createTime":"2024-11-11T02:39:33Z",
                "deployMode":"1-1-1",
                "deployType":"dual",
                "diskSize":0,
                "diskType":"cloud_essd",
                "instanceClass":"4C16G",
                "instanceId":"ob68cg********",
                "instanceName":"ob68cg********",
                "instanceRole":"NORMAL",
                "instanceType":"cluster",
                "managementMode":"DBaaS",
                "mem":16,
                "obRpmVersion":"4.1.0.2-104030012023121217",
                "payType":"POSTPAY",
                "region":"cn-southwest-2",
                "resource":{
                    "cpu":{
                        "totalCpu":4.0,
                        "usedCpu":2.0
                    },
                    "disk":{
                        "totalDiskSize":100.0,
                        "usedDiskSize":1.0
                    },
                    "memory":{
                        "totalMemory":16.0,
                        "usedMemory":8.0
                    }
                },
                "saleChannel":"domestic",
                "series":"NORMAL",
                "standbyInstanceIds":[],
                "state":"ONLINE",
                "status":"ONLINE",
                "tagList":[],
                "usedDiskSize":1,
                "version":"4.1.0",
                "vpcId":"751bc080-d862-4917-972e-48ae********"
            }
        ],
        "total":2
    },
    "requestId":"b819053c-8969-4373-bc6e-f3a3********",
    "success":true
}%

Here is a response example when the request failed:

{
    "errorCode": "Privilege.OpenAPI.AuthFailed",
    "errorMessage": "OpenAPI authentication failed",
    "requestId": "cb32942e-bdf2-4d85-a26f-6bf8********",
    "success": false
}