Updated on 2025-07-29 GMT+08:00

Querying HTAP Instances

Function

This API is used to query HTAP instances. Before calling this API:

URI

GET /v3/{project_id}/instances/{instance_id}/htap

Table 1 URI parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID of a tenant in a region.

To obtain this value, see Obtaining a Project ID.

Constraints

N/A

Range

The value contains 32 characters. Only letters and digits are allowed.

Default Value

N/A

instance_id

Yes

String

Definition

TaurusDB instance ID, which is compliant with the UUID format.

Constraints

N/A

Range

The value contains 36 characters with a suffix of in07. Only letters and digits are allowed.

Default Value

N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition

User token. To obtain this value, call the IAM API for obtaining a user token.

The value of X-Subject-Token in the response header is the token value.

Constraints

N/A

Range

N/A

Default Value

N/A

Content-Type

Yes

String

Definition

Content type.

Constraints

N/A

Range

application/json

Default Value

application/json

X-Language

No

String

Definition

Request language type.

Constraints

N/A

Range

  • en-us

  • zh-cn

Default Value

en-us

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

total

Integer

Definition

Number of HTAP instances.

Range

N/A

instances

Array of instances objects

Definition

HTAP instance information.

Range

N/A

max_htap_instance_num_of_taurus

Integer

Definition

Maximum number of HTAP instances that can be created.

Range

N/A

Table 4 instances

Parameter

Type

Description

id

String

Definition

HTAP instance ID, which is compliant with the UUID format.

Range

N/A

name

String

Definition

HTAP instance name.

Range

N/A

engine_name

String

Definition

HTAP DB engine name.

Range

N/A

engine_version

String

Definition

HTAP DB engine version.

Range

N/A

project_id

String

Definition

Project ID of a tenant in a region.

Range

N/A

instance_state

instance_state object

Definition

HTAP instance status information.

Range

N/A

create_at

Long

Definition

Time when the HTAP instance was created.

Range

N/A

is_frozen

Boolean

Definition

Whether the HTAP instance is frozen.

Range

N/A

ha_mode

String

Definition

HTAP instance deployment mode.

Range

N/A

pay_model

String

Definition

Billing mode. Only pay-per-use billing is supported.

Range

0: pay-per-use

1: yearly/monthly

order_id

String

Definition

Order ID for the yearly/monthly subscription.

Range

N/A

alter_order_id

String

Definition

Alternative order ID for the yearly/monthly subscription.

Range

N/A

data_vip

String

Definition

Private IP address.

Range

N/A

readable_node_infos

Array of ReadableNodeInfos objects

Definition

Readable node information.

Range

N/A

proxy_ips

Array of strings

Definition

Proxy IP addresses.

Range

N/A

data_vip_v6

String

Definition

Private IPv6 address.

Range

N/A

port

Integer

Definition

Database port.

Range

N/A

available_zones

Array of available_zones objects

Definition

AZ information.

Range

N/A

current_actions

Array of QueryAction objects

Definition

Instance actions.

Range

N/A

volume_type

String

Definition

Storage type.

Range

N/A

server_type

String

Definition

Server type.

Range

N/A

enterprise_project_id

String

Definition

Enterprise project ID. This parameter is mandatory when the enterprise project is enabled.

Range

N/A

dedicated_resource_id

String

Definition

Dedicated resource pool ID. This parameter is only available when the dedicated resource pool is enabled.

Range

N/A

network

network object

Definition

Network information.

Range

N/A

ch_master_node_id

String

Definition

ClickHouse primary node ID.

Range

N/A

node_num

Integer

Definition

Number of nodes.

Range

N/A

Table 5 instance_state

Parameter

Type

Description

instance_status

String

Definition

HTAP instance status.

Range

N/A

create_fail_error_code

String

Definition

Error code for HTAP instance creation failures.

Range

N/A

fail_message

String

Definition

Error message for HTAP instance creation failures.

Range

N/A

wait_restart_for_params

Boolean

Definition

Whether a reboot is required for parameter updates.

Range

N/A

Table 6 ReadableNodeInfos

Parameter

Type

Description

data_ip

String

Definition

IP address of the readable node.

Constraints

N/A

Range

N/A

Default Value

N/A

node_id

String

Definition

ID of the readable node.

Constraints

N/A

Range

N/A

Default Value

N/A

node_name

String

Definition

Name of the readable node.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 7 available_zones

Parameter

Type

Description

code

String

Definition

AZ code.

Range

N/A

description

String

Definition

AZ description.

Range

N/A

az_type

String

Definition

AZ type.

Range

N/A

Table 8 QueryAction

Parameter

Type

Description

id

String

Definition

Instance or node action ID.

Range

N/A

action

String

Definition

Instance or node action name.

Range

N/A

object_id

String

Definition

Object ID of the instance or node action.

Range

N/A

type

String

Definition

Instance or node action type.

Range

N/A

job_id

String

Definition

Task ID of the instance or node action.

Range

N/A

status

String

Definition

Instance or node action status.

Range

N/A

created_at

Long

Definition

Time when the instance or node action was created.

Range

N/A

updated_at

Long

Definition

Time when the instance or node action was updated.

Range

N/A

Table 9 network

Parameter

Type

Description

vpc_id

String

Definition

VPC ID.

Range

N/A

sub_net_id

String

Definition

Subnet ID.

Range

N/A

security_group_id

String

Definition

Security group ID.

Range

N/A

Status code: 400

Table 10 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Status code: 500

Table 11 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Error message.

Example Request

Querying HTAP instances of a TaurusDB instance

GET https://{endpoint}/v3/23a50154cf494ec9ad6883979a12db0a/instances/18c3eeb7b788479eb8b93b209946a83bin07/htap

Example Response

Status code: 200

Success.

{
  "total" : 2,
  "instances" : [ {
    "id" : "5fbd54b94f0f4adbb17f728f581d247ein17",
    "name" : "htap-1f05",
    "engine_name" : "star-rocks",
    "engine_version" : "3.1.11",
    "project_id" : "23a50154cf494ec9ad6883979a12db0a",
    "instance_state" : {
      "instance_status" : "normal",
      "create_fail_error_code" : null,
      "fail_message" : null,
      "wait_restart_for_params" : false
    },
    "create_at" : 1716364704475,
    "is_frozen" : false,
    "ha_mode" : "Cluster",
    "pay_model" : "0",
    "order_id" : null,
    "alter_order_id" : "",
    "data_vip" : "192.168.8.69,192.168.8.28,192.168.8.91",
    "readable_node_infos" : [ {
      "data_ip" : "192.168.8.69",
      "node_id" : "48e89b523de54a168bdd5ce0d6c134f0no17",
      "node_name" : "htap-1f05_fe_shard01_node01"
    }, {
      "data_ip" : "192.168.8.28",
      "node_id" : "70bcbaef85164a299188cc6798de67f6no17",
      "node_name" : "htap-1f05_fe_shard01_node02"
    }, {
      "data_ip" : "192.168.8.91",
      "node_id" : "f50fdf0c1e7447b3bca7d9eefe9d4a30no17",
      "node_name" : "htap-1f05_fe_shard01_node03"
    } ],
    "proxy_ips" : [ ],
    "data_vip_v6" : null,
    "port" : 3306,
    "available_zones" : [ {
      "code" : "cn-southwest-244d",
      "description" : "az4",
      "az_type" : "Center"
    } ],
    "current_actions" : [ ],
    "volume_type" : "SSD",
    "server_type" : "KVM",
    "enterprise_project_id" : "0",
    "dedicated_resource_id" : "",
    "network" : {
      "vpc_id" : "f7876b94-3696-419b-a609-161de4b42d59",
      "sub_net_id" : "09249318-4a97-4e48-b314-ffaab86d4295",
      "security_group_id" : ""
    },
    "ch_master_node_id" : null,
    "node_num" : 6
  }, {
    "id" : "914481def3574d5189baee926a26512din17",
    "name" : "htap-5d98",
    "engine_name" : "star-rocks",
    "engine_version" : "3.1.11",
    "project_id" : "23a50154cf494ec9ad6883979a12db0a",
    "instance_state" : {
      "instance_status" : "normal",
      "create_fail_error_code" : "500000",
      "fail_message" : null,
      "wait_restart_for_params" : false
    },
    "create_at" : 1716344516418,
    "is_frozen" : false,
    "ha_mode" : "Single",
    "pay_model" : "0",
    "order_id" : null,
    "alter_order_id" : "",
    "data_vip" : "192.168.8.4",
    "readable_node_infos" : [ {
      "data_ip" : "192.168.8.4",
      "node_id" : "7739bfbc4e244a8bac0662d63683c808no17",
      "node_name" : "htap-5d98_fe_shard01_node01"
    } ],
    "proxy_ips" : [ ],
    "data_vip_v6" : null,
    "port" : 3306,
    "available_zones" : [ {
      "code" : "cn-southwest-244d",
      "description" : "az4",
      "az_type" : "Center"
    } ],
    "current_actions" : [ ],
    "volume_type" : "SSD",
    "server_type" : "KVM",
    "enterprise_project_id" : "0",
    "dedicated_resource_id" : "",
    "network" : {
      "vpc_id" : "f7876b94-3696-419b-a609-161de4b42d59",
      "sub_net_id" : "09249318-4a97-4e48-b314-ffaab86d4295",
      "security_group_id" : ""
    },
    "ch_master_node_id" : null,
    "node_num" : 2
  } ],
  "max_htap_instance_num_of_taurus" : 10
}

Status Code

For details, see Status Codes.

Error Code

For details, see Error Codes.