DescribeInstances|OceanBase Cloud| docs|Distributed Database

DescribeInstances

Last Updated：2026-01-29 07:18:31 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 the Multi-Cloud API. For information about how to obtain the AccessKey ID and AccessKey secret, see Manage AccessKeys.

Request path

GET /api/v2/instances

Request parameters

Query

Name	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 list of tags of the cluster.
pageNumber	int	No	The page number, which starts from 1.	1
pageSize	int	No	The number of entries per page.	10

Body

Name	Type	Required	Description	Example value
None

Response parameters

Name	Type	Description	Example value
data	object	The cluster information, including the dataList attribute.
dataList	arr	The list of cluster information, including the following attributes.
expireTime	String	The expiration time.
managementMode	string	The cluster management mode. DBaaS: the normal mode.	DBaaS
availableZones	array	The available zones.	["4"]
version	string	The OBServer version.	4.2.3
obRpmVersion	String	The detailed OBServer version.	4.2.3.0-100000232024042317
cloudProvider	string	The name of the cloud service provider. ALIYUN: Alibaba Cloud AWS: AWS QCLOUD: Tencent Cloud HUAWEI: Huawei Cloud GCP: GCP	QCLOUD
createTime	string	The creation time of the cluster, in the UTC time format.	2023-08-28T08:30:54Z
deployMode	string	The data replica mode of the cluster, where n indicates the number of OBServer nodes in each IDC. n: single IDC. n-n: dual IDC. n-n-n: multi-IDC.	1-1-1
deployType	string	The deployment type of the cluster. multiple: multi-IDC. single: single IDC. dual: dual IDC.	multiple
instanceClass	string	The cluster specifications. The following packages are supported: 4C16GiB 8C16GiB 8C32GiB 16C32GiB 16C70GiB 32C70GiB 32C180GiB 64C180GiB 64C400GiB	4C16G
instanceId	string	The OceanBase cluster ID.	ob5******
instanceName	string	The name of the OceanBase cluster.	ob********
instanceRole	string	The role of the OceanBase instance.	NORMAL
instanceType	string	The cluster type. DEDICATED: the dedicated cluster mode SHARED: the shared cluster mode CLUSTER: cluster instance PRIMARY_STANDBY_CLUSTER: standby cluster instance K8s_DEDICATED: the K8s dedicated cluster mode ANALYTICAL_CLUSTER: AP instance K8s_SHARED: the K8s shared cluster mode KV_CLUSTER: KV instance SHARED_STORAGE_CLUSTER: shared storage cluster	CLUSTER
payType	string	The billing method of the OceanBase cluster: PREPAY: the prepaid method. POSTPAY: the pay-as-you-go method.	POSTPAY
region	string	The region.	ap-guangzhou
saleChannel	String	The sales channel. By default, it is self-operated channel: Note Currently, only the normandy channel is supported. overseas: overseas self-operated channel domestic: domestic self-operated channel normandy_domestic: normandy channel aliyun_domestic: Alibaba Cloud China Station huawei_mp_domestic: Huawei Cloud China Station aws_mp_domestic: AWS China Station aws-mp: AWS Marketplace aliyun_overseas: Alibaba Cloud Overseas Station gcp_mp: GCP Marketplace	domestic
vpcId	String	The ID of the virtual private cloud.	vpc-xxxxx
status	string	The status of the cluster: PENDING_CREATE: creating. ONLINE: running. TENANT_CREATING: creating a tenant. TENANT_SPEC_MODIFYING: modifying the specifications of a tenant. EXPANDING: expanding nodes. REDUCING: reducing nodes. SPEC_UPGRADING: upgrading the specifications of the cluster. DISK_UPGRADING: upgrading the storage specifications. WHITE_LIST_MODIFYING: modifying the allowlist. PARAMETER_MODIFYING: modifying parameters. SSL_MODIFYING: changing SSL. PREPAID_EXPIRE_CLOSED: the cluster is overdue. ARREARS_CLOSED: the cluster is overdue. PENDING_DELETE: deleting. The cluster is generally in the ONLINE state.	ONLINE
series	string	The series of the OceanBase cluster. By default, it is NORMAL, indicating the standard cluster edition (cloud disk). It can also be normal_kv, indicating the standard cluster edition (key-value).	NORMAL
primaryInstanceId	String	The ID of the primary cluster.
standbyInstanceIds	arr	The IDs of the standby clusters.	["xxx","xxxx"]
cpuArchitecture	String	The value of the CPU architecture: X86/ARM	X86
cpu	integer	The number of CPU cores of the cluster.	8
mem	long	The size of the 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 deployed for the cluster.	cloud_essd
state	string	The status of the instance.	ONLINE
usedDiskSize	long	The size of the storage space used by the cluster, in GiB.	1
stopTime	String	The time when the cluster is stopped.
resource	object	The resource information of the cluster.
cpu	object	The CPU resource information of the cluster.
totalCpu	long	The total number of CPU cores in the cluster.	4.0
usedCpu	long	The number of CPU cores used by the cluster.	1.0
disk	object	The storage resource information of the cluster.
totalDiskSize	long	The total disk size.	100.0
usedDiskSize	long	The size of the used disk.	1.0
memory	object	The memory resource information of the cluster.
totalMemory	long	The total memory size.	16.0
usedMemory	long	The size of the used memory.	4.0
tagList	arr	The list of tags of the cluster instance.
tagKey	String	The key of the tag.
tagValue	String	The value of the tag.
success	boolean	Indicates whether the request was successful.	true/false
requestId	String	trace	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.
Make sure that the project ID corresponding to the specified instanceId is consistent with the specified project ID.

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": "Params.InstanceName.Invalid",
    "errorMessage": "The cluster name is invalid.",
    "requestId": "cb32942e-bdf2-4d85-a26f-6bf8********",
    "success": false
}