Skip to content

Clients API

This API documentation provides information on various operations related to managing MQTT clients, including viewing all client information, viewing a specific client information, and kicking clients.

Clients

URI

GET /clients

Returns information for all clients under the cluster, with support for pagination.

Parameters:

NameTypeRequiredDescription
clientidStringFalseClient identifier
usernameStringFalseClient username
zoneStringFalseClient configuration group name
ip_addressStringFalseClient IP address
conn_stateEnumFalseThe current connection status of the client, the possible values areconnected,idle,disconnected
clean_startBoolFalseWhether the client uses a new session
proto_nameEnumFalseClient protocol name, the possible values areMQTT,CoAP,MQTT-SN
proto_verIntegerFalseClient protocol version
_like_clientidStringFalseFuzzy search of client identifier by substring method
_like_usernameStringFalseClient user name, fuzzy search by substring
_gte_created_atIntegerFalseSearch client session creation time by less than or equal method
_lte_created_atIntegerFalseSearch client session creation time by greater than or equal method
_gte_connected_atIntegerFalseSearch client connection creation time by less than or equal method
_lte_connected_atIntegerFalseSearch client connection creation time by greater than or equal method

Request Message

None.

Response Message

NameTypeDescription
codeInteger0
dataArray of ObjectsInformation for all clients
data[0].nodeStringName of the node to which the client is connected
data[0].clientidStringClient identifier
data[0].usernameStringUser name of client when connecting
data[0].proto_nameStringClient protocol name
data[0].proto_verIntegerProtocol version used by the client
data[0].ip_addressStringClient's IP address
data[0].portIntegerClient port
data[0].is_bridgeBooleanIndicates whether the client is connected via bridge
data[0].connected_atStringClient connection time, in the format of "YYYY-MM-DD HH:mm:ss"
data[0].disconnected_atStringClient offline time, in the format of "YYYY-MM-DD HH:mm:ss", This field is only valid and returned when connected isfalse
data[0].connectedBooleanWhether the client is connected
data[0].zoneStringIndicate the configuration group used by the client
data[0].keepaliveIntegerkeepalive time, with the unit of second
data[0].clean_startBooleanIndicate whether the client is using a brand new session
data[0].expiry_intervalIntegerSession expiration interval, with the unit of second
data[0].created_atStringSession creation time, in the format "YYYY-MM-DD HH:mm:ss"
data[0].subscriptions_cntIntegerNumber of subscriptions established by this client
data[0].max_subscriptionsIntegerMaximum number of subscriptions allowed by this client
data[0].inflightIntegerCurrent length of inflight
data[0].max_inflightIntegerMaximum length of inflight
data[0].mqueue_lenIntegerCurrent length of message queue
data[0].max_mqueueIntegerMaximum length of message queue
data[0].mqueue_droppedIntegerNumber of messages dropped by the message queue due to exceeding the length
data[0].awaiting_relIntegerNumber of awaiting PUBREC packet
data[0].max_awaiting_relIntegerMaximum allowed number of awaiting PUBREC packet
data[0].recv_octIntegerNumber of bytes received by EMQX Broker (the same below)
data[0].recv_cntIntegerNumber of TCP packets received
data[0].recv_pktIntegerNumber of MQTT packets received
data[0].recv_msgIntegerNumber of PUBLISH packets received
data[0].send_octIntegerNumber of bytes sent
data[0].send_cntIntegerNumber of TCP packets sent
data[0].send_pktIntegerNumber of MQTT packets sent
data[0].send_msgIntegerNumber of PUBLISH packets sent
data[0].mailbox_lenIntegerProcess mailbox size
data[0].heap_sizeIntegerProcess heap size with the unit of byte
data[0].reductionsIntegerErlang reduction
metaObjectPaging information
meta.pageIntegerPage number
meta.limitIntegerNumber of data displayed per page
meta.countIntegerTotal number of data

Request Example

bash
$ curl -u app_id:app_secret -X GET {api}/clients?_page=1&_limit=10

Response Example

JSON
{
  "meta": {
    "page": 1,
    "limit": 10000,
    "hasnext": false,
    "count": 1
  },
  "data": [
    {
      "recv_cnt": 45,
      "send_pkt": 44,
      "clean_start": true,
      "expiry_interval": 0,
      "proto_ver": 4,
      "recv_msg": 0,
      "connected_at": "2021-03-18 02:15:57",
      "recv_oct": 164,
      "is_bridge": false,
      "connected": true,
      "max_awaiting_rel": 100,
      "heap_size": 610,
      "mqueue_dropped": 0,
      "recv_pkt": 2,
      "ip_address": "127.0.0.1",
      "max_subscriptions": 0,
      "created_at": "2021-03-18 02:15:57",
      "awaiting_rel": 0,
      "mountpoint": "undefined",
      "node": "emqx@10.12.50.91",
      "proto_name": "MQTT",
      "mailbox_len": 0,
      "send_msg": 2,
      "clientid": "emqx_c_1",
      "mqueue_len": 0,
      "inflight": 0,
      "max_mqueue": 1000,
      "subscriptions_cnt": 4,
      "keepalive": 60,
      "reductions": 35471,
      "zone": "external",
      "send_cnt": 44,
      "username": "test",
      "send_oct": 159,
      "port": 3107,
      "max_inflight": 32
    }
  ],
  "code": 0
}

Check Information for the Specified Client

URI

GET /clients/{clientid}

Return information for the specified client.

Parameter:

NameTypeDescription
clientidStringclientid

Request Message

None.

Response Message

NameTypeDescription
codeInteger0
dataArray of ObjectsClient information,see detail GET /clients

Request Example

Check specified client

bash
$ curl -u app_id:app_ssecret -X GET {api}/clients/emqx_c_1

Response Example

JSON
{
  "data": [
    {
      "recv_cnt": 49,
      "send_pkt": 48,
      "clean_start": true,
      "expiry_interval": 0,
      "proto_ver": 4,
      "recv_msg": 0,
      "connected_at": "2021-03-18 02:15:57",
      "recv_oct": 172,
      "is_bridge": false,
      "connected": true,
      "max_awaiting_rel": 100,
      "heap_size": 610,
      "mqueue_dropped": 0,
      "recv_pkt": 2,
      "ip_address": "127.0.0.1",
      "max_subscriptions": 0,
      "created_at": "2021-03-18 02:15:57",
      "awaiting_rel": 0,
      "mountpoint": "undefined",
      "node": "emqx@10.12.50.91",
      "proto_name": "MQTT",
      "mailbox_len": 0,
      "send_msg": 2,
      "clientid": "emqx_c_1",
      "mqueue_len": 0,
      "inflight": 0,
      "max_mqueue": 1000,
      "subscriptions_cnt": 4,
      "keepalive": 60,
      "reductions": 38501,
      "zone": "external",
      "send_cnt": 48,
      "username": "test",
      "send_oct": 167,
      "port": 3107,
      "max_inflight": 32
    }
  ],
  "code": 0
}

Kick a Client

URI

DELETE /clients/{clientid} Kick a specified client off. Note that kicking the client terminates the connection and the session.

Parameter:

NameTypeDescription
clientidStringclientid

Request Message

None.

Respond Message

NameTypeDescription
codeInteger0

Request Example

bash
$ curl -u app_id:app_secret -X DELETE {api}/clients/emqx_c_1

Response Example

JSON
{
  "code": 0
}