Skip to main content

"listMqSessions" (JSON Action)

View a list of sessions that match the "partialClientName"

The "listMqSessions" action returns a list of all MQ sessions that match the "partialClientName". If "partialClientName" is omitted or set to null, it returns all MQ sessions, including those created by MQTT and the MQ API.

Request examples

Minimal

{
  "api": "mq",
  "action": "listMqSessions",
  "params": {},
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "api": "mq",
  "action": "listMqSessions",
  "params":
  {
    "partialClientName": "",
    "connectionStatusFilter": [ 
      "disconnected", 
      "connected", 
      "connectedTemporarily" 
    ],
    "sessionStatusFilter": [ 
      "normal", 
      "banned", 
      "hidden",
      "inactive" 
    ],
    "sessionTypeFilter": [ "mqtt", "mqApi" ],
    "healthFilter": [ "healthy", "unhealthy", "offline" ],
    "unsetHealthMeasures": true,
    "sortDescending": "lastConnect|lastDisconnect|clientName|ipAddress",
    "sortAscending": "lastConnect|lastDisconnect|clientName|ipAddress",

    "labelId": 423,

    "label": {
      "group": "group name",
      "name": "label name"
    }
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The listMqSessions action is a JSON API call used to retrieve a list of MQ sessions. It can filter sessions based on a partialClientName (acting as a "begins with" search), and if omitted or null, returns all MQ sessions, including those from MQTT and the MQ API. The request supports various optional parameters for filtering by connection status, health status, session status, and session type, as well as for sorting the results in ascending or descending order by connection/disconnection time, client name, or IP address, and for including sessions without health measures.

listMqSessionslist Mq SessionJSON ActionMQ APIMQ sessions listget MQ sessionsMQ get active sessionsget active MQ sessionslist MQTT sessionsMQ filter sessionssort MQ sessionsMQ API list sessionsretrieve MQ sessionslistMqSession json ActionMQ sessions APIMQ API get sessions actionlist sessions action

"params"

Table 1. listMqSessions "params" properties summary

Property

Description

Default

Type

Limits (inclusive)

connectionStatusFilter

(optional) filters the returned sessions by connection status

[]

array

"disconnected"
"connected"
"connectedTemporarily"

healthFilter

(optional) filters the returned sessions by health status

[]

array

"healthy"
"unhealthy"
"offline"

label

(optional) assigns a label to the object using the label's group and name.

null

object

"label": {
  "group": "group name",
  "name": "label name"
}
label
.group

(optional) identifies a label using its group description.

""

string

0 to 64 bytes

label
.name

(optional) identifies a label using its name.

""

string

0 to 64 bytes

labelID

(optional) assigns a label to the object using the label's ID.

null

integer

0 to 4294967296

partialClientName

(optional) specifies which sessions to return from the "listMqSessions" action

""

string

sessionStatusFilter

(optional) filters the returned sessions by session status

[]

array

"normal"
"banned"
"hidden"

sessionTypeFilter

(optional) filters the returned sessions by session type

[]

array

"mqtt"
"mqApi"

sortAscending

(optional) sorts the returned sessions in ascending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses

""

string

"lastConnect"
"lastDisconnect"
"clientName"
"ipAddress"

sortDescending

(optional) sorts the returned sessions in descending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses

""

string

"lastConnect"
"lastDisconnect"
"clientName"
"ipAddress"

unsetHealthMeasures

(optional) specifies whether or not to include sessions without health measures in the response

true

Boolean

true
false


"connectionStatusFilter"

The "connectionStatusFilter" property is an optional array that filters the returned sessions by the selected connection statuses.

"healthFilter"

The "healthFilter" property is an optional array that filters the returned sessions by the selected health statuses.

"label"

The optional "label" property assigns a label to an object. The "label" object contains "group" and "name" properties that uniquely identify a label. If you omit the "group" and "name" properties, they default to the empty string, "", which is a valid group and name for a label.

A label is a tag that you can add to some objects, such as an MQTT topic or session. You can use list actions such as "listTopics" and "listMqSessions" to find objects with a specific label.

The "label" property is mutually exclusive from the "labelId" property.

Example

"label": {
 "group": "group name",
 "name": "label name"
}

"label.group"

The optional "group" property is a child of the "label" property. It defaults to "", which is a valid group name.

A label's "group" and "name" properties work together to uniquely identify a label. If you omit the "group" and "name" properties, they default to the empty string, "", which is a unique and valid natural identifier for a label.

The "labelId" property is another way to uniquely identify a label.

Example

"label": {
  "group": "group name",
  "name": "label name"
}

"label.name"

The optional "name" property is a child of the "label" property. It defaults to "", which is a valid label name.

A label's "group" and "name" properties work together to uniquely identify a label. If you omit the "group" and "name" properties, they default to the empty string, "", which is a unique and valid natural identifier for a label.

The "labelId" property is another way to uniquely identify a label.

Example

"label": {
  "group": "group name",
  "name": "label name"
}

"labelId"

The optional "labelId" property assigns a label to an object. The "labelId" property uniquely identifies a label.

A label is a tag that you can add to some objects, such as an MQTT topic or session. You can use list actions such as "listTopics" and "listMqSessions" to find objects with a specific label.

The "labelId" property is mutually exclusive with the "label" property.

Example

"labelId": 423

"partialClientName"

The "partialClientName" property is a string that is used to specify which sessions to return from the "listMqSessions" action. This property behaves as a "begins with" search.

"sessionStatusFilter"

The "sessionStatusFilter" property is an optional array that filters the returned sessions by the selected session statuses.

"sessionTypeFilter"

The "sessionTypeFilter" property is an optional array that filters the returned sessions by the selected session types.

"sortAscending"

The "sortAscending" property is an optional string that sorts the returned sessions in ascending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses.

"sortDescending"

The "sortDescending" property is an optional string that sorts the returned sessions in descending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses.

"unsetHealthMeasures"

The "unsetHealthMeasures" property is an optional Boolean that specifies whether or not to include sessions without health measures in the response.