listMqSessions

View a list of 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

{
  "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"
}
 
 

 

Response example

Maximal

{
  "authToken": "3Am1nttU8tj5j17SLy3RKexcaxuVN9YW8szWLpQdsy9yChXtKw3g2xKbcqbtJkr6",
  "result": {
    "data": [
      {
        "clientName": "client1",
        "sessionType": "mqApi"
      }
    ]
  },
  "requestId": "00000003",
}
 
 

 

Properties 

Request properties ("params")

Property Description Default Type Limits (inclusive)

connectionStatusFilter

The "connectionStatusFilter" property filters the returned sessions by the selected connection statuses. The "listThings" action uses it to return things that match the specified connection states. Omitting the property or setting it to null matches all things.
 

 Optional with default of [] array

"disconnected"

"connected"

"connectedTemporarily"

"unknown"

healthFilter

The "healthFilter" property filters the returned sessions by the selected "sessionHealth" statuses.

 Optional with default of [] array

"healthy"

"unhealthy"

"offline"

label

The "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.

 Optional with default of null object 
"label": {
  "group": "group name",
  "name": "label name"
}

label

.group

The "group" property groups labels into a lookup list or tag set. It is a namespace for a set of labels that identifies their purpose. You can use the "listLabelGroups" action to return the list groups. You can use the "listLabels" action to return labels in one or more groups. 

The "group" and "name" properties work together to uniquely identify each label. They are its natural key. 

When you assign a group name to a label, the server automatically checks if the group name exists in the list of groups that the "listLabelGroups" action returns. If the group name does not exist, the server adds the group name to the list. When you rename a group assigned to a label, the server automatically adds a new group name to the list and removes the previous group name if no other label uses it.

Tip If your application creates many groups, you can use a delimiter character, such as the forward slash / in your group names to create a group hierarchy. Include the delimiter after each part of the hierarchy and at the end of the group name. In the "listLabels" action, you can use the "partialGroupFilter" filter to return subsets of groups in the hierarchy. For example, you if have groups named "product/size/", "product/weight/", "product/ranking/", "person/gender/", and "person/ranking/", you can set the "partialGroupFilter" to "product/" to return the product groups.

 Optional with default of "" string 1 to 64 bytes of UTF-8 encoded characters

label

.name

The "name" property is the name of a label or field. 

The "group" and "name" properties combined uniquely identify each label. The "createLabel" and "alterLabel" actions return an error if the "group" and "name" properties do not create a unique label name.

The "id" property also uniquely identifies each label, so you can rename a label's group and name without breaking "id" references to the label.

 

 Required - No default value string 1 to 64 bytes

labelId

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.

 Optional with default of null integer 0 to 4294967296

partialClientName

The "partialClientName" property specifies which sessions to return from the "listMqSessions" action. This property behaves as a "begins with" search.

 Optional with default of "" string  

sessionStatusFilter

The "sessionStatusFilter" property filters the returned sessions by the selected session statuses.

 Optional with default of [] array

"normal"

"banned"

"hidden"

sessionTypeFilter

The "sessionTypeFilter" property filters the returned sessions by the selected session types.

 Optional with default of [] array

"mqtt"

"mqApi"

sortAscending

The "sortAscending" property 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.

 Optional with default of "" string

"lastConnect"

"lastDisconnect"

"clientName"

"ipAddress"

sortDescending

The "sortDescending" property 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.

"fields": [
  {
    "sortDescending": true
  }
]
 Optional with default of false Boolean

true

false

unsetHealthMeasures

The "unsetHealthMeasures" property specifies whether or not to include sessions without health measures in the response.

 Optional with default of true Boolean

true

false

 

Response properties ("result")

Property Description Type Limits (inclusive)

data

The "data" property contains a response message. Its contents are defined by the action. It is an empty array when no results are available. The following is an example of the data property from a code package action.

  "result": {
    "data": [
      {
        "codeId": 6,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertAndCategorizeTemperature",
        "codeVersion": 1,
        "clonedCodeId": 1,
        "codeStatus": "active",
        "codeLanguage": "javascript",
        "serviceName": "javascript",
        "codeType": "module",
        "description": "optional new description",
        "metadata": {},
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109",
        "comment": "Cloned from convertTemperature",
        "codeFormat": "utf8"
      },
    ]
 array of objects The action determines its contents.

data

.clientName

 The "Clientname" property uniquely identifies an MQ session. string 0 to 65,550 bytes

data

.sessionType

 The "sessionType" property specifies which type of session the requested client is currently running. string

"mqApi"

"mqtt"

"both"

 

Was this article helpful?

Give feedback about this article

Related Articles