Queries all dead-letter messages for a specified group ID within a specified time range by page.

Usage notes

  • It is a range query to query messages based on a group ID. Query results are displayed to the caller by page. This operation is applicable only when no message ID is specified.
  • We recommend that you minimize the time range to query. Otherwise, it will be difficult to locate problems due to an excessive number of matched messages. To call this operation, perform the following steps:

    1. Specify the group ID, start time, end time, and number of entries on each page to return. If matched messages are found, the first page of the messages, total number of pages, and query task ID are returned by default.

    2. Query messages by specifying the returned query task ID and the current page number.

QPS limit

The queries-per-second (QPS) limit on this operation is 10 per user. Throttling is triggered when the number of calls to this operation exceeds this limit. Throttling may affect your business. Therefore, call this operation based on your needs. For more information, see QPS limits.

Authorization information

By default, only Alibaba Cloud accounts can call this operation. Resource Access Management (RAM) users can call this operation only after they are authorized. The following table lists the authorization information of this operation. For more information, see Policies and examples.



Resource with a namespace

Resource without a namespace






OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes OnsDLQMessagePageQueryByGroupId

The operation that you want to perform. Set the value to OnsDLQMessagePageQueryByGroupId.

BeginTime Long Yes 1570723200000

The timestamp that indicates the beginning of the time range to query. Unit: milliseconds.

CurrentPage Integer Yes 2

The number of the page to return. Pages start from page 1. Valid values: 1 to 50.

EndTime Long Yes 1570809600000

The timestamp that indicates the end of the time range to query. Unit: milliseconds.

GroupId String Yes GID_test_group_id

The ID of the consumer group whose dead-letter queue messages you want to query.

InstanceId String Yes MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance where the consumer group whose dead-letter queue messages you want to query is located.

TaskId String No 0BC1310300002A9F000021E4D7A48346

The ID of the query task. It is not required for the first query but is required in subsequent queries for these messages. You can obtain the ID from the returned result of the first query.

PageSize Integer No 5

The number of entries to return on each page. Valid values: 5 to 50. Default value: 20.

Note For more information about request parameters, see Common parameters and Make API requests.

Response parameters

Parameter Type Example Description
MsgFoundDo Struct

The returned query results.

CurrentPage Long 1

The page number of the returned page.

MaxPageCount Long 400

The maximum number of returned pages.

MsgFoundList Array of OnsRestMessageDo

A returned set of messages displayed on the current page. The results are the same as those returned for the call to the OnsDLQMessageGetById operation.

BodyCRC Integer 914112295

The Cyclic Redundancy Check (CRC) value of the message body.

BornHost String 42.120.***.***:59270

The producer instance that produced the message.

BornTimestamp Long 1570760999721

The timestamp that indicates when the message was produced.

InstanceId String MQ_INST_111111111111_DOxxxxxx

The ID of the Message Queue for Apache RocketMQ instance.

MsgId String 1E0578FE110F18B4AAC235C05F2*****

The ID of the message.

PropertyList Array of MessageProperty

A returned list of properties of the message.

Name String TAGS

The property of the message. Valid values:

  • TRACE_ON: indicates whether a trace of the message exists.
  • KEYS: indicates the key property of the message.
  • TAGS: indicates the tag property of the message.
  • INSTANCE_ID: indicates the ID of the Message Queue for Apache RocketMQ instance that corresponds to the message.

For more information about the terms, see Terms.

Value String TagA

The value of the message property.

ReconsumeTimes Integer 1

The number of consumption retries of the message.

StoreHost String 11.193.***.***:10911

The Message Queue for Apache RocketMQ broker that stored the message.

StoreSize Integer 406

The size of the message.

StoreTimestamp Long 1570760999811

The timestamp that indicates when the Message Queue for Apache RocketMQ broker stored the message.

Topic String test-mq_topic

The topic of the message.

TaskId String 0BC1310300002A9F000021E4D7A48346

The task ID returned for the first query task, which is used to subsequently query messages.

RequestId String B00CD3C8-D81E-4A41-85E2-38F19252****

The ID of the request, which is a common parameter. Each request has a unique ID, which facilitates troubleshooting and fault locating.


Sample requests

&<Common request parameters>

Sample success responses

XML format


JSON format

    "OnsDLQMessagePageQueryByGroupIdResponse": {
        "MsgFoundDo": {
            "MaxPageCount": 400,
            "MsgFoundList": {
                "OnsRestMessageDo": {
                    "MsgId": "1E0578FE110F18B4AAC235C05F2*****",
                    "InstanceId": "MQ_INST_111111111111_DOxxxxxx",
                    "ReconsumeTimes": 1,
                    "BornHost": "42.120.***.***:59270",
                    "StoreTimestamp": 1570760999811,
                    "StoreHost": "11.193.***.***:10911",
                    "BodyCRC": 914112295,
                    "Topic": "test-mq_topic",
                    "BornTimestamp": 1570760999721,
                    "StoreSize": 406,
                    "PropertyList": {
                        "MessageProperty": [                            
                                "Name": "TAGS",
                                "Value": "TagA"
            "TaskId": "0BC1310300002A9F000021E4D7A48346",
            "CurrentPage": 1
        "RequestId": "5DC2A47E-2B31-4722-96C8-FA59C9*****"

Error codes

For a list of error codes, visit the API Error Center.

Operations in the console

In addition to calling the OnsDLQMessagePageQueryByGroupId operation, you can query dead-letter message in the Message Queue for Apache RocketMQ console. For more information, see Dead-letter queues.