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

Querying Messages

Function

This API is used to query messages.

URI

GET /v2/{engine}/{project_id}/instances/{instance_id}/messages

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

engine

Yes

String

Definition

Message engine.

Constraints

N/A

Range

  • rocketmq: RocketMQ message engine.

  • reliability: RocketMQ message engine alias.

Default Value

N/A

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

topic

Yes

String

Topic name.

queue

No

String

Queue.

limit

No

Integer

Definition

Number of records to query.

Constraints

N/A

Range

NOTE:
0

Default Value

10

offset

No

Integer

Definition

Offset.

Constraints

N/A

Range

≥ 0

Default Value

0

key

No

String

Key of a message.

start_time

No

String

Start time. This parameter is mandatory when msg_id is not used for query.

end_time

No

String

End time. This parameter is mandatory when msg_id is not used for query.

msg_id

No

String

Definition

Message ID.

Constraints

Mandatory when a time range is not used for query.

Range

N/A

Default Value

N/A

Request Parameters

None

Response Parameters

Status code: 200

Table 3 Response body parameters

Parameter

Type

Description

messages

Array of Message objects

Definition

Message list.

Constraints

N/A

Range

N/A

Default Value

N/A

total

Number

Definition

Total number of messages.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 4 Message

Parameter

Type

Description

msg_id

String

Definition

Message ID.

Constraints

N/A

Range

N/A

Default Value

N/A

instance_id

String

Definition

Instance ID.

Constraints

N/A

Range

N/A

Default Value

N/A

topic

String

Definition

Topic name.

Constraints

N/A

Range

N/A

Default Value

N/A

store_timestamp

Number

Definition

Time when the message is stored.

Constraints

N/A

Range

N/A

Default Value

N/A

born_timestamp

Number

Definition

Time when the message is generated.

Constraints

N/A

Range

N/A

Default Value

N/A

reconsume_times

Integer

Number of retry times.

body

String

Definition

Message body.

Constraints

N/A

Range

N/A

Default Value

N/A

body_crc

Number

Definition

Message body checksum.

Constraints

N/A

Range

N/A

Default Value

N/A

store_size

Number

Definition

Storage size.

Constraints

N/A

Range

N/A

Default Value

N/A

property_list

Array of property_list objects

Definition

Message attribute list.

Constraints

N/A

Range

N/A

Default Value

N/A

born_host

String

Definition

IP address of the host that generates the message.

Constraints

N/A

Range

N/A

Default Value

N/A

store_host

String

Definition

IP address of the host that stores the message.

Constraints

N/A

Range

N/A

Default Value

N/A

queue_id

Integer

Definition

Queue ID.

Constraints

N/A

Range

N/A

Default Value

N/A

queue_offset

Integer

Definition

Offset in the queue.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 5 property_list

Parameter

Type

Description

name

String

Definition

Attribute name.

Constraints

N/A

Range

N/A

Default Value

N/A

value

String

Definition

Attribute value.

Constraints

N/A

Range

N/A

Default Value

N/A

Example Requests

Querying messages

GET https://{endpoint}/v2/{engine}/{project_id}/instances/{instance_id}/messages?topic={topic}&msg_id=C0A807C9000027740000000000000030

Example Responses

Status code: 200

Messages queried successfully.

{
  "messages" : [ {
    "msg_id" : "C0A807C9000027740000000000000030",
    "instance_id" : "11c45539-xxxx-xxxx-xxxx-812c41f61f30",
    "topic" : "topic-test",
    "store_timestamp" : 1648888166319,
    "born_timestamp" : 1648888166275,
    "reconsume_times" : 0,
    "body" : "xxxx",
    "body_crc" : 1932557065,
    "store_size" : 175,
    "property_list" : [ {
      "name" : "KEYS",
      "value" : ""
    }, {
      "name" : "UNIQ_KEY",
      "value" : "7F00000123DC6E0BE85808B037820000"
    }, {
      "name" : "CLUSTER",
      "value" : "DmsCluster"
    }, {
      "name" : "TAGS",
      "value" : ""
    } ],
    "born_host" : "192.168.0.66:50098",
    "store_host" : "192.168.7.201:10100",
    "queue_id" : 2,
    "queue_offset" : 0
  } ],
  "total" : 1
}

Status Codes

Status Code

Description

200

Messages queried successfully.

Error Codes

See Error Codes.

Parent Topic: Message Management