Updated on 2025-08-06 GMT+08:00

Querying the Cluster List

Function

This API is used to query the cluster list.

Calling Method

For details, see Calling APIs.

URI

GET /v1.0/{project_id}/clusters

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. To obtain the value, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

enterprise_project_id

No

String

Definition

Enterprise project ID. If all clusters bound to enterprise projects are queried, the value is all_granted_eps.

Constraints

N/A

Range

all_granted_eps: all enterprise projects

0: default enterprise project

Others: data of the corresponding enterprise project

Default Value

N/A

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

clusters

Array of ClusterInfo objects

Definition

Cluster object list.

Range

N/A

count

Integer

Definition

Total number of clusters.

Range

N/A

Table 4 ClusterInfo

Parameter

Type

Description

id

String

Definition

Cluster ID.

Range

N/A

name

String

Definition

Cluster name.

Range

The value must be unique under the same account ID.

status

String

Definition

Cluster status. The value is an enumerated string.

Range

  • CREATING: The cluster is being created.

  • ACTIVE: The cluster is available.

  • FAILED: The cluster is unavailable.

  • CREATE_FAILED: The cluster failed to be created.

  • DELETING: The cluster is being deleted.

  • DELETE_FAILED: The cluster failed to be deleted.

  • FROZEN: The cluster is frozen.

  • POLICE_FROZEN: The cluster is frozen by the public security.

version

String

Definition

DWS cluster version.

Range

The value contains three to four characters separated by decimal points, for example, 9.1.0.200. A larger value indicates a later version.

updated

String

Definition

Last modification time of a cluster. The format is ISO8601:YYYY-MM-DDThh:mm:ssZ.

Range

The value must be an ISO8601 time and later than or equal to the cluster creation time.

created

String

Definition

Cluster creation time in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ).

Range

Time in ISO 8601 format.

port

Integer

Definition

Cluster service port. If this parameter is not specified when a cluster is created, the default value 8000 is used.

Range

8000 to 30000

endpoints

Array of Endpoints objects

Definition

Private network connection information about the cluster.

Range

N/A

nodes

Array of Nodes objects

Definition

Cluster nodes.

Range

The number of rows in the list is the same as the value of the number_of_node field.

tags

Array of Tags objects

Definition

Cluster tags.

Range

The default value is null.

user_name

String

Definition

Administrator username.

Range

The default value is dbadmin.

number_of_node

Integer

Definition

Number of nodes. This parameter is specified when a cluster is created.

Range

N/A

recent_event

Integer

Definition

Number of events. Only user operations that affect clusters are recorded. The switch operations of certain buttons are not recorded as cluster events.

Range

N/A

availability_zone

String

Definition

AZ.

Range

N/A

enterprise_project_id

String

Definition

Enterprise project ID for a cluster. If this parameter is not specified, the default value 0 (indicating that the ID of the default enterprise project) is used.

Constraints

N/A

Range

N/A

Default Value

0

node_type

String

Definition

Cluster flavor ID.

Range

N/A

vpc_id

String

Definition

VPC ID.

Range

N/A

subnet_id

String

Definition

Subnet ID.

Range

N/A

public_ip

PublicIp object

Definition

Public IP address. If the parameter is not specified, public connection is not used by default.

Range

N/A

public_endpoints

Array of PublicEndpoints objects

Definition

Public IP address. If the parameter is not specified, public connection is not used by default.

Range

N/A

action_progress

Map<String,String>

Definition

Task information. It consists of a key and a value. The key indicates an ongoing task, and the value indicates the progress of the ongoing task.

Range

The key can contain but is not limited to the following values:

  • CREATING

  • RESTORING

  • SNAPSHOTTING

  • GROWING

  • REBOOTING

  • SETTING_CONFIGURATION: Security settings are being configured.

  • CONFIGURING_EXT_DATASOURCE: The MRS connection is being configured.

  • ADD_CN_ING: A CN is being added.

  • DEL_CN_ING: A CN is being deleted.

  • REDISTRIBUTING: Redistribution is in progress.

  • ELB_BINDING: An ELB is being bound.

  • ELB_UNBINDING: An ELB is being unbound.

  • ELB_SWITCHING: An ELB is being switched.

  • NETWORK_CONFIGURING: The network is being configured.

  • DISK_EXPANDING: The disk is being expanded.

  • ACTIVE_STANDY_SWITCHOVER: The primary/standby switchover is being performed.

  • CLUSTER_SHRINKING: The cluster is being scaled in.

  • SHRINK_CHECKING: Cluster scale-in check is being performed.

  • FLAVOR_RESIZING: The flavor is being changed.

  • MANAGE_IP_BINDING: Login is being enabled.

  • FINE_GRAINED_RESTORING: The fine-grained restoration is in progress.

  • DR_RECOVERING: The DR recovery is in progress.

  • REPAIRING: The cluster is being repaired.

sub_status

String

Definition

Sub-status of the available clusters.

Range

NORMAL

  • READONLY

  • REDISTRIBUTING

  • REDISTRIBUTION-FAILURE

  • UNBALANCED

  • UNBALANCED | READONLY

  • DEGRADED

  • DEGRADED | READONLY

  • DEGRADED | UNBALANCED

  • UNBALANCED | REDISTRIBUTING

  • UNBALANCED | REDISTRIBUTION-FAILURE

  • READONLY | REDISTRIBUTION-FAILURE

  • UNBALANCED | READONLY | REDISTRIBUTION-FAILURE

  • DEGRADED | REDISTRIBUTION-FAILURE

  • DEGRADED | UNBALANCED | READONLY | REDISTRIBUTION-FAILURE

  • DEGRADED | UNBALANCED | READONLY

DEGRADED | UNBALANCED | REDISTRIBUTION-FAILURE

task_status

String

Definition

Result of an ongoing task or an executed task for cluster management.

Range

The value can contain but is not limited to the following values:

  • UNFREEZING

  • FREEZING

  • RESTORING

  • SNAPSHOTTING

  • GROWING

  • REBOOTING

  • SETTING_CONFIGURATION: Security settings are being configured.

  • CONFIGURING_EXT_DATASOURCE: The MRS connection is being configured.

  • DELETING_EXT_DATASOURCE: The MRS connection is being deleted.

  • REBOOT_FAILURE: The reboot failed.

  • RESIZE_FAILURE: The scale-out failed.

  • ADD_CN_ING: A CN is being added.

  • DEL_CN_ING: A CN is being deleted.

  • CREATING_NODE: A node is being added.

  • CREATE_NODE_FAILED: The node failed to be added.

  • DELETING_NODE: The node is being deleted.

  • DELETE_NODE_FAILED: The node failed to be deleted.

  • REDISTRIBUTING: Redistribution is in progress.

  • REDISTRIBUTE_FAILURE: Redistribution failed.

  • WAITING_REDISTRIBUTION: Redistribution is waiting.

  • REDISTRIBUTION_PAUSED: Redistribution is paused.

  • ELB_BINDING: An ELB is being bound.

  • ELB_BIND_FAILED: An ELB failed to be bound.

  • ELB_UNBINDING: An ELB is being unbound.

  • ELB_UNBIND_FAILED: An ELB failed to be unbound.

  • ELB_SWITCHING: An ELB is being switched.

  • ELB_SWITCHING_FAILED: An ELB failed to be switched.

  • NETWORK_CONFIGURING: The network is being configured.

  • NETWORK_CONFIG_FAILED: Network configuration failed.

  • DISK_EXPAND_FAILED: Disk capacity expansion failed.

  • DISK_EXPANDING: The disk is being expanded.

  • ACTIVE_STANDY_SWITCHOVER: The primary/standby switchover is being performed.

  • ACTIVE_STANDY_SWITCHOVER_FAILURE: The primary/standby switchover failed.

  • CLUSTER_SHRINK_FAILED: The cluster scale-in failed.

  • CLUSTER_SHRINKING: The cluster is being scaled in.

  • SHRINK_CHECK_FAILED: The cluster scale-in check failed.

  • SHRINK_CHECKING: Cluster scale-in check is being performed.

  • FLAVOR_RESIZING_FAILED: The flavor change failed.

  • FLAVOR_RESIZING: The flavor is being changed.

  • MANAGE_IP_BIND_FAILED: Login failed to be enabled.

  • MANAGE_IP_BINDING: Login is being enabled.

  • ORDER_PENDING: The order is pending to be paid.

  • FINE_GRAINED_RESTORING: The fine-grained restoration is in progress.

  • DR_RECOVERING: The DR recovery is in progress.

security_group_id

String

Definition

Security group ID.

Range

N/A

failed_reasons

FailedReason object

Definition

Failure cause. If the parameter is left blank, the cluster is in the normal state.

Range

N/A

Table 5 Endpoints

Parameter

Type

Description

connect_info

String

Definition

Private network connection information.

Range

N/A

jdbc_url

String

Definition

JDBC URL of the private network.

Constraints

N/A

Range

N/A

Default Value

jdbc:postgresql://<connect_info>/<YOUR_DATABASE_NAME>

Table 6 Nodes

Parameter

Type

Description

id

String

Definition

Cluster instance ID.

Range

N/A

status

String

Definition

Cluster instance status.

Range

100: creating

199: idle

200: available

300: unavailable

303: creation failed

304: deleting

305: deletion failed

400: deleted

name

String

Definition

Instance name.

Range

N/A

Table 7 Tags

Parameter

Type

Description

key

String

Definition

Tag key.

Constraints

N/A

Range

  • It can contain a maximum of 128 Unicode characters. It cannot be an empty string, and cannot start or end with a space.

  • It cannot contain the following characters: =*<>\,|/

  • Only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-) are allowed.

Default Value

N/A

value

String

Definition

Tag value.

Constraints

N/A

Range

  • The value can contain a maximum of 256 characters and can be an empty string. It cannot start or end with a space.

  • It cannot contain the following characters: =*<>\,|/

  • Only uppercase letters, lowercase letters, digits, underscores (_), and hyphens (-) are allowed.

Default Value

N/A

Table 8 PublicIp

Parameter

Type

Description

public_bind_type

String

Definition

EIP binding type.

Constraints

N/A

Range

auto_assign

not_use

bind_existing

Default Value

null

eip_id

String

Definition

EIP ID.

Constraints

N/A

Range

N/A

Default Value

null

Table 9 PublicEndpoints

Parameter

Type

Description

public_connect_info

String

Definition

Public network connection information.

Range

N/A

jdbc_url

String

Definition

JDBC connection string of the public network.

Constraints

N/A

Range

N/A

Default Value

jdbc:postgresql://<public_connect_info>/<YOUR_DATABASE_name>

Table 10 FailedReason

Parameter

Type

Description

error_code

String

Definition

Error code.

Range

N/A

error_msg

String

Definition

Error message.

Range

N/A

Example Requests

Query the cluster list.

GET https://{Endpoint}/v1.0/89cd04f168b84af6be287f71730fdb4b/clusters?enterprise_project_id=all_granted_eps

Example Responses

Status code: 200

Cluster list queried.

{
  "clusters" : [ {
    "id" : "7d85f602-a948-4a30-afd4-e84f47471c15",
    "name" : "dws-1",
    "status" : "AVAILABLE",
    "version" : "1.2.0",
    "updated" : "2016-02-10T14:28:14Z",
    "created" : "2016-02-10T14:26:14Z",
    "port" : 8000,
    "endpoints" : [ {
      "connect_info" : "dws-1.cn-north-4.dwscloud.com",
      "jdbc_url" : "jdbc:postgresql://dws-1.cn-north-4.dwscloud.com/<YOUR_DATABASE_name>"
    } ],
    "nodes" : [ {
      "id" : "acaf62a4-41b3-4106-bf6b-2f669d88291e",
      "name" : "dws-1-dws-cn-cn-1-1",
      "status" : "200"
    }, {
      "id" : "d32de51e-4fcd-4e5a-a9dc-bb903abb494b",
      "name" : "dws-1-dws-cn-cn-2-1",
      "status" : "200"
    }, {
      "id" : "d71a4a25-c9bc-4ffd-9f4a-e422aef327f9",
      "name" : "dws-1-dws-cn-cn-3-1",
      "status" : "200"
    } ],
    "tags" : [ {
      "key" : "key1",
      "value" : "value1"
    }, {
      "key" : "key2",
      "value" : "value2"
    } ],
    "user_name" : "dbadmin",
    "number_of_node" : 3,
    "recent_event" : 6,
    "availability_zone" : "cn-north-4b",
    "enterprise_project_id" : "0",
    "node_type" : "dws.d1.xlarge.ultrahigh",
    "vpc_id" : "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574",
    "subnet_id" : "374eca02-cfc4-4de7-8ab5-dbebf7d9a720",
    "public_ip" : {
      "public_bind_type" : "auto_assign",
      "eip_id" : "85b20d7e-9eb7-4b2a-98f3-3c8843ea3574"
    },
    "public_endpoints" : [ {
      "public_connect_info" : "dws-1.cn-north-4.dwscloud.com",
      "jdbc_url" : "jdbc:postgresql://dws-1.cn-north-4.dwscloud.com/<YOUR_DATABASE_name>"
    } ],
    "action_progress" : {
      "SNAPSHOTTING" : "20%"
    },
    "sub_status" : "READONLY",
    "task_status" : "SNAPSHOTTING",
    "security_group_id" : "dc3ec145-9029-4b39-b5a3-ace5a01f772b"
  } ]
}

Status Codes

Status Code

Description

200

Cluster list queried.

400

Request error.

401

Authentication failed.

403

You do not have required permissions.

404

No resources found.

500

Internal server error.

503

Service unavailable.