Help Center/ Distributed Message Service for RocketMQ/ API Reference/ APIs V2 (Recommended)/ Lifecycle Management/ Querying the Instance List
Updated on 2025-12-18 GMT+08:00
View PDF

Querying the Instance List

Function

This API is used to query the instances of an account by the specified conditions.

URI

GET /v2/{project_id}/instances

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

Project ID. For details about how to obtain it, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

engine

Yes

String

Definition

Message engine type.

Constraints

N/A

Range

  • rocketmq: RocketMQ engine.

  • reliability: RocketMQ engine alias.

Default Value

N/A

name

No

String

Definition

Instance name.

Constraints

N/A

Range

N/A

Default value

N/A

instance_id

No

String

Definition

Instance ID. You can call the API for querying all instances to obtain the instance ID. The instance ID is in the response body.

Constraints

N/A

Range

N/A

Default Value

N/A

status

No

String

Definition

Instance status.

Constraints

N/A

Range

For details, see Instance Status.

Default Value

N/A

include_failure

No

String

Definition

Whether to return the number of instances that fail to be created.

Constraints

N/A

Range

  • 'true': yes

  • 'false': no

Default value

N/A

exact_match_name

No

String

Definition

Whether to search for the instance that precisely matches a specified instance name.

Constraints

N/A

Range

  • 'true': yes

  • 'false': no

Default value

'false'

enterprise_project_id

No

String

Definition

Enterprise project ID.

Constraints

N/A

Range

N/A

Default value

N/A

limit

No

Integer

Definition

Maximum number of instances that can be returned in a query.

Constraints

N/A

Range

1–50

Default value

10

offset

No

Integer

Definition

Offset where the query starts.

Constraints

N/A

Range

≥ 0

Default value

N/A

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

instances

Array of InstanceDetail objects

Definition

Instance list.

Range

N/A

instance_num

Integer

Definition

Number of instances.

Range

N/A
Table 4 InstanceDetail

Parameter

Type

Description

name

String

Definition

Instance name.

Range

N/A

engine

String

Definition

Message engine.

Range

  • rocketmq: RocketMQ message engine.

  • reliability: RocketMQ message engine alias.

status

String

Definition

Status.

Range

For details, see Instance Status.

description

String

Definition

Message description.

Range

N/A

type

String

Definition

Instance type.

Range

  • single: 4.8.0 single-node.

  • cluster: 4.8.0 cluster

  • single.basic: 5.x single-node basic edition

  • cluster.basic: 5.x cluster basic edition

  • cluster.professional: 5.x cluster professional edition

specification

String

Definition

Instance specification.

Range

N/A

engine_version

String

Definition

Instance version.

Range

  • 4.8.0

  • 5.x

instance_id

String

Definition

Instance ID.

Range

N/A

arch_type

String

Definition

Architecture type.

Range

  • X86

  • ARM

charging_mode

Integer

Definition

Billing mode.

Range

1: pay-per-use; 0: yearly/monthly.

vpc_id

String

Definition

VPC ID.

Range

N/A

vpc_name

String

Definition

VPC name.

Range

N/A

created_at

String

Definition

Time when creation is complete.

The time is in the format of timestamp, that is, the offset milliseconds from 1970-01-01 00:00:00 UTC to the specified time.

Range:

N/A

product_id

String

Definition

Product flavor.

Range

  • c6.4u8g.cluster.small: Max. 2,000 topics and 2,000 consumer groups per broker

  • c6.4u8g.cluster: Max. 4,000 topics and 4,000 consumer groups per broker

  • c6.8u16g.cluster: Max. 8,000 topics and 8,000 consumer groups per broker

  • c6.12u24g.cluster: Max. 12,000 topics and 12,000 consumer groups per broker

  • c6.16u32g.cluster: Max. 16,000 topics and 16,000 consumer groups per broker

  • rocketmq.b1.large.1: RocketMQ 5.x basic edition single-node flavor, instance TPS 500

  • rocketmq.b2.large.4: RocketMQ 5.x basic edition cluster flavor, instance TPS 2,000

  • rocketmq.b2.large.8: RocketMQ 5.x basic edition cluster flavor, instance TPS 4,000

  • rocketmq.b2.large.12: RocketMQ 5.x basic edition cluster flavor, instance TPS 6,000

  • rocketmq.p1.large.1: RocketMQ 5.x professional edition single-node flavor, instance TPS 500

  • rocketmq.p2.large.8: RocketMQ 5.x professional edition cluster flavor, instance TPS 4,000

  • rocketmq.p2.large.12: RocketMQ 5.x professional edition cluster flavor, instance TPS 6,000

  • rocketmq.p2.large.20: RocketMQ 5.x professional edition cluster flavor, instance TPS 10,000

  • rocketmq.p2.large.40: RocketMQ 5.x professional edition cluster flavor, instance TPS 20,000

  • rocketmq.p2.large.100: RocketMQ 5.x professional edition cluster flavor, instance TPS 50,000

  • rocketmq.p2.large.150: RocketMQ 5.x professional edition cluster flavor, instance TPS 75,000

  • rocketmq.p2.large.200: RocketMQ 5.x professional edition cluster flavor, instance TPS 100,000

  • rocketmq.p2.large.300: RocketMQ 5.x professional edition cluster flavor, instance TPS 150,000

security_group_id

String

Definition

Security group ID.

Range

N/A

security_group_name

String

Definition

Security group name.

Range

N/A

subnet_id

String

Definition

Subnet ID.

Range

N/A

subnet_cidr

String

Definition

Subnet route.

Range

N/A

available_zones

Array of strings

Definition

List of AZ IDs.

Value range:

N/A

available_zone_names

Array of strings

Definition

List of AZ names.

user_id

String

Definition

User ID.

Range

N/A

user_name

String

Definition

Username.

Range

N/A

maintain_begin

String

Definition

Time at which the maintenance window starts. The format is HH:mm:ss.

Range

N/A

maintain_end

String

Definition

Time at which the maintenance window ends. The format is HH:mm:ss.

Range

N/A

enable_log_collection

Boolean

Definition

Whether log collection is enabled.

Range

  • true: yes

  • false: no

storage_space

Integer

Definition

Storage space, in GB.

Range

Different instance specifications support different storage configurations.

used_storage_space

Integer

Definition

Used message storage space, in GB.

Range

N/A

enable_publicip

Boolean

Definition

Whether to enable public access.

Range

  • true: yes

  • false: no

publicip_id

String

Definition

ID of the EIP bound to the instance.

Use commas (,) to separate multiple EIP IDs.

This parameter is mandatory if public access is enabled (that is, enable_publicip is set to true).

Range

N/A

publicip_address

String

Definition

Public IP address.

Range

N/A

ssl_enable

Boolean

Definition

Whether SSL is enabled.

Range

  • true: yes

  • false: no

cross_vpc_info

String

Definition

Cross-VPC access information.

Range

N/A

storage_resource_id

String

Definition

Storage resource ID.

Range

N/A

storage_spec_code

String

Definition

Storage specification code.

Range

  • dms.physical.storage.high.v2: high I/O disk

  • dms.physical.storage.ultra.v2: ultra-high I/O disk

service_type

String

Definition

Service type.

Range

  • advanced: Service type.

storage_type

String

Definition

Storage type.

Range

  • hec: Storage type.

extend_times

Long

Definition

Extension time.

Range

N/A

ipv6_enable

Boolean

Definition

Whether IPv6 is enabled.

Range

  • true: Yes

  • false: No

support_features

String

Definition

Features supported by the instance.

Range

N/A

disk_encrypted

Boolean

Definition

Whether disk encryption is enabled.

Range

  • true: yes

  • false: no

ces_version

String

Definition

Cloud Eye version.

Range

N/A

node_num

Integer

Definition

Number of nodes. (This field is available only for RocketMQ 4.8.0 instances.)

Range

N/A

new_spec_billing_enable

Boolean

Definition

Whether billing based on new specifications is enabled.

Range

  • true: yes

  • false: no

enable_acl

Boolean

Definition

Whether access control is enabled.

Range

  • true: yes

  • false: no

broker_num

Integer

Definition

Number of brokers.

Range

N/A

dns_enable

Boolean

Definition

Whether to enable domain name access to an instance.

Range

  • true: yes

  • false: no

namesrv_address

String

Definition

Metadata address.

Range

N/A

namesrv_domain_name

String

Definition

Metadata domain name.

Range

N/A

broker_address

String

Definition

Service data address.

Range

N/A

public_namesrv_address

String

Definition

Public network metadata address.

Range

N/A

public_namesrv_domain_name

String

Definition

Public metadata domain name.

Range

N/A

public_broker_address

String

Definition

Public network service data address.

Range

N/A

grpc_address

String

Definition

gRPC connection address (displayed only for RocketMQ 5.x).

Range

N/A

grpc_domain_name

String

Definition

gRPC connection domain name (displayed only for RocketMQ 5.x).

Range

N/A

public_grpc_address

String

Definition

Public gRPC connection address (displayed only for RocketMQ 5.x).

Range

N/A

public_grpc_domain_name

String

Definition

Public gRPC domain name (displayed only for RocketMQ 5.x).

Range

N/A

enterprise_project_id

String

Definition

Enterprise project ID.

Range

N/A

tags

Array of TagEntity objects

Definition

Tag list.

Range

N/A

total_storage_space

Integer

Definition

Total storage space.

Range

N/A

resource_spec_code

String

Definition

Resource flavor.

Range

N/A

produce_portion

Integer

Definition

Production TPS proportion.

Range

N/A

consume_portion

Integer

Definition

Consumption TPS proportion.

Range

N/A

dr_enable

Boolean

Definition

Whether the instance has disaster recovery (DR).

Range

  • true: Yes

  • false: No

quota_address

String

Definition

Quota address.

Range

N/A

max_msg_process_tps

Integer

Definition

Maximum message TPS.

Range

N/A

config_ssl_need_restart_process

Boolean

Definition

Whether a restart is required to configure SSL.

Range

  • true: Yes

  • false: No

tls_mode

String

Definition

Security protocol used by the instance.

Range

N/A
Table 5 TagEntity

Parameter

Type

Description

key

String

Tag key.

  • Must be specified.

  • Must be unique for the same instance.

  • Can contain 1 to 128 characters.

  • Can contain letters, digits, spaces, and special characters _.:=+-@

  • Cannot start or end with a space.

value

String

Tag value.

  • Can contain 0 to 255 characters.

  • Can contain letters, digits, spaces, and special characters _.:=+-@

  • Cannot start or end with a space.

Example Requests

Querying the list of all instances

GET https://{endpoint}/v2/{project_id}/instances?engine=reliability

Example Responses

Status code: 200

Instance list queried successfully.

{
  "instances" : [ {
    "name" : "reliability-ztest",
    "engine" : "reliability",
    "status" : "RUNNING",
    "description" : "",
    "type" : "cluster",
    "specification" : "c6.4u8g.cluster * 1 broker",
    "engine_version" : "4.8.0",
    "instance_id" : "68fdc9a8-805e-439d-8dd9-25adc1c58bf6",
    "resource_spec_code" : "",
    "charging_mode" : 1,
    "vpc_id" : "3db8490c-4d6d-4d8f-8d3f-047b0de4c5cf",
    "vpc_name" : "vpc-1101840",
    "created_at" : "1636699753874",
    "product_id" : "c6.4u8g.cluster",
    "security_group_id" : "23c5977f-ff33-4b95-a73e-08d8a0bc4e6c",
    "security_group_name" : "Sys-default",
    "subnet_id" : "0a0f1fcb-f019-458d-b9e5-301867394d50",
    "subnet_cidr" : "192.168.0.0/24",
    "available_zones" : [ "9f1c5806706d4c1fb0eb72f0a9b18c77" ],
    "available_zone_names" : [ "AZ3" ],
    "user_id" : "0b01fbb53600d4671fa8c00673c71260",
    "user_name" : "",
    "maintain_begin" : "02:00:00",
    "maintain_end" : "06:00:00",
    "enable_log_collection" : false,
    "storage_space" : 558,
    "total_storage_space" : 600,
    "used_storage_space" : 28,
    "enable_publicip" : false,
    "ssl_enable" : false,
    "arch_type" : "X86",
    "cross_vpc_info" : "{\"192.168.1.21\":{\"advertised_ip\":\"192.168.1.21\",\"broker_port\":\"-\",\"port_id\":\"fa020857-d899-497c-a5f8-8dd90ed67ff7\",\"namesrv_port\":\"8301\"},\"192.168.1.246\":{\"advertised_ip\":\"192.168.1.246\",\"broker_port\":\"10100\",\"port_id\":\"c0f0586f-a4ee-41b5-a7f1-b4e554bbf12d\",\"namesrv_port\":\"-\"},\"192.168.1.77\":{\"advertised_ip\":\"192.168.1.77\",\"broker_port\":\"10101\",\"port_id\":\"8eb1d144-4315-402f-8498-37c9a10b630c\",\"namesrv_port\":\"-\"},\"192.168.1.159\":{\"advertised_ip\":\"192.168.1.159\",\"broker_port\":\"-\",\"port_id\":\"d35b22af-a202-4329-bda4-26e1bdf2aa8e\",\"namesrv_port\":\"8300\"},\"192.168.1.14\":{\"advertised_ip\":\"192.168.1.14\",\"broker_port\":\"10102\",\"port_id\":\"5fcb50fd-3af5-4123-a455-a67f1b926026\",\"namesrv_port\":\"-\"}}",
    "storage_resource_id" : "164bdaef-2e67-4fd5-be8b-a18f91d455a2",
    "storage_spec_code" : "dms.physical.storage.ultra.v2",
    "service_type" : "advanced",
    "storage_type" : "hec",
    "enterprise_project_id" : "0",
    "extend_times" : 0,
    "ipv6_enable" : false,
    "support_features" : "features.log.collection",
    "disk_encrypted" : false,
    "enable_acl" : true,
    "ces_version" : "linux,v1,v2",
    "node_num" : 5,
    "new_spec_billing_enable" : true,
    "broker_num" : 1,
    "dr_enable" : false,
    "namesrv_address" : "***",
    "config_ssl_need_restart_process" : false,
    "broker_address" : "***",
    "public_namesrv_address" : "***",
    "public_broker_address" : "***",
    "grpc_address" : "***",
    "public_grpc_address" : "***"
  } ],
  "instance_num" : 1
}

Status Codes

Status Code

Description

200

Instance list queried successfully.

Error Codes

See Error Codes.

Parent Topic: Lifecycle Management