DescribeInstance|OceanBase Cloud | docs|Distributed Database

DescribeInstance

Last Updated：2026-03-24 07:38:30 Updated

Overview

You can call this API to query the details of an OceanBase cluster.

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/{instanceId}

Request parameters

Query

Name	Type	Required	Description	Example value
None

Body

Name	Type	Required	Description	Example value
None

Response parameters

Parameter	Type	Description	Example value
data	object	The details of the cluster.
diskType	string	The type of the storage used to deploy the cluster.	cloud_essd
managementMode	string	The management mode of the cluster. DBaaS: The normal mode.	DBaaS
series	string	The series of the OceanBase cluster. Default value: NORMAL, which indicates a standard cluster (with cloud disks). Valid values: normal_kv and normal.	NORMAL
projectId	string	The ID of the project.	li15c8s987d2arse********
availableZones	array	The zones.	["4"]
version	string	The version of the OBServer.	3.2.3.0
obRpmVersion	String	The detailed version of the OBServer.	4.2.3.0-100000232024042317
cloudProvider	string	The name of the cloud service provider. > ALIYUN: Alibaba Cloud. QCLOUD: Tencent Cloud. AWS: Amazon Web Services. AWSCN: Amazon Web Services China. HUAWEI: Huawei Cloud. GCP: Google Cloud Platform.	QCLOUD
createTime	string	The creation time of the cluster in the UTC format.	2023-08-28T08:30:54Z
dataMergeTime	String	The data merge time of the cluster.	18:00Z
deployMode	string	The data replica mode of the cluster. n: single IDC. n-n: dual IDC. n-n-n: multi-IDC. n indicates the number of OBServer nodes in each 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 specifications of the cluster. The following packages are supported: 4C16GiB 8C16GiB 8C32GiB 16C32GiB 16C70GiB 32C70GiB 32C180GiB 64C180GiB 64C400GiB	8C32G
instanceId	string	The ID of the OceanBase cluster.	ob5******
instanceName	string	The name of the OceanBase cluster.	test
instanceRole	string	The role of the OceanBase instance.	NORMAL
instanceType	string	The type of the cluster. DEDICATED: dedicated cluster SHARED: shared cluster CLUSTER: cluster instance PRIMARY_STANDBY_CLUSTER: standby cluster instance K8s_DEDICATED: K8s dedicated cluster ANALYTICAL_CLUSTER: AP instance K8s_SHARED: K8s shared cluster KV_CLUSTER: KV instance SHARED_STORAGE_CLUSTER: shared storage cluster	CLUSTER
payType	string	The billing type of the OceanBase cluster: PREPAY: prepaid. POSTPAY: pay-as-you-go.	POSTPAY
region	string	The region.	ap-guangzhou
saleChannel	String	The sales channel: domestic: Alibaba Cloud China. aliyun_domestic: Alibaba Cloud China. huawei_mp_domestic: Huawei Cloud China. aws_mp_domestic: AWS China. aws-mp: AWS Marketplace. aliyun_overseas: Alibaba Cloud International. gcp_mp: GCP Marketplace.	domestic
NodeNum	String	The number of nodes in the cluster. If the deployment mode is n-n-n, the number of nodes is n * 3.	3
CpuArchitecture	String	The CPU architecture of the cluster.	X86
replicaMode	String	The number of full-featured replicas. Valid values: 3 and 2. 3: three full-featured replicas. 2: two full-featured replicas. If the cluster is deployed in three zones, three full-featured replicas are supported. If the cluster is deployed in two zones, two full-featured replicas are supported. If the cluster is deployed in one zone, two or three full-featured replicas are supported.	3
vpcId	String	The ID of the VPC.	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. DISK_UPGRADING: upgrading the storage. WHITE_LIST_MODIFYING: modifying the allowlist. PARAMETER_MODIFYING: modifying parameters. SSL_MODIFYING: changing SSL settings. 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
primaryInstanceId	String	The ID of the primary cluster.
standbyInstanceIds	arr	The IDs of the standby clusters.	["xxx","xxxx"]
tagList	arr	The tags of the cluster instance.	[{"tagKey","tagValue"}]
expireTime	String	The expiration time.
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 of 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 disk size in use.	1.0
memory	object	The memory resource information of the cluster.
totalMemory	long	The total memory size.	16.0
usedMemory	long	The memory size in use.	4.0
tagList	arr	The list of tags of the cluster instance.
tagKey	String	The tag key.
tagValue	String	The tag value.
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' \
--url https://api-cloud.oceanbase.com/api/v2/instances/{instanceId}
-H 'X-Ob-Project-Id: <Project ID>'

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":{
        "availableZones":[
            "d",
            "e"
        ],
        "cloudProvider":"HUAWEI",
        "cpuArchitecture":"X86",
        "createTime":"2024-11-11T02:39:33Z",
        "dataMergeTime":"18:00Z",
        "deployMode":"1-1-1",
        "deployType":"dual",
        "diskType":"cloud_essd",
        "instanceClass":"4C16G",
        "instanceId":"ob68cg********",
        "instanceName":"ob68cg********",
        "instanceRole":"NORMAL",
        "instanceType":"CLUSTER",
        "managementMode":"DBaaS",
        "nodeNum":3,
        "obRpmVersion":"4.1.0.2-104030012023121217",
        "payType":"POSTPAY",
        "projectId":"li15c8s987d2arse********",
        "region":"cn-southwest-2",
        "replicaMode":"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":[],
        "status":"ONLINE",
        "version":"4.1.0",
        "vpcId":"751bc080-d862-4917-972e-48ae********"
    },
    "requestId":"d5ce1e06-f263-4407-8ba0-5ad2********",
    "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
}