You can call this operation to query the number of connected Message Queue for MQTT (MQTT) clients that subscribe to the specified topic.


OnsMqttQueryClientByTopic is typically used for service analysis. The devices that subscribe to a specific topic generally participate in the same activity. Through query by topic, you can obtain the number of devices that participate in this activity.

API operations are designed for you to implement custom management and development. Based on this, the MQTT broker throttles frequent calls that amount to 30 or more per minute. Therefore, do not call this operation in the main service process. To determine whether an MQTT client is connected, use the device online/offline notification function. If an MQTT client is online, this client has been connected to an MQTT broker.


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

Request parameters

Parameter Type Required Example Description
Action String Yes OnsMqttQueryClientByTopic

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

ParentTopic String Yes test

The parent topic that you want to query.

SubTopic String Yes /testmqtt

The subtopic that you want to query. This parameter can be unspecified if no subtopic exists.

InstanceId String No post-cn-0pp12gl****

The ID of the MQTT instance to which the topic you want to query belongs. This parameter is required for instances with separate namespaces.

Response parameters

Parameter Type Example Description

The structure of information about whether the MQTT client was connected to the MQTT broker.

OnlineCount Long 4

The total number of connected MQTT clients that subscribed to the specified topic.

RequestId String F7C7E53F-B753-4EAA-B204-5DDA173DE86F

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


Sample request

http(s)://[Endpoint]/? Action=OnsMqttQueryClientByTopic
&<Common request parameters>

Sample success response

XML format


JSON format


Error codes

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