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

Querying the Topic List

Function

This API is used to query the topic list of a RocketMQ instance.

URI

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

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
Table 2 Query Parameters

Parameter

Mandatory

Type

Description

limit

No

Integer

Definition

Number of records to 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

0

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

total

Integer

Definition

Total number of topics.

Constraints

N/A

Range

N/A

Default Value

N/A

max

Integer

Definition

Maximum number of topics that can be created.

Constraints

N/A

Range

N/A

Default Value

N/A

remaining

Integer

Definition

Remaining number of topics that can be created.

Constraints

N/A

Range

N/A

Default Value

N/A

next_offset

Integer

Definition

Offset of the next page.

Constraints

N/A

Range

N/A

Default Value

N/A

previous_offset

Integer

Definition

Offset of the previous page.

Constraints

N/A

Range

N/A

Default Value

N/A

topics

Array of Topic objects

Definition

Remaining number of topics that can be created.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 4 Topic

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 5 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 a list of 10 topics of a specified RocketMQ instance from offset=0

GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/topics?offset=0&limit=10

Example Responses

Status code: 200

Query succeeded.

{
  "total" : 3,
  "max" : 2000,
  "remaining" : 1997,
  "next_offset" : -1,
  "previous_offset" : -1,
  "topics" : [ {
    "name" : "topic-1",
    "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"
  }, {
    "name" : "topic-2",
    "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"
  }, {
    "name" : "topic-3",
    "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

Query succeeded.

Error Codes

See Error Codes.

Parent Topic: Topic Management