Query the list of OceanBase clusters|V4.3.6| docs|Distributed Database

Query the list of OceanBase clusters

Last Updated：2025-09-08 08:15:43 Updated

Feature description

This API is used to query information about OceanBase clusters managed by OCP.

You can narrow down the query scope based on the conditions such as the keyword for the cluster name and the cluster status. In primary-standby deployment mode, the response parameters include both primary and standby clusters. You can identify the role of each cluster based on its attributes.

Call description

Prerequisites

The caller must be at least the CLUSTER_VIEWER role.
The caller must be authenticated by the OCP application service.

Request path

GET /api/v2/ob/clusters

Request parameters

Parameter	Type	Required	Example Value	Description
page	Integer	No	1	The page number of the requested data. The value starts from 1. Default value: 1.
size	Integer	No	10	The number of records to return on each page. Default value: 10, maximum value: 2000.
sort	String	No	name,asc	The sorting rule for the requested data.
name	String	No	foo	The keyword for the cluster name, which is case-insensitive.
status	StringArray	No	CREATING,RUNNING	The status of the cluster. Valid values: RUNNING CREATING DELETING STARTING RESTARTING STOPPING STOPPED TAKINGOVER MOVINGOUT SWITCHOVER FAILOVER OPERATING
withRemote	Enum	No	NONE	Specifies whether to query OceanBase clusters managed by remote OCP clusters. Valid values: NONE: Query none of them. ALL: Query local tenants and the remote tenants that are in a primary/standby relationship with local tenants.
foldStandby	-	-	-	This parameter is deprecated and will be removed from later versions.

Response parameters

Basic data structure

Parameter	Type	Description
data	Object	For more information, see Data structure of ObCluster.
├─ contents	Array	The array of the primary/standby cluster information.
├─ page	Object	The paging information.
├─ totalElements	Integer	The total number of records.
├─ totalPages	Integer	The total number of pages.
├─ number	Integer	The current page number.
├─ size	Integer	The size of the current page.
successful	Boolean	Indicates whether the request is successful.
timestamp	Datetime	The timestamp when the server completed the request.
duration	Integer	The time taken by the server to process the request, in milliseconds.
status	Integer	An HTTP status code that conforms to the HTTP status specification.
traceId	String	The trace ID of the request, which is used to troubleshoot issues.
server	String	The address of the application service that responds to the request.

Data structure of ObCluster

Parameter	Type	Description
primaryCluster	Object	The primary cluster of the current cluster.
standbyClusters	Array	The array of standby clusters of the current cluster.
id	Integer	The ID of the cluster.
name	String	The name of the cluster.
vpcId	Integer	The ID of the VPC to which the cluster belongs.
vpcName	String	The name of the VPC to which the cluster belongs.
obClusterId	Integer	The ID of the cluster in OceanBase Database.
obVersion	String	The version of the cluster.
minObBuildVersion	String	The minimum OceanBase build version. The build versions of servers may vary, and the minimum value among the servers in the cluster is used.
status	String	The status of the cluster. Valid values: RUNNING CREATING DELETING STARTING RESTARTING STOPPING STOPPED TAKINGOVER MOVINGOUT SWITCHOVER FAILOVER OPERATING
origin	Enum	The type of the cluster. Valid values: CREATED: The OceanBase cluster was created by the current OCP. TAKEN_OVER: The OceanBase cluster was taken over to the current OCP.
compactionStatus	Enum	The compaction status of the cluster. Valid values: IDLE: idle. MERGING: major compaction is in progress. INDEX INDEXING: indexing. Major compaction is performed before indexing. OceanBase Database V2.2 and later no longer use the INDEX state. ERROR: error. TIMEOUT: timeout. MOST_MERGED: major compaction is completed.
rpmName	String	The name of the RPM package.
architecture	String	The hardware architecture.
rootServers	Array	Information about the root servers.
├─ address	String	The address of the root server, in the `IP:Port` format.
├─ role	String	The role of the root server. Valid values: LEADER FOLLOWER
├─ sql_port	Integer	The SQL port number.
type	String	The type of the cluster. Valid values: PRIMARY STANDBY
regionCount	Integer	The number of regions.
tenantCount	Integer	The number of tenants.
partitionCount	Integer	The number of partitions.
serverCount	Integer	The number of OBServer nodes.
delayTime	Float	The latency of the standby cluster, in seconds.
consistentTime	String	The point in time when the standby cluster was synchronized with the primary cluster.
protectionMode	Enum	The protection mode of the cluster. Valid values: MAXIMUM_PERFORMANCE MAXIMUM_PROTECTION MAXIMUM_AVAILABILITY UNKNOWN
redoTransportMode	Enum	The log transmission mode of the cluster. Valid values: SYNC ASYNC UNKNOWN
redoTransportStatus	Enum	The actual log transmission status of the cluster.
syncStatus	String	The primary/standby synchronization status. Valid values: VALID DISABLED SYNCHRONIZING
syncInfo	String	The description of the primary/standby synchronization status.
zoneTopo	String	The zone deployment topology.
configUrl	String	The ConfigUrl of the cluster.
startupParameters	Array	The startup parameters of the cluster.
attributes	Object	The attributes of the cluster.
├─InstallPath	String	The installation path of the cluster.
├─RunPath	String	The running path.
├─DataDiskPath	String	The path of the data disk.
├─LogDiskPath	String	The path of the log disk.
├─DiskPathStyle	Enum	OBD DEFAULT.
├─OperatingSystemUser	String	The host operating system user.
├─SqlPort	Integer	The SQL port number.
├─SvrPort	Integer	The RPC port number.
availableOperations	Array	The operations that can be executed.
rootServer	Array	The root server list.
zones	Object	For more information, see Data structure of Zone.
tenants	Array	The tenant list.
createTime	DateTime	The time when the cluster was created.
updateTime	DateTime	The time when the cluster was last updated.
creator	String	The username of the user who created the cluster.
alarmSummaries	-	This parameter is deprecated and will be removed from later versions.
resourceStats	-	This parameter is deprecated and will be removed from later versions.
performanceStats	-	This parameter is deprecated and will be removed from later versions.
failToQueryFromObReason	-	This parameter is deprecated and will be removed from later versions.
ocpCluster	Object	The information about the OCP cluster.
├─ id	Long	The ID of the OCP cluster.
├─ name	String	The name of the OCP cluster.
├─ role	Enum	The role of the OCP cluster. Valid values: LEADER: primary cluster. CANDIDATE: candidate primary cluster. FOLLOWER: standby cluster.
├─ address	String	The address of the OCP cluster.
├─ version	String	The version of the OCP cluster.
├─ status	Enum	The status of the OCP cluster. Valid values: NORMAL: The OCP cluster is running. UPGRADING: The OCP cluster is being upgraded. SWITCHING: The OCP cluster is in the progress of a failover or switchover. OFFLINE: The OCP cluster is unavailable. When the primary OCP cluster detects a heartbeat timeout from a standby OCP cluster, it sets the standby cluster to the `OFFLINE` state. ABANDONED: The original primary OCP cluster was abandoned after a failover.
├─ lastHeartbeatTime	DateTime	The timestamp of the last heartbeat.
deadLockDetectionEnabled	Boolean	Indicates whether automatic deadlock detection is enabled.
cgroupEnabled	Boolean	Indicates whether the Cgroup feature is enabled for the cluster.
enableCgroup	Boolean	Indicates whether the Cgroup feature has been successfully enabled after the cluster is modified.
oversellingFactor	Integer	The resource overprovisioning factor. Valid values: [100, 200], indicating that the factor ranges from 100% to 200%. Default value: 100, indicating that resources are not overprovisioned.
originalPrimary	Boolean	Indicates whether the cluster was the primary cluster before the failover.
arbitrationServiceInfo	Object	The information about the arbitration service.
arbitrationServiceGroup	Object	The information about the arbitration service group.
obArbitrationStatus	Enum	The communication status between OceanBase Database and the arbitration service. Valid values: ACTIVE INACTIVE
tags	Array	The tags for the cluster.
packageOperatingSystem	String	The operating system of the software package.
loadType	Enum	The load type. Valid values: EXPRESS_OLTP COMPLEX_OLTP HTAP OLAP KV
obStartTime	DateTime	The start time of the cluster.

Data structure of Zone

Parameter	Type	Description
name	String	The name of the zone.
idcName	String	The name of the IDC to which the zone belongs.
regionName	String	The name of the region to which the zone belongs.
servers	Array	The server list.
clusterId	Long	The ID of the server.
obClusterId	Long	The ID of the cluster in OceanBase Database.
serverCount	Integer	The number of servers.
hostCount	Integer	The number of hosts.
architecture	String	The CPU architecture.
status	Enum	The status of the zone. Valid values: RUNNING UNAVAILABLE SERVICE_STOPPED STOPPED DELETED CREATING (an intermediate O&M state). STOPPING (an intermediate O&M state). STARTING (an intermediate O&M state). RESTARTING (an intermediate O&M state). DELETING (an intermediate O&M state). OPERATING (an intermediate O&M state).
innerStatus	Enum	The inner status of the zone in OceanBase Database, which is the value of the internal table `__all_zone status`. Valid values: ACTIVE INACTIVE
compactionStatus	Enum	The major compaction status. Valid values: IDLE: The major compaction has not started. MERGING: The major compaction is in progress. INDEX INDEXING: The newly compacted data is being indexed. The INDEX state is no longer used in OceanBase Database V2.2 and later. ERROR: An error occurred. TIMEOUT: The major compaction timed out. MOST_MERGED: The major compaction is complete.
rootServer	Object	The RootServer of the zone.
availableOperations	Object	The operations that can be executed.

Examples

Request example

Query OceanBase clusters and return only the first page, with a page size of 10.

GET /api/v2/ob/clusters?page=1&size=10

Response example

{
    "data": {
        "contents": [
            {
                "id": 1,
                "name": "ExampleCluster",
                "vpcId": 1001,
                "vpcName": "example-vpc",
                "obClusterId": 2001,
                "obVersion": "4.2.0.0_100000132023071110",
                "minObBuildVersion": "4.2.0.0",
                "status": "RUNNING",
                "origin": "CREATED",
                "operatingTaskInstanceId": 3001,
                "statusAnalysis": {
                    "startTime": "2023-10-01T10:15:30Z",
                    "reason": "Normal operation",
                    "action": "No action needed",
                    "reasonType": "Healthy",
                    "diagnosisType": "None",
                    "diagnosisContent": {}
                },
                "compactionStatus": "IDLE",
                "rpmName": "oceanbase-4.2.0.rpm",
                "architecture": "x86_64",
                "type": "PRIMARY",
                "regionCount": 1,
                "tenantCount": 5,
                "partitionCount": 10,
                "serverCount": 3,
                "consistentTime": "2023-10-01T10:15:30Z",
                "delayTime": 0.5,
                "protectionMode": "MAXIMUM_PERFORMANCE",
                "redoTransportMode": "SYNC",
                "syncStatus": "VALID",
                "syncInfo": "No sync issues",
                "zoneTopo": "zone1->zone2",
                "configUrl": "http://example.com/cluster_config",
                "startupParameters": {},
                "attributes": {
                    "InstallPath": "/home/admin/oceanbase",
                    "RunPath": "/home/admin/oceanbase/run",
                    "DataDiskPath": "/data/1",
                    "LogDiskPath": "/logs",
                    "DiskPathStyle": "OBD",
                    "OperatingSystemUser": "admin",
                    "SqlPort": 3306,
                    "SvrPort": 5000
                },
                "zones": [
                    {
                        "id": 7001,
                        "name": "ZoneA",
                        "idcId": 8001,
                        "idcName": "IDC1",
                        "regionName": "Region1",
                        "architecture": "x86_64",
                        "servers": [{
                            "id": 9001,
                            "ip": "xxx.xxx.xxx.xxx",
                            "port": 3306,
                            "sqlPort": 3306,
                            "runUser": "admin",
                            "runPath": "/home/admin/rs",
                            "installPath": "/data/1",
                            "version": "4.2.0.0",
                            "withRootserver": true,
                            "status": "RUNNING",
                            "innerStatus": "ACTIVE",
                            "operatingTaskInstanceId": 10001,
                            "statusAnalysis": {
                                "startTime": "2023-10-01T10:00:00Z",
                                "reason": "Normal operation",
                                "action": "No action needed",
                                "reasonType": "Healthy",
                                "diagnosisType": "None",
                                "diagnosisContent": {}
                            },
                            "updateTime": "2023-10-01T10:15:30Z",
                            "clusterId": 2001,
                            "zoneName": "ZoneA",
                            "regionName": "Region1",
                            "idcName": "IDC1",
                            "hostId": 3001,
                            "hostTypeName": "Default",
                            "hostStatus": "ONLINE",
                            "startTime": "2023-10-01T09:00:00Z",
                            "stopTime": null
                        }],
                        "status": "RUNNING",
                        "operatingTaskInstanceId": 11001,
                        "statusAnalysis": {
                            "startTime": "2023-10-01T10:00:00Z",
                            "reason": "Normal operation",
                            "action": "No action needed",
                            "reasonType": "Healthy",
                            "diagnosisType": "None",
                            "diagnosisContent": {}
                        },
                        "innerStatus": "ACTIVE",
                        "compactionStatus": "IDLE",
                        "clusterId": 2001,
                        "obClusterId": 2001,
                        "serverCount": 1,
                        "hostCount": 1,
                        "createTime": "2023-10-01T09:00:00Z",
                        "updateTime": "2023-10-01T10:15:30Z"
                    }
                ],
                "createTime": "2023-10-01T10:00:00Z",
                "updateTime": "2023-10-01T10:15:30Z",
                "creator": "admin"
            }
        ],
        "page": {
            "number": 1,
            "size": 10,
            "totalElements": 1,
            "totalPages": 1
        }
    },
    "duration": 108,
    "server": "a83ad33525",
    "status": 200,
    "successful": true,
    "timestamp": "2020-12-02T20:03:58.233+08:00",
    "traceId": "3cfec9a5180748ff"
}