describeTopics

JSON MQ "describeTopics" action returns info about MQTT topics

The "describeTopics" action returns all available information about specified MQTT topics.

 

Request examples

Minimal

{
  "apiVersion": "1.0",
  "action": "describeTopics",
  "params": {
    "topics": [
      "test/topic1"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Minimal

{
  "result": {
    "data": [
      {
        "name": "test/topic1",
        "creationTime": "2024-02-01T23:47:45.814",
        "messageCount": 2,
        "lastMessageTime": "2024-02-01T23:47:51.716",
        "averageMessagesPerMinute": 0,
        "averageMessagesPerHour": 0,
        "averageMessagesPerDay": 0,
        "subscriberList": [
          {
            "topicExpression": "#",
            "connectionList": [
              {
                "connection": {
                  "clientId": "mqtt-explorer-001",
                  "ipaddress": "127.0.0.1",
                  "port": 35646,
                  "mqttProtocol": 4,
                  "keepAliveSeconds": 60,
                  "status": "Connected with clean flag = 1",
                  "connectionTime": "2024-01-31T17:31:19"
                },
                "qos": 0
              }
            ]
          },
          {
            "topicExpression": "test/#",
            "connectionList": [
              {
                "connection": {
                  "clientId": "NodeREDSecure",
                  "ipaddress": "127.0.0.1",
                  "port": 36115,
                  "mqttProtocol": 4,
                  "keepAliveSeconds": 60,
                  "status": "Connected with clean flag = 1",
                  "connectionTime": "2024-01-31T17:31:30"
                },
                "qos": 1
              }
            ]
          }
        ],
        "persistence": {
          "topic": "test/topic1",
          "mqttPayloadType": "json",
          "databaseConnectionString": "FAIRCOMS",
          "databaseUserName": "admin",
          "databaseName": "faircom",
          "tableName": "mqtt_msg_test_topic1",
          "ownerName": "admin",
          "threads": 1,
          "tableAutoTimeStamp": true,
          "tableAutoTimeStampIndex": true,
          "tableReplicationReady": true,
          "retentionPolicy": "autoPurge",
          "retentionUnit": "week",
          "retentionPeriod": 4,
          "storeAndForward": true,
          "maxDeliveryRatePerSecond": 0,
          "newSubscriberDeliveryMode": "default",
          "newSubscriberMaxDeliveredMessages": 0,
          "retrySeconds": 20,
          "outputPayloadField": "source_payload",
          "label": {
            "id": 1,
            "group": "test",
            "name": "test",
            "value": null,
            "enum": null,
            "sequence": 0,
            "deprecated": false,
            "description": null,
            "metadata": null
          }
        }
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

topics

The "topics" property specifies the name of each "topic" that you want to be described in the results.

 Optional with default of []

array

 0 or more topic strings

 

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

.averageMessagesPerDay

 The "averageMessagesPerDay" property describes how many messages the specified topic publishes per day on average. integer The average number of messages published per day

data

.averageMessagesPerHour

 The "averageMessagesPerHour" property indicates the average number of messages the specified topic publishes per hour. integer The average number of messages published per hour

data

.averageMessagesPerMinute

 The "averageMessagesPerMinute" property indicates the average number of messages the specified topic publishes per minute. integer The average number of messages published per minute

data

.creationTime

 The "creationTime" property details the date and time when the specified topic was created. This property stores the creation date in an ISO 8601 timestamp. timestamp An ISO 8601 timestamp

data

.lastMessageTime

 The "lastMessageTime" property specifies the last time that a message was published by the topic.  timestamp An ISO 8601 timestamp

data

.messageCount

 The "messageCount" property defines the total number of messages published by the topic. BigInteger 0 to 9223372036854775807

data

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

 string 1 to 64 bytes

data

.persistence

 The "persistence" property defines the parameters of the persistence table. object

"databaseConnectionString"

"databaseName"

"databaseUserName"

"maxDeliveryRatePerSecond"

"mqttPayloadType"

"newSubscriberDeliveryMode"

"newSubscriberMaxDeliveredMessages"

"outputPayloadField"

"ownerName"

"retentionPeriod"

"retentionPolicy"

"retentionUnit"

"retrySeconds"

"tableName"

"tableReplicationReady"

"threads"

"topic"

“validateMqttPayload”

data

persistence

.databaseConnectionString

 The "databaseConnectionString" property specifies the connection string for the database that holds the persistence table. string No limits

data

persistence

.databaseName

The "databaseName" property specifies the database that contains the tables. 

Note In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

  • If the "databaseName" property is omitted or set to null, the server will use the default database name specified at login.
  • If no default database is specified during "createSession", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.
  • This property's value is case insensitive. 
 string 1 to 64 bytes

data

persistence

.databaseUserName

 The "databaseUserName" property specifies the user name of the account logged into the database that holds the persistence table. string 0 to 64 bytes

data

persistence

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

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

data

persistence

label

.deprecated

The "deprecated" property deprecates a label. Set it to true to deprecate a label and false to preserve it. Deprecating a label is similar to marking a label as deleted.

 Boolean

true

false

null

data

persistence

label

.description

The "description" property provides additional information about an object, such as a label or thing. You can use it as internal or external documentation of a label's meaning, purpose, and usage.

Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character:  \".

 

In the Thing API, It defaults to "unknown" and is a string from 1 to 512 bytes. You cannot use it for lookups and filtering.

 

 string 1 to 65,500 bytes

data

persistence

label

.enum

The "enum" property assigns an integer from -32768 to 32767 to a label. You can use this property to assign an application's hardcoded enumerated value to a label.

 

 smallint -32768 to 32767

data

persistence

label

.group

The "group" property groups labels into a lookup list or tag set. It is an optional 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. A group assigned to the empty string "" is the default group.

If the "group" property is omitted when creating a label, the group defaults to the empty string, "", which is the catch-all group.

When you assign a group name to a label, the server automatically checks whether the group name exists in the list of groups returned by the "listLabelGroups" action. 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.

 

 string 1 to 64 bytes

data

persistence

label

.id

The "id" property is the unique identifier of an object such as a label or thing. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create a label and stores it in the label table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property.

 integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API 

data

persistence

label

.metadata

The "metadata" field allows a customer to add a JSON value to an object such as a label or thing. It is typically a JSON object, but may be any JSON value. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.

 JSON 0 to 65,500 bytes

data

persistence

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.

 

 string 1 to 64 bytes

data

persistence

label

.sequence

The "sequence" property assigns an order to the labels in a group. You can use a floating point or integer number. You may embed the number in a JSON string. It defines the order of labels in a group. It is a floating point number to make it easy to change label order without renumbering all labels in a group. For example, to move a label in between two other labels, you can assign a fractional number to the label that is in between the sequence numbers of two other labels.

 float Any floating point or integer number.

data

persistence

label

.value

The "value" property associates a value with a label. It can be any JSON value that is associated with a label.

 

When you use the "alterLabel" action to update the "value" property, it replaces "value" with an entirely new value. It cannot replace parts of the JSON value.

 

In Key-Value actions, the "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 JSON 0 to 65,500 bytes

data

persistence

.maxDeliveryRatePerSecond

The "maxDeliveryRatePerSecond" property sets the throttle rate for current and new subscribers of the topic. If this property is omitted, it defaults to 0, which means no throttling is applied.

  • It must be a value between 0 and 2,147,483,647, but a more realistic range is between 0 and 1,000. It is useful to keep a client from being overwhelmed with too many messages sent too quickly.
  • You can set it to a number greater than 0 to throttle the delivery rate. This allows you to avoid saturating the network and other resources.
    • For example, you can set it to 100 to throttle the delivery to 100 messages per second. This is a maximum setting because the actual message delivery rate is bounded by the network, local resources, the hardware running FairCom's servers, and a client’s ability to process messages quickly.
 integer 0 to 2147483647

data

persistence

.mqttPayloadType

 The "mqttPayloadType" property specifies the variant type format of the "source_payload" field. For more details, see mqttPayloadType.  string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

data

persistence

.newSubscriberDeliveryMode

The "newSubscriberDeliveryMode" property defines how new subscribers receive messages. 

  • It may be set to one of two values:
    • "newMessages" (default)
    • "storedMessages"
  • When set to "newMessages" new subscribers only receive new messages.
  • When set to "storedMessages" new subscribers will receive some or all previously sent messages. The "newSubscriberDeliveryMode" property defines the maximum number of messages.
 string enum

"newMessages"

"storedMessages"

data

persistence

.newSubscriberMaxDeliveredMessages

The "newSubscriberMaxDeliveredMessages" property is the maximum number of previously stored historical messages a client receives automatically when subscribing to a topic.

  • A value of -1 or "all" defaults to delivering all currently stored messages.
  • A non-negative number limits the delivery of currently stored messages to that number. 
  • This property only applies when the "newSubscriberDeliveryMode" property is set to "storedMessages".
  • The broker can only send messages stored in the topic’s integration table. The table's retention policy automatically removes old messages.
  • Each time a client unsubscribes from a topic and then subscribes to the topic, the broker sends historical messages as specified by this property. A client can use this behavior to reprocess messages, such as refresh a local data cache or recalculate aggregates.

Note A topic’s "retentionPolicy", "retentionUnit", and "retentionPeriod" properties define how long the broker retains messages in a topic’s integration table.

 integer -1 to 2147483647

data

persistence

.outputPayloadField

The "outputPayloadField" property specifies the field that the MQTT Subscription service should use as the payload when it sends the payload to subscribers. 

  • "outputPayloadField" must be one of the following values: 
    • "source_payload" (default) allows
    • A user-defined field

This makes it possible for the output from any transform to be used as the payload delivered to subscribers.

 string "source_payload" or a user-defined field

data

persistence

.ownerName

 The "ownerName" property identifies the user who owns an object (see Object owner).  string 0 to 64 bytes

data

persistence

.retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It must be an integer value from 1 to 100. It refers to the unit of time specified by the "retentionUnit" property — for example, if "retentionPeriod" is 14 and "retentionUnit" is "day", then message data is retained for 14 days. This property is optional.

  • Periodically, the system increments the age of each table partition.
    • "Minute" units are incremented at the zero second of each minute, whether the table partition was created 1 second before or 59 seconds before.
    • "Day" units are incremented at midnight GMT, not midnight of the local UTC time zone. A table partition becomes one day old at midnight GMT, whether it was created one second before or 23 hours and 59 seconds before.
    • "Week" units are incremented at midnight GMT on the last day of each week, even if the table partition was created one second before. The last day of the week is Saturday GMT.
    • "Month" units are incremented at midnight GMT on the last day of each month.
    • "Year" units are incremented at midnight GMT on Dec 31.
  • "retentionPeriod" implicitly calculates an upper bound on how many partitions are able to accumulate on your hard drive. However, partitions are not deleted just because this calculated number of partitions is reached. The system also does not restrict the deletion of all partitions.
  • If the FairCom database is shut down for a month, when the database is started up again, all partitions that are retained for less than one month are immediately deleted.
  • If someone purposely or accidentally sets the date to a future date, all partitions immediately become older, and auto-deletion ensues accordingly.

When partitions are auto-purged, some data are maintained "forever" in a global index. Auto-purge does not prevent these files from growing without bounds and filling up your hard drive.

Automatically purging data is important to ensure that retained data does not consume all storage and shut down the computer. The default value of 4 weeks allows FairCom's servers to store 1 TB of messages when 200 topics send one 2K message per second.

Note 

  • If the value is not an integer from 1 to 100, FairCom's servers set it to the default value.
  • Smaller numbers improve SQL performance.
  • Each time the "retentionPeriod" cycles, FairCom's servers automatically and efficiently delete expired data.
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".
  • FairCom's servers only use the "retentionPeriod" property when the "retentionPolicy" is "autoPurge".
  • The "retentionPeriod" can be changed to retain fewer or more messages. Changing it does not necessarily destroy existing data, but data may expire more quickly or be retained longer.
  • The "retentionPeriod" and "retentionUnit" properties control data granularity as well as the retention time. In other words, "retentionPeriod" defines how many sets of data are stored, and "retentionUnit" defines how often data is purged.
    • For example, if "rententionPeriod" is set to 14 , the server stores 14 sets of data. At the beginning of the 15th cycle, the server automatically purges the oldest set of data. If "retentionUnit" is set to day, then data will be purged daily. If set to "week", then data will be purged weekly.
  • The current calendar date affects purging.
    • FairCom's servers automatically purge all retained data that has expired. This is noticeable when FairCom's servers come online after having been offline for a long time. When a server comes back online, it automatically purges all expired data.
    • For example, if a FairCom server is offline for four weeks when it comes online, it will completely purge all retained data that has a retention time of less than 4 weeks.
 integer 1 to 100

data

persistence

.retentionPolicy

The "retentionPolicy" property controls how messages are persisted. 

Possible values:
  • "autoPurge"
    • This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.
  • "neverPurge"
    • This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.
 string enum

"autoPurge"

"neverPurge"

data

persistence

.retentionUnit

Each time this unit cycles, FairCom purges expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.
  • "retentionUnit" values:
    • "minute"
    • "hour"
    • "day"
    • "week"
    • "month"
    • "year"
    • "forever"

Note 

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 
  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".
 string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

data

persistence

.retrySeconds

The "retrySeconds" property is the number of seconds that FairCom's MQTT broker will wait for the next expected packet from a client during a QoS 1 or QoS 2 PUBLISH packet exchange/PUBLISH handshake with an MQTT client. It applies when a client publishes to the broker and when the broker publishes to a client. This property does not apply to QoS 0 PUBLISH operations because QoS 0 PUBLISH operations are not answered. 

  • If the "retrySeconds" time expires, FairCom's broker will disconnect the MQTT client with MQTT error code 7.  MQTT 5 clients will also receive a Reason Code.  An error message will be logged to <faircom>/data/CTSTATUS.FCS explaining why the disconnect happened. For example: 
    • MQTT connection for client ID [myMqttClient7] has been disconnected due to inactivity timeout. retrySeconds is set to [25] seconds for topic [my/test/topic12].: 14226
    • When the MQTT client reconnects, FairCom's MQTT broker will attempt to resume the PUBLISH handshake by resending the unanswered packet to the client, hoping that the client will reply with the next step of the handshake.
  • If "retrySeconds" is omitted or its range is exceeded, FairCom's broker uses the default value.
  • Note that this parameter is not related to MQTT Keep Alive or when PINGREQ packets should be sent by the client.
 integer 1 to 65535

data

persistence

.storeAndForward

      

data

persistence

.tableAutoTimeStamp

      

data

persistence

.tableAutoTimeStampIndex

      

data

persistence

.tableName

The "tableName" property is a string containing the name of a table.

See table name in System specifications for the table naming requirements and limitations.

 string 1 to 64 bytes

data

persistence

.tableReplicationReady

 The "tableReplicationReady" property enables the transaction log on the persistence table. Transaction logs must be enabled before a table can be replicated. Boolean

true

false

data

persistence

.threads

The "threads" property is the number of threads assigned to a topic to write published messages to disk. 

  • The default of 1 is enough to handle typical workloads.
  • For heavy workloads, you may increase the number of threads to 2 or 3.
 integer

1

2

3

data

persistence

.topic

The "topic" property specifies the MQTT topic on the external broker to which messages will be forwarded.

 string A topic name between 1 and 65,500 bytes

data

.subscriberList

      

data

subscriberList

.connectionList

      

data

subscriberList

connectionList

.connection

      

data 

subscriberList

connectionList

connection

.clientId

      

data 

subscriberList

connectionList

connection

.connectionTime

      

data 

subscriberList

connectionList

connection

.ipaddress

 The "ipAddress" property specifies the PLC/Equipment IPV4 Address. string A valid IP address

data 

subscriberList

connectionList

connection

.keepAliveSeconds

The "keepAliveSeconds" property specifies how often (in seconds) the broker expects a message to be sent. The server will retain a temporary session as long as the client performs an MQ Message action within the keep alive timeout period, which is "keepAliveSeconds" x 1.5. Once there is no activity, the server starts the session expiry timer to remove the temporary session. If there is no session activity within the number of seconds specified in the "sessionExpiryInternal" property, the server removes the session.

 integer No limit

data 

subscriberList

connectionList

connection

.mqttProtocol

 The "mqttProtocol" property specifies the version of MQTT protocol to use in your session. string enum

"3.1.1"

"5.0"

data 

subscriberList

connectionList

connection

.port

The "port" property is an integer that specifies the port number.

 integer an integer port number

data 

subscriberList

connectionList

connection

.status

The "status" property defaults to "active". The alternative is "inactive", which indicates an item is no longer in active use. Setting an item to "status": "inactive", functions similarly to deleting an item without making the deletion permanent.

 

When the "status" property is omitted or set to null, API actions set the "status" property to "active". Thus, when you create an item, it defaults to being active. When you list items, the action defaults to returning active items.

 

To create, alter, and list inactive items, set the "status" property to "inactive".
Use a delete action to permanently delete an item.

 string enum

"active"

"inactive"

data 

subscriberList

connectionList

.qos

      

data 

subscriberList

.topicExpression

      

 

Was this article helpful?

Give feedback about this article

Related Articles