describeTags

The "describeTags" action describes specified tags. You can specify tags by ID or name. You can also control the information returned about each tag.

You can include additional information about where a tag is used:

  • "includeInputConnectorsProperties" - lists the input connectors that use a specific tag.
  • "includeOutputConnectorsProperties" - lists the output connectors that use a specific tag.
  • "includeThingProperties" - List of devices and software that use a specific tag, including when the tag is being collected and/or delivered to the device.
  • "includeTopicProperties" - The topics that use a specific tag. 
    • Typically a tag is used by one MQTT topic, but the "jsonToDifferentTableFields" transform action can map a tag to additional tables that can be associated with additional MQTT topics.

 

Request examples

Describe by IDs

{
  "api": "hub",
  "action": "describeTags",
  "params": {

    "ids": [ 1, "2" ],

    "includeInputConnectorProperties": ["id", "connectorName", "connectorId" ], 
    "includeOutputConnectorProperties": ["id", "connectorName", "connectorId" ], 
    "includeThingProperties": [], 
    "includeTopicProperties": ["id", "topic", "tableName"]

  },
  "authToken": "replaceWithAuthTokenFromCreateSession" 
}
 
 

Describe by Names

{
  "api": "hub",
  "action": "describeTags",
  "params": {

    "tagNames": [ "My Device", "Changed Name" ],

    "includeInputConnectorProperties": ["id", "connectorName", "connectorId" ], 
    "includeOutputConnectorProperties": ["id", "connectorName", "connectorId" ], 
    "includeThingProperties": [], 
    "includeTopicProperties": ["id", "topic", "tableName"]

  },
  "authToken": "replaceWithAuthTokenFromCreateSession" 
}
 
 

 

Response examples

Minimal

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {

    "id": 1,
    "tagName": "temperatureCelsius",

    "tableName": "temperature",
    "ownerName": "admin",
    "databaseName": "faircom",

    "tagDataType": "number",

    "sourceFieldName": "temperature_celsius",
    "sourceFieldType": "integer",
    "sourceFieldLength": 4,
    "sourceFieldScale": null,

    "sourcePayloadPath": "temperature.celsius",
    "sourcePayloadBinaryFormat": "hex",
    "sourcePayloadDateFormat": "iso8601",
    "sourcePayloadTimeFormat": "iso8601",
    "sourcePayloadNumberRounding": "roundup",
    "sourcePayloadVariantFormat": "json",

    "status": "active",
    "purpose": "Store temperature in Celsius",
    "description": "My tag's description",
    "labels": ["temperature", "celsius"],
    "metadata": { "myProperty": "myValue" }, 

    "createdTimestamp": "2026-01-03T12:13:04Z",
    "updatedTimestamp": "2026-01-03T12:13:04Z"null,
    "inactiveTimestamp": null

  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Maximal

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {

    "id": 1,
    "tagName": "temperatureCelsius",

    "tableName": "temperature",
    "ownerName": "admin",
    "databaseName": "faircom",

    "tagDataType": "number",

    "sourceFieldName": "temperature_celsius",
    "sourceFieldType": "integer",
    "sourceFieldLength": 4,
    "sourceFieldScale": null,

    "sourcePayloadPath": "temperature.celsius",
    "sourcePayloadBinaryFormat": "hex",
    "sourcePayloadDateFormat": "iso8601",
    "sourcePayloadTimeFormat": "iso8601",
    "sourcePayloadNumberRounding": "roundup",
    "sourcePayloadVariantFormat": "json",

    "status": "inactive",
    "purpose": "Store temperature in Celsius",
    "description": "My tag's description",
    "labels": ["temperature", "celsius"],
    "metadata": { "myProperty": "myValue" }, 

    "createdTimestamp": "2026-01-03T12:13:04Z",
    "updatedTimestamp": "2026-02-03T17:36:57Z",
    "inactiveTimestamp": "2026-03-03T09:01:13Z",

    "inputConnectors": [
      { "connectorId": 51, "connectorName": "INPUT: PLC 74 & Modbus", "lastCollectedTimestamp": "2025-08-28T10:47:13.041" }
    ],
    "outputConnectors": [
      { "connectorId": 52, "connectorName": "OUTPUT: PLC 74 & Modbus","lastDeliveredTimestamp": "2025-08-28T10:47:13.041" },
      { "connectorId": 53, "connectorName": "OUTPUT: MES & REST",     "lastDeliveredTimestamp": "2025-08-28T10:47:13.041" }
    ],
    "things": [ 
      { "thingId": 1 }
    ],
    "topics": [ 
      { "topicId": 1, "topic": "Temperature",          "tableName": "temperature" },
      { "topicId": 1, "topic": "Temperature//Celsius", "tableName": "celsius" }
    ]
  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

ids

The "ids" property specifies 0 or more ids. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. It is required if the "primaryKeys" property is "null" or not specified.

  • The "ids" property is mutually exclusive with the "primaryKeys" property meaning it is required when "primaryKeys" is omitted or an error is returned if both have values.
  • It is typically an array of integers ("ids": [1,3,5]).
  • It can be an array of an array of strings ("ids": ["9555444333222111","9555444333222112", "9555444333222113"]).
    • A string "id" supports numbers larger than 9,007,199,254,740,991.
    • This is the largest number supported by many programming languages and JSON parser implementations that use IEEE double-precision floats to hold numbers.
  • It can be the primary key value of another field in the table making it useful when your table is created by another API, such as SQL, that allows any field in the table to be the primary key.
    • If your table does not have an "id" field but uses a "vin" field as the primary key, you can use vin values to look up records ("ids": [ "4Y1SL65848Z411439", "1HGBH41JXMN109186" ]).
  • If your table uses more than one field as the primary key, you must use the "primaryKeys" property to look up records.

Tip The "getRecordsByIds" action uses a primary key index to look up records. A primary key index must be a unique, non-null index without conditional filtering. For best performance and maximum simplicity, create tables using the JSON DB API because it automatically creates an auto increment "id" field that is indexed as a primary key.

Optional with default of "null".

Required when "primaryKeys" is omitted

 array 0 or more ids

includeInputConnectorProperties

The "includeInputConnectorProperties" property specifies names of connector properties. When it is included in the request, the response includes an "inputConnectors" list that contains all the connectors related to the request. Each item in the list is an object that contains the specified properties.

 

For more details, see "includeInputConnectorProperties".

 Optional with default of [] array of strings

"connectorName"

"connectorId"

"settings"

"serviceName"

"metadata"

includeOutputConnectorProperties

The "includeOutputConnectorProperties" property causes the response to include an "outputConnectors" list that contains all the connectors related to the request. Each item in the list is an object that contains the specified properties.

 

For more details, see "includeOutputConnectorProperties".

 Optional with default of [] array of strings

"connectorName"

"connectorId"

"settings"

"serviceName"

"metadata"

includeThingProperties

 The "includeThingProperties" property causes the response to include a "things" list that contains all the devices and software related to the request. Each string is the name of a device property. For more details, see "includeThingProperties". Optional with default of [] array of strings

"id"

"thingName"

"status"

"manufacturer"

"model"

"serialNumber"

"type"

"purpose"

"description"

"location"

"labels"

"hostnames"

"metadata"

"photo"

includeTopicProperties

 The "includeTopicProperties" property causes the response to include a "topics" list that contains all the MQTT topics related to the request. Each string is the name of a topic property. For more info, see “includeTopicProperties”.  Optional with default of [] array of strings zero or more of the properties in the results example of the describeTopics action

tagNames

The "tagNames" property specifies one or more tag names. You can use it to describe or delete tags. 

  • Each item in the array is the exact name of a tag. 
 Required - No default value string 1 to 256 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

createdTimestamp

 The "createdTimestamp" property is the date and time when something, such as a thing or key, was originally created in ISO 8601 format, such as "2025-08-28T10:47:13.041". It is never null. timestamp An ISO 8601 timestamp

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

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

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 

inactiveTimestamp

 The "inactiveTimestamp" property is the date and time when the thing was last made inactive. It is null when the thing is active. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

inputConnectors

The "inputConnectors" property occurs in the response to Tag API actions when the "includeInputConnectorProperties" property is in the request. It contains all input connectors related to a tag. Each object contains the requested connector properties. See "includeInputConnectorProperties" for examples and additional information.

 

Note Input and output connectors are included separately because they have different properties.

 array of objects

zero or more objects containing zero or more of the following properties: 

"connectorName"

"connectorId"

"lastCollectedTimestamp"

labels

The "labels" property can assign 1 or more labels to the same record. Each label may belong to any group. Each specified label must have already been created using the "createLabel" action so that it exists in the label table.

The "labels" property must contain at least one label object. Each label object specifies the label's group name and label name. 

  • The "name" property must be set to a string value. If it is omitted or set to null, the action returns an error. 
  • The "group" property is optional. If it is omitted or set to null, the action sets it to the empty string "". 

When using tag actions, the optional "labels" property assigns zero or more labels to a tag. You can use it to do lookups and filtering. You can display a list of existing stages, add new ones, rename them, and deprecate them.

 

When you use the "alterThing" action, omit the "labels" property to leave existing labels unchanged or specify the complete set of labels. The action does not allow you to change one label at a time.

 

You can use the "labelsFilter" property to lookup and filter things.

 

The Tag API implements the "labels" property using the Label API. 

  • The API stores and manages labels in the label group, "faircom/labels".
  • An API client can retrieve a list of all labels by using the "listLabels" action with "partialGroupFilter": "faircom/labels".
  • An API client should use the Thing API's "labels" property to manage the labels  assigned to a thing. It should not use the Label API to rename, link, or unlink host names to things.
 array of objects

1 or more label objects

 

Values are managed in the Label API with the group of "faircom/edge/label".

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. object 0 or more key/value pairs

onSyncConflict

 The "onSyncConflict" property specifies what happens when the automatic synchronization between a tag's property and field cannot be synchronized because both have different values. string enum "overwriteField"
"overwriteFieldWithoutError"
"overwriteProperty"
"overwritePropertyWithoutError"
"retainValues"
"retainValuesWithoutError"
 

outputConnectors

The "outputConnectors" property occurs in the response to Tag API actions when the "includeOutputConnectorProperties" property is in the request. It is an array of objects that contains all output connectors related to a tag. Each object contains the requested connector properties. See "includeOutputConnectorProperties" for examples and additional information.

 

Note Input and output connectors are included separately because they have different properties.

 array of objects

Zero or more objects containing zero or more of the following properties:

"connectorId"

"connectorName"

"lastDeliveredTimestamp"

ownerName

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

purpose

The "purpose" property provides a short description of the specified server's purpose.

 

In the Thing API, the "purpose" property specifies the thing's purpose, which is a short description of why a thing is in use. A thing may have one purpose. 

 

This API uses the Label API to manage purposes.

  • It uses the label group, "faircom/edge/purpose". 
  • An API client can use the "listLabels" action to retrieve the purpose list. 
  • An API client can use the "alterLabel" action to rename a purpose label.
  • An API client can use the "createLabel" action to create a purpose label.
  • An API client can use the "changeLabel" action to delete a purpose label, but the API client must first use the "listThings" action with the "purposeFilter" property to ensure the label is unused.
 string 1 to 64 bytes

sourceFieldLength

 The "sourceFieldLength" property links a tag to a field in the tag's integration table. string 1 to 64 bytes

sourceFieldName

The "sourceFieldName" property links a tag to a field in the tag's integration table. It is the tag's primary field. Transformations can associate a tag with additional fields.

  • It must be the name of an existing field in an integration table. 
  • It is a case-sensitive string from 1 to 64 bytes in length. 
  • It is an optional request property in the "createTag" and "alterTag" actions.
  • When a primary field is assigned to a tag, the field's information is returned in the responses to the "createTag", "alterTag", "deleteTag" and "describeTag" actions.

Note: Before using the "sourceFieldName" property with the "createTag" and "alterTag" actions to link a tag to a field, that field must already be defined in the integration table. The integration table defines each field's type, length, and scale. For convenience, tag action responses include this information when a tag is linked to a field.

 string 1 to 64 bytes

sourceFieldScale

 The "sourceFieldScale" property contains the scale of the tag's field in the integration table. integer "money": 2 digits to the right of the decimal point allows 30 digits to the left.
"money": 4 digits to the right of the decimal point allows 28 digits to the left.
"number": 0 to 32 digits. It must be less than or equal to "sourceFieldLength" which defaults to 32.

sourceFieldType

 The "sourceFieldType" property specifies the number of bytes of the tag's field in the integration table. integer "json", "varchar", and "varbinary": 1 to 65500 (Specifies the variable-length field's maximum number of bytes.)
"char" and "binary": 1 to 65500 (Specifies the fixed-length field's length in bytes.)
"number" and "money": 1 to 32 (Optionally specifies the field's maximum total number of numeric digits.)

sourcePayloadBinaryFormat

The "sourcePayloadBinaryFormat" property specifies the "binaryFormat" of data embedded in a string property in the source_payload field.

 

 string

"hex"
"base64"
"byteArray"

 

sourcePayloadDateFormat

 The "sourcePayloadDateFormat" property specifies the "dateFormat" of data embedded in a string property in the source_payload field. string

"ccyy.mm.dd"
"mm.dd.ccyy"
"mm.dd.yy"
"dd.mm.ccyy"
"dd.mm.yy"
"ccyymmdd"
"iso8601"
"yymmdd"
"utc"

 

sourcePayloadNumberRounding

 The "sourcePayloadNumberRounding" property specifies the rounding option to use when reducing the scale of a number property in the source_payload field. string

"truncate"
"roundup"
"rounddown"

 

sourcePayloadPath

The "sourcePayloadPath" property is the propertyPath of the tag's value in the source_payload field, such as "sourcePayloadPath": "temperature".

  • It must not be an empty string and it may contain up to 2048 bytes.
  • It is the primary location of a tag's value.
    • Transforms may make additional copies of the value and store them in other locations in the source_payload field, other JSON fields, user-defined fields, and fields in other tables.
    • It does not have to be the first location of the value as identified in a tag's provenance.


For example, setting "sourcePayloadPath" to "temperature" causes the server to take a value it collects, such as 20.1, and assign it to the "temperature" property in the source_payload field, such as { "temperature": 20.1 }. 

 string 1 to 2048 bytes

sourcePayloadTimeFormat

 The "sourcePayloadTimeFormat" property specifies how the server encodes and decodes a time value assigned to a tag. For more details, see "sourcePayloadTimeFormat". string enum "hh.mm.ss.ttt"
"hh.mm.am/pm"
"hh.mm.ss.am/pm"
"hh.mm.ss"
"hh.mm"
"hhmm"
"iso8601"
"utc"

sourcePayloadVariantFormat

The "sourcePayloadVariantFormat" property indicates how a variant value is encoded in the "sourcePayloadPath". 

  • It applies to the tag's value only when the "tagDataType" property is "variant".
  • The default value is "json".
  • It can be set to one of the following:
    • "json"
    • "variantObject"
    • "binary"
    • "string"


Examples

  • "sourcePayloadVariantFormat":"json" encodes the tag's value in the source_payload field as JSON. If the variant field value is binary, it is encoded in a string and the "sourcePayloadBinaryFormat" property specifies the binary encoding.
  • "sourcePayloadVariantFormat":"variantObject" encodes the tag's value in the source_payload field as a variant object.
  • "sourcePayloadVariantFormat":"binary" encodes the tag's value in the source_payload field as binary. The "sourcePayloadBinaryFormat" property specifies the binary encoding.
  • "sourcePayloadVariantFormat":"string" encodes the tag's value in the source_payload field as a string. If the variant field value is binary, it is encoded in a string and the "sourcePayloadBinaryFormat" property specifies the binary encoding.


For more details, see "variantFormat".

 string enum "json"
"variantObject"
"binary"
"string"

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"

tableName

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

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

 string 1 to 64 bytes

tagDataType

The "tagDataType" property specifies the data type of the tag.  

  • It defines the data type of the tag's value. 
  • It defines how the server interprets the tag's value, which is located in the source_payload field and its primary table field.
 string enum "string"
"number" 
"boolean" 
"date" 
"time" 
"timestamp" 
"json" 
"variant" 
"binary" 

tagName

The "tagName" property is a string that specifies the unique name of a tag. See also "tagId".

  • In "createInput" and "createOutput", you can use the "tagId" or "tagName" properties to associate the connector with a tag. 
  • In "alterInput" and "alterOutput", you can use the "tagId" or "tagName" properties to change the connector's association with a tag.
  • When assigning a tag to a connector, you can use either the "tagId" or "tagName" property but not both.
  • If a tag is associated with a connector, the response to the input and output actions include both the "tagId" or "tagName" properties; otherwise, these properties are omitted in the response. 

Important The "propertyPath" property is deprecated for the "createInput", "createOutput", "alterInput", and "alterOutput" actions. Instead, use the "tagName" or "tagId" properties.

 string 1 to 256 bytes

things

 The "things" property occurs in the response to Tag API actions when the "includeThingProperties" property is in the request. It is an array of objects that contains all devices and software related to a tag. Each object contains the requested device properties. See "includeThingProperties" for examples and additional information. array of objects All devices and software related to a tag.

topics

 The "topics" property occurs in the response to Tag API actions when the "includeTopicProperties" property is in the request. It is an array of objects that contains all topics related to a tag. Each object contains the requested topic properties. See "includeTopicProperties" for examples and additional information. array of objects All topics related to a tag.

updatedTimestamp

 The "updatedTimestamp" property is the date and time when the thing was last updated. It is the same as the "createdTimestamp" property when the thing has never been updated. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

Was this article helpful?

Give feedback about this article

Related Articles