Overview
You can call this API to query the list of OceanBase Cloud instances. You can filter the instances by name, ID, or tag, and you can also perform pagination.
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 |
|---|---|---|---|---|
| requestId | String | Yes | The request ID for tracing. | dc302d76-66b5-48d8-ab53-a035******** |
| X-Ob-Project-Id | String | Yes | The project ID. | hxq3ztx3377nby3v87ry**** |
| instanceName | String | No | The name of the cluster. | test-cluster |
| tenantSearchKey | String | No | The search keyword for tenants. | |
| instanceId | String | No | The ID of the cluster. | obcluster-***** |
| tagList | String | No | The list of tags of the cluster. | |
| organizationId | String | No | The ID of the organization. | |
| pageNumber | int | No | The page number. | 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 |
|---|---|---|---|
| success | Boolean | Indicates whether the request was successful. | true |
| errorCode | String | Error code. | INVALID_PARAMETER |
| errorMessage | String | Error message. | Invalid parameter |
| data | Object | Business data (Object). | None |
| cost | Number | Time consumed. | 1.0 |
| server | String | Server address, typically the IP address of an OBServer node. | 10.0.0.10 |
| requestId | String | Request ID. | d04eabba**** |
| totalCount | Number | Total number of records. | 100.0 |
| extra | Object | Extended information. | {} |
data object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| dataList | Array | Dataset. | [{'id': 'resource-123456'}] |
| total | Number | Total amount of data. | 100.0 |
| hasMore | Boolean | Whether there is more data. | true |
data.dataList[] object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| region | String | Region. | ap-guangzhou |
| instanceId | String | OceanBase cluster ID. | obcluster-***** |
| instanceName | String | Cluster name. | test-clu**** |
| instanceClass | String | Cluster specification. | xxxxxx |
| series | String | Instance series. | NORMAL |
| gmtCreate | String | Creation time. | 2026-02-25 15:40:43+00:00 |
| obRpmVersion | String | OB RPM version. | 4.2.1.0-100020042023102310 |
| version | String | OceanBase Database version. | 2.2.52 |
| maxCpu | Integer | Maximum CPU specification. | 4 |
| maxMem | Integer | Maximum memory specification (GB). | 16 |
| usedDiskSize | Integer | Used disk capacity. | 200 |
| state | String | Status. Legacy field. | ONLINE |
| resource | Object | Resource specification information, including CPU, memory, disk, and node resources. | None |
| resource.cpu | Object | Processor core or specification information. | None |
| resource.cpu.totalCpu | Number | Total number of CPU cores. | 4.0 |
| resource.cpu.usedCpu | Number | Number of CPU cores used. | 4.0 |
| resource.cpu.originalTotalCpu | Number | Total number of CPU cores before the change. | 4.0 |
| resource.cpu.unitCpu | Number | Unit processor specification. | 2.0 |
| resource.memory | Object | Memory information in the resource specification. | None |
| resource.memory.totalMemory | Number | Total memory size. | 16.0 |
| resource.memory.usedMemory | Number | Used memory. | 16.0 |
| resource.memory.originalTotalMemory | Number | Total memory size before the change. | 16.0 |
| resource.memory.unitMemory | Number | Unit memory size (GB). | 8.0 |
| resource.memory.hostActualMemory | Number | Actual host memory size, in GiB. | 16.0 |
| resource.memory.systemMemory | Number | Memory used by the system on an Ultimate Edition host, in GiB. Formula: hostActualMemory - totalMemory. | 16.0 |
| resource.memory.originalHostActualMemory | Number | Actual host memory size for the original specification, in GiB. | 16.0 |
| resource.diskSize | Object | Disk size. | None |
| resource.diskSize.totalDiskSize | Number | Total disk capacity. | 200.0 |
| resource.diskSize.usedDiskSize | Number | Used disk capacity. | 200.0 |
| resource.diskSize.originalTotalDiskSize | Number | Total disk capacity before the change. | 200.0 |
| resource.diskSize.totalDataSize | Number | Total data volume. | 200.0 |
| resource.diskSize.unitDiskSize | Number | Unit disk size. | 200.0 |
| resource.diskSize.availableDiskSize | Number | User-available storage size (GB). Formula: getAvailableDiskSize(unitDiskSize, nodeCount, obVersion, shareStorageCluster). | 200.0 |
| status | String | Current status of the task or resource. | ONLINE |
| deployMode | String | Data replica mode (n/n-n/n-n-n). | 1-1-1 |
| vpcId | String | VPC identifier. | vpc-xxxx**** |
| payType | String | Billing type. | POSTPAID |
| availableZones | Array | Zones. | ['h'] |
| deployType | String | Deployment type. Valid values: single (single IDC), multiple (multiple IDCs), and dual (dual IDCs). |
single |
| gmtEnd | String | End time. | 2026-02-25 15:40:43+00:00 |
| cloudProvider | String | Cloud service provider or data source. | xxxxxx |
| managementMode | String | Management mode. | DBAAS |
| instanceType | String | Instance type. | DEDICATE**** |
| diskType | String | Storage type. Valid values: cloud_essd_pl1 (ESSD cloud disk) and ephemeral_ssd (local SSD disk). |
cloud_essd |
| diskSize | Integer | Disk size. | 200 |
| instanceRole | String | Instance role, for example, primary instance or standby instance. | xxxxxx |
| primaryInstanceId | String | 2022-05-10 Primary database ID. Valid only when instanceRole=PHYSICAL_STANDBY. |
obcluste**** |
| standbyInstanceIds | Array | 2022-05-10 Standby database ID. Valid only when instanceRole=PRIMARY. |
['obclus**** |
| stopTime | String | Stop time. | 2026-02-26 10:40:43+00:00 |
| saleChannel | String | Sales channel. Valid values: overseas (overseas self-operated channel), domestic (domestic self-operated 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), and gcp_mp (GCP Marketplace). |
domestic |
| tagList | Array | Tag list. | [{'tagKey': 'env', 'tagValue': 'prod'}] |
| cpuArchitecture | String | CPU architecture. | 4 |
| storageArchitecture | String | Storage architecture. shareStorage indicates shared storage, and standardStorage indicates standard storage. |
standardStorage |
| storageDiskType | String | Storage type. Currently, only tp mode supports selecting a storage type, and only OBPL1 is supported. |
OBPL1 |
| inTempCapacityStatus | Boolean | Indicates whether the instance is undergoing a temporary specification change. | true |
data.dataList[].availableZones[] element fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| data.dataList[].availableZones[] | String | Zone. | h |
data.dataList[].standbyInstanceIds[] element fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| data.dataList[].standbyInstanceIds[] | String | 2022-05-10 Standby database ID. Valid only when instanceRole=PRIMARY. |
o**** |
data.dataList[].tagList[] object fields
Name |
Type |
Description |
Example value |
|---|---|---|---|
| tagKey | String | Tag key. | env |
| tagValue | String | Tag value. | prod |
Examples
Request example
curl --request GET \
--digest -u '<Your ak:sk>' \
-H 'X-Ob-Project-Id: {projectId}' \
--url 'https://api-cloud.oceanbase.com/api/v2/instances?requestId={requestId}&instanceName={instanceName}&instanceId={instanceId}&tenantSearchKey={tenantSearchKey}&organizationId={organizationId}&pageNumber={pageNumber}&pageSize={pageSize}'
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
JSON format
{
"success": true,
"errorCode": "INVALID_PARAMETER",
"errorMessage": "Invalid parameter",
"data": {
"dataList": [
{
"region": "ap-guangzhou",
"instanceId": "obcluster-*****",
"instanceName": "test-clu****",
"instanceClass": "xxxxxx",
"series": "NORMAL",
"gmtCreate": "2026-02-25 15:40:43+00:00",
"obRpmVersion": "4.2.1.0-100020042023102310",
"version": "2.2.52",
"maxCpu": 4,
"maxMem": 16,
"usedDiskSize": 200,
"state": "ONLINE",
"resource": {
"cpu": {
"totalCpu": 4.0,
"usedCpu": 4.0,
"originalTotalCpu": 4.0,
"unitCpu": 2.0
},
"memory": {
"totalMemory": 16.0,
"usedMemory": 16.0,
"originalTotalMemory": 16.0,
"unitMemory": 8.0,
"hostActualMemory": 16.0,
"systemMemory": 16.0,
"originalHostActualMemory": 16.0
},
"diskSize": {
"totalDiskSize": 200.0,
"usedDiskSize": 200.0,
"originalTotalDiskSize": 200.0,
"totalDataSize": 200.0,
"unitDiskSize": 200.0,
"availableDiskSize": 200.0
}
},
"status": "ONLINE",
"deployMode": "1-1-1",
"vpcId": "vpc-xxxx****",
"payType": "POSTPAID",
"availableZones": "---\n- \"h\"",
"deployType": "single",
"gmtEnd": "2026-02-25 15:40:43+00:00",
"cloudProvider": "xxxxxx",
"managementMode": "DBAAS",
"instanceType": "DEDICATE****",
"diskType": "cloud_essd",
"diskSize": 200,
"instanceRole": "xxxxxx",
"primaryInstanceId": "obcluste****",
"standbyInstanceIds": "---\n- \"o****",
"stopTime": "2026-02-26 10:40:43+00:00",
"saleChannel": "domestic",
"tagList": [
{
"tagKey": "env",
"tagValue": "prod"
}
],
"cpuArchitecture": "4",
"storageArchitecture": "standardStorage",
"storageDiskType": "OBPL1",
"inTempCapacityStatus": true
}
],
"total": 100.0,
"hasMore": true
},
"cost": 1.0,
"server": "xxx.xxx.x.xxx:xxx",
"requestId": "d04eabba****",
"totalCount": 100.0,
"extra": "{}"
}