Release Notes and Announcements

Release Notes

Product Introduction

TDMQ Product Series Introduction and Selection

What Is TDMQ for MQTT

Scenarios

Technical Architecture

Product series

MQTT Protocol Compatibility Notes

Comparison with Apache

High Availability

Product Constraints and Usage Quota

Basic Concepts

Supported Regions

Billing

Billing Overview

Renewal Instructions

Viewing Consumption Details

Overdue Payment Instructions

Refund

Getting Started

Guide for Getting Started

Preparations

Public Network Access

VPC Network Access

User Guide

Usage Process Guide

Configuring Account Permission

Creating a Cluster

Managing Topic

Connecting to the Cluster

Querying Messages

Managing Client

Managing a Cluster

Viewing Monitoring Metrics and Configuring Alarm Policies

Data Integration

Integrating Data Into SCF

Integrating Data Into CKafka

Integrating Data into RocketMQ

Development Guide

MQTT 5 Advanced Features

Data Plane HTTP API Description

Quota and Flow Control Mechanism Description

Configuring a Custom Domain Name

Configuring SQL Filtering

Configuring Point-to-Point Subscription

MQTT over QUIC

Managing Client Subscription

Message Enhancement Rule

Use Cases

Must-Knows for MQTT Client Development

Observability

Topic and Wildcard Subscriptions

API Reference

History

Introduction

API Category

Making API Requests

Cluster APIs

Topic APIs

Authorization Policy APIs

User APIs

Client APIs

Message Enhancement Rule APIs

Message APIs

Data Types

Error Codes

SDK Reference

Access Point Format

Java SDK

C SDK

Javascript/Node.JS/Mini Program

Go SDK

iOS SDK

JavaScript SDK

Dart SDK

Python SDK

.NET

Security and Compliance

Permission Management

FAQs

Related Agreement

Data Privacy And Security Agreement

TDMQ for MQTT Service Level Agreement

DescribeMessageByTopic

PDF

Focus Mode

Font Size

Last updated: 2026-01-13 21:49:32

1. API Description

Domain name for API request: mqtt.intl.tencentcloudapi.com.

This API is used to query messages based on subscription.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer

Try it

API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name	Required	Type	Description
Action	Yes	String	Common Params. The value used for this API: DescribeMessageByTopic.
Version	Yes	String	Common Params. The value used for this API: 2024-05-16.
Region	Yes	String	Common Params. For more information, please see the list of regions supported by the product.
InstanceId	Yes	String	tencent cloud MQTT instance ID, obtained from the DescribeInstanceList api or console.
Topic	Yes	String	home/room
StartTime	Yes	Integer	Start time. millisecond-level timestamp.
MaxNumber	No	Integer	Specifies the number of query messages. value range: 1-1024. default: 100.

3. Output Parameters

Parameter Name	Type	Description
Data	Array of MQTTMessage	Message List
RequestId	String	The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Example

This example shows you the example.

Input Example

POST / HTTP/1.1
Host: mqtt.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeMessageByTopic
<Common request parameters>

{
    "InstanceId": "mqtt-g839agr2",
    "Topic": "home/room3",
    "StartTime": 1745828681259
}

Output Example

{
    "Error": null,
    "RequestId": null,
    "Response": {
        "Data": [
            {
                "ClientId": "mqttxxxxxx",
                "MessageId": "15397032005D639FEE48935F932F004D",
                "OriginTopic": "home/room3",
                "Qos": "1",
                "StoreTimestamp": "2025-04-29 14:48:34"
            },
            {
                "ClientId": "mqttxxxxxx",
                "MessageId": "15397032005D639FEE48935FA6B80050",
                "OriginTopic": "home/room3",
                "Qos": "1",
                "StoreTimestamp": "2025-04-29 14:48:39"
            },
            {
                "ClientId": "mqttxxxxxx",
                "MessageId": "15397032005D639FEE48935FBA410057",
                "OriginTopic": "home/room3",
                "Qos": "1",
                "StoreTimestamp": "2025-04-29 14:48:44"
            },
            {
                "ClientId": "mqttxxxxxx",
                "MessageId": "15397032005D639FEE4893603732005C",
                "OriginTopic": "home/room3",
                "Qos": "1",
                "StoreTimestamp": "2025-04-29 14:49:16"
            }
        ],
        "RequestId": "6af56edc-5085-4583-8366-7f125c973603"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

Tencent Cloud CLI 3.0

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code	Description
FailedOperation.InstanceNotReady	FailedOperation.InstanceNotReady
ResourceNotFound.Instance	ResourceNotFound.Instance

Help and Support

Was this page helpful?

You can also Contact sales or Submit a Ticket for help.

Help us improve! Rate your documentation experience in 5 mins.

Feedback

tencent cloud

TDMQ for MQTT