Data Labels in the REST API

Data Labels, described in the "Data Labels" topic of the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window) help, can be extensively controlled through the REST API.

Using the labels methods, non-administrators with permissions can list, add, remove, or update data labels on assets.
Using the labelValues methods, administrators can list, create, delete, or update data label values that are available to the users. In other words, administrators can define the labels that are available to non-administrators for associating with assets.
Using the labelCategories methods, administrators can list, create, delete, or update data label categories that are available to the users. In other words, administrators can define the data label categories that are used to group data labels into distinct types.

Note: The REST API continues to support older methods to add and remove certifications and data quality warnings (the dataQualityCertifications and dataQualityWarnings endpoints). These methods were developed before the broader data labels concept existed, and are not included in this topic.

All label operations except those related to the certification of data sources require Tableau Catalog to be enabled. Tableau Catalog requires a Data Management license.

Data label terms in the REST API

The data label object model is more complex than it's presented in the "Manage Data Labels" topic of the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window). A label on an asset has a number of properties, one of which – value – has its own properties. The most notable label value properties are name, category, and description, because they appear to users in dialogs and other parts of the Tableau interface.

Data label object and properties diagram

Manipulating and managing data labels through the REST API requires knowledge of the relevant objects and properties. In general, capabilities and limitations imposed on the objects or their properties are covered in the REST API Reference(Link opens in a new window), in the methods themselves. Some common editing limitations are in the "Limitations for editing labels" section of the Manage Data Labels topic in the Tableau Cloud(Link opens in a new window) and Tablau Server(Link opens in a new window) product help.

Label

A label is attached to an asset. Using the labels methods, non-administrators with permissions can list, add, remove, or update data labels on assets.

The labels methods (introduced with Tableau Cloud June 2022 / Server 2022.3) are:

Important label properties

value
The value of a label is, for most purposes, its name. Valid values are the list of labelValue names. For information about its appearance in Tableau, see the "Name" section of the Manage Data Labels page in the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window) product help.

category
Valid categories are the list of labelCategory names. For information about its appearance in Tableau, see the "Category" section of the Manage Data Labels page in the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window) product help.

active
Boolean. The active property corresponds to the on/off toggle switch available in the various label dialogs. It turns the data label on or off without disturbing its other properties.

elevated
Boolean. The elevated property corresponds to the visibility level of a data label, and may result in the label and asset being more visible or appearing more urgent. A label with elevated set to true is a high visibility label. For more information, see the "Visibility" section of the Manage Data Labels page in the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window) product help.

Note: When users are working in the regular web interface, only labels with a WARNING or SENSITIVITY category have an adjustable visibility level. The REST API allows users to change the elevated property (the visibility level) of labels in other categories, but doing so doesn't affect the appearance of those labels in the regular web interface.

message
The label message. Each instance of a label has its own message.

contentType
The type of asset the label is on. Valid types are:

database
table
column (Can be labeled starting in Tableau API 3.16 / Cloud October 2022 / Server 2022.3)
datasource
flow
virtualconnection
virtualconnectiontable

owner
The user who created or last updated the data label.

Label value (labelValue)

A label has a number of properties, one of which is value, which is itself a collection of other properties. The most notable of these properties are name, category, and description, because they appear to the user in dialogs and other parts of the Tableau interface. Using the labelValues methods, administrators can list, create, delete, or update data labels that are available to the users.

What the Manage Data Labels topic of the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window) help calls a label name is referred to in the REST API as a labelValue name. Similarly, a label category is a labelValue category and a description is a labelValue description.

Note: In the context of the common name for a label, the terms label, label name, label value, and label value name are often used interchangeably.

The labelValues methods (introduced with Tableau Cloud June 2023 / Server 2023.3.) are:

Important labelValue properties

name
The name of a labelValue is, for most purposes, synonymous with the terms label, label value, and label name. The built-in label values have the following names:

certified
warning
deprecated
stale
maintenance
extract_refresh_failure
flow_run_failure
sensitive_data

For information about its appearance in Tableau, see the "Name" section of the Manage Data Labels page in the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window) product help.

Two of the label values – extract_refresh_failure and flow_run_failure – correspond to monitoring quality warnings. Tableau adds and removes these labels automatically based on trigger events, so they have the internal property set to true. Using the REST API, you can see these labels on assets, but can't modify them.

description
A description that tells users what the label value is used for. For information about its appearance in Tableau, see the "Description" section of the Manage Data Labels page in the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window) product help.

internal
Boolean. An internal label is one that's automatically added or removed by the system in response to a trigger. Extract refresh and flow run monitoring warnings are examples of internal label values.

elevatedDefault
Boolean. If elevatedDefault is true, then when a label with this label value is added to an asset, elevated is automatically set to true (meaning the visibility level is set to high visibility).

builtIn
Boolean. Built-in label values are the ones that ship with Tableau. (See labelValue name for the built-in label value names.)

Note: An administrator can change the label value names for some built-in label values. If they have, the label value names will be different, but the builtIn property will be true.

Label Category (labelCategory)

One of the properties of a label value is category (or labelValue category). Using the labelCategories methods, administrators can list, create, delete, or update data label categories that are available to the users.

The labelCategories methods (introduced with Tableau Cloud October 2023 / Server 2023.3) are:

Important labelCategory properties

name
The name of the category. The built-in label categories are:

certification
warning
sensitivity

For information about its appearance in Tableau, see the "Category" section of the Manage Data Labels page in the Tableau Cloud(Link opens in a new window) and Tableau Server(Link opens in a new window) product help.

description
A description that tells users what the category is used for. Users may see this when interacting with elements related to label categories.

Built-in names and categories

The label value names and categories built-into Tableau are:

Label value name	Category
Certified	Certification
Deprecated	Data Quality Warning
Stale data	Data Quality Warning
Under maintenance	Data Quality Warning
Warning	Data Quality Warning
Extract refresh failed	Data Quality Warning
Flow run failed	Data Quality Warning
Sensitive data¹	Sensitivity

¹In Tableau Cloud March 2023 / Server 2023.1 and earlier, the Sensitive data label uses the Data Quality Warning category.

Webhooks

You can create webhooks that trigger when a data label is attached to an asset, updated, or deleted. For information, see the LabelCreated, LabelUpdated, and LabelDeleted events in Webhook Events and Payloads(Link opens in a new window).

The Tableau REST API Postman Collection

The Tableau REST API Postman Collection(Link opens in a new window) contains an open source collection of methods for easy learning, development, and testing.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help