Help Center/ Distributed Message Service for RocketMQ/ API Reference/ APIs V2 (Recommended)/ Topic Management/ Querying a Topic
Updated on 2026-04-30 GMT+08:00
View PDF

Querying a Topic

Function

This API is used to query a topic.

URI

GET /v2/{project_id}/instances/{instance_id}/topics/{topic}

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

instance_id

Yes

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

topic

Yes

String

Topic name.

Request Parameters

None

Response Parameters

Status code: 200

Table 2 Response body parameters

Parameter

Type

Description

name

String

Definition

Topic name.

Constraints

N/A

Range

N/A

Default Value

N/A

total_read_queue_num

Number

Definition

Total number of read queues.

Constraints

N/A

Range

N/A

Default Value

N/A

total_write_queue_num

Number

Definition

Total number of write queues.

Constraints

N/A

Range

N/A

Default Value

N/A

permission

String

Definition

Permission.

Constraints

N/A

Range

  • sub: subscribe permissions.

  • pub: publish permissions.

  • all: subscribe and publish permissions.

Default Value

N/A

created_at

String

Definition

Creation time.

Constraints

N/A

Range

N/A

Default Value

N/A

brokers

Array of brokers objects

Definition

Associated broker.

Constraints

N/A

Range

N/A

Default Value

N/A

message_type

String

Definition

Message type (available only for RocketMQ 5.x instances).

Constraints

N/A

Range

  • NORMAL: normal messages.

  • FIFO: ordered messages.

  • DELAY: scheduled messages.

  • TRANSACTION: transactional messages.

Default Value

N/A
Table 3 brokers

Parameter

Type

Description

broker_name

String

Definition

Broker name.

Constraints

N/A

Range

N/A

Default Value

N/A

read_queue_num

Number

Definition

Number of read queues.

Constraints

N/A

Range

N/A

Default Value

N/A

write_queue_num

Number

Definition

Number of write queues.

Constraints

N/A

Range

N/A

Default Value

N/A

Example Requests

Querying details about a specified topic

GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/topics/{topic}

Example Responses

Status code: 200

Topic queried successfully.

{
  "name" : "topic",
  "total_read_queue_num" : 3,
  "total_write_queue_num" : 3,
  "permission" : "all",
  "brokers" : [ {
    "broker_name" : "broker-0",
    "read_queue_num" : 3,
    "write_queue_num" : 3
  } ],
  "message_type" : "NORMAL"
}

Status Codes

Status Code

Description

200

Topic queried successfully.

Error Codes

See Error Codes.

Parent Topic: Topic Management