Query tenants of a cluster|V4.3.5|OceanBase Cloud Platform|docs|OceanBase Documentations

Query tenants of a cluster

Last Updated：2026-09-04 02:20:48 Updated

Feature description

Queries the tenant list of a cluster.

Call instructions

Interface constraints

The caller must have the read privilege on the specified cluster.

Request path

GET /api/v2/ob/clusters/{id}/tenants

Request parameters

path:

Parameter	Type	Required	Example Value	Description
id	Integer	Yes	1000002	The cluster ID in OCP.

body:

Parameter	Type	Required	Example Value	Description
page	Integer	No	0	The page number of the requested data. Values start from 1, and the default value is 1.
size	Integer	No	10	The size of the requested data. The default value is 10. The maximum value is 2000.
sort	String	No	asc,name	The sorting rule.
name	String	No	foo	The keyword for the cluster name, which is case-insensitive.
mode	String	No	MYSQL	The tenant mode: MYSQL or ORACLE.
locked	Boolean	No	true	Specifies whether the tenant is locked.
readonly	Boolean	No	Boolean	Specifies whether the tenant is read-only.
status	StringArray	No	CREATING	The status of the tenant: NORMAL: running. CREATING: being created. MODIFYING: being modified. UNAVAILABLE: unavailable. RESTORING: being restored. DISCONNECTING: being uncoupled. FAILOVER: disaster recovery switchover. SWITCHOVER: regular switchover. OPERATING: under maintenance. CLONING: cloning.

Response

Basic data structure

Parameter	Type	Description
data	Object	The business data requested.
├─ contents	Array	For more information, see Data structure of tenant information.
├─ page	Object	The pagination information.
├─ totalElements	Integer	The total number of records.
├─ totalPage	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 was 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	The 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 server that responded to the request.

Data structure of tenant information

Parameter	Type	Description
id	Integer	The ID of the tenant.
name	String	The name of the tenant.
clusterName	String	The name of the cluster to which the tenant belongs.
clusterId	Integer	The ID of the cluster to which the tenant belongs in OCP.
obClusterId	Integer	The ID of the cluster to which the tenant belongs in OceanBase.
clusterType	String	The type of the cluster to which the tenant belongs. Valid values: PRIMARY: the primary cluster STANDBY: the standby cluster
mode	String	The mode of the tenant. Valid values: ORACLE: Oracle mode MYSQL: MySQL mode
createTime	Datetime	The creation time of the tenant.
primaryZone	String	The zone priority of the tenant.
zoneList	String	The zone list of the tenant.
locality	String	The replica distribution of the tenant.
status	String	The status of the tenant. Valid values: NORMAL: running. CREATING: being created. MODIFYING: being modified. UNAVAILABLE: unavailable. RESTORING: being restored. DISCONNECTING: being uncoupled. FAILOVER: in disaster recovery switchover. SWITCHOVER: in routine switchover. OPERATING: under maintenance. CLONING: being cloned.
locked	Boolean	Indicates whether the tenant is locked.
readonly	Boolean	Indicates whether the tenant is in read-only mode.
obVersion	String	The OceanBase version of the cluster to which the tenant belongs.
description	String	The description of the tenant.
loadType	Enum	The load type. Valid values: EXPRESS_OLTP COMPLEX_OLTP HTAP OLAP KV

Example

Request example

Query all tenants in the cluster with ID 1000002.

GET /api/v2/ob/clusters/1000002/tenants

Response example

{
    "data": {
        "contents": [{
            "arbitrationStatus": "ENABLED",
            "clusterId": 1000002,
            "clusterName": "ob4252_X",
            "clusterStatus": "RUNNING",
            "clusterType": "PRIMARY",
            "createTime": "2025-05-21T16:11:46+08:00",
            "id": 1000009,
            "loadType": "KV",
            "locality": "FULL{1}@zone1, FULL{1}@zone2",
            "locked": false,
            "logTransportMode": "NETWORK",
            "mode": "ORACLE",
            "name": "Y_oracle",
            "obClusterId": 1731295878,
            "obTenantId": 1004,
            "obVersion": "4.2.5.3",
            "ocpClusterView": {
                "address": "http://xx.xx.xx.xx:8080",
                "id": 111,
                "lastHeartbeatTime": "2025-05-26T13:43:00.457198391+08:00",
                "name": "ocp1",
                "role": "LEADER",
                "status": "NORMAL",
                "version": "4.3.5"
            },
            "primaryZone": "RANDOM",
            "readonly": false,
            "role": "PRIMARY",
            "serviceNameInfo": {
                "serviceName": "osn_XY",
                "serviceNameStatus": "VALID",
                "serviceNameValid": true
            },
            "status": "NORMAL",
            "syncStatus": "VALID",
            "zoneList": "zone1;zone2"
        },
        {
            "arbitrationStatus": "ENABLED",
            "clusterId": 1000002,
            "clusterName": "ob4252_X",
            "clusterStatus": "RUNNING",
            "clusterType": "PRIMARY",
            "createTime": "2025-05-21T16:11:13+08:00",
            "id": 1000008,
            "loadType": "KV",
            "locality": "FULL{1}@zone1, FULL{1}@zone2",
            "locked": false,
            "logTransportMode": "NETWORK",
            "mode": "MYSQL",
            "name": "X_mysql",
            "obClusterId": 1731295878,
            "obTenantId": 1002,
            "obVersion": "4.2.5.3",
            "ocpClusterView": {
                "address": "http://xx.xx.xx.xx:8080",
                "id": 111,
                "lastHeartbeatTime": "2025-05-26T13:43:00.457198391+08:00",
                "name": "ocp1",
                "role": "LEADER",
                "status": "NORMAL",
                "version": "4.3.5"
            },
            "primaryZone": "RANDOM",
            "readonly": false,
            "role": "PRIMARY",
            "serviceNameInfo": {
                "serviceName": "msn_XY",
                "serviceNameStatus": "VALID",
                "serviceNameValid": true
            },
            "status": "NORMAL",
            "syncStatus": "VALID",
            "zoneList": "zone1;zone2"
        },
        {
            "arbitrationStatus": "ENABLED",
            "clusterId": 1000002,
            "clusterName": "ob4252_X",
            "clusterStatus": "RUNNING",
            "clusterType": "PRIMARY",
            "createTime": "2025-05-21T16:03:04+08:00",
            "id": 1000006,
            "locality": "FULL{1}@zone1, FULL{1}@zone2",
            "locked": false,
            "mode": "MYSQL",
            "name": "sys",
            "obClusterId": 1731295878,
            "obTenantId": 1,
            "obVersion": "4.2.5.3",
            "ocpClusterView": {
                "address": "http://xx.xx.xx.xx:8080",
                "id": 111,
                "lastHeartbeatTime": "2025-05-26T13:43:00.457198391+08:00",
                "name": "ocp1",
                "role": "LEADER",
                "status": "NORMAL",
                "version": "4.3.5"
            },
            "primaryZone": "RANDOM",
            "readonly": false,
            "role": "PRIMARY",
            "status": "NORMAL",
            "syncStatus": "VALID",
            "zoneList": "zone1;zone2"
        }],
        "page": {
            "number": 1,
            "size": 5000,
            "totalElements": 3,
            "totalPages": 1
        }
    },
    "duration": 95,
    "server": "21dc8a9b83",
    "status": 200,
    "successful": true,
    "timestamp": "2025-05-26T14:38:36.643066258+08:00",
    "traceId": "5b3c49e18a4e1e4d"
}

OceanBase

Customer Stories

Documentation