--- schema_version: "1" id: 20843785cfb61ceb1b2bf6d9a20577c9d34bead93e251b025255b4631dc3e768 title: Data Labels in the REST API collection: tableau version: next locale: en-us portal_url: https://docs.salesforce.com/tableau/next/en-us/api/rest_api/REST/rest_api_concepts_data_labels.md canonical_url: https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_concepts_data_labels.htm source_site: help.tableau.com content_type: documentation content_hash: 7103caac17778fbfd7f6c1a8f37afc52c2376608d654ef1be31a4a4f91030a70 description: Data Labels, described in the "Data Labels" topic of the Tableau Cloud and Tableau Server help, can be extensively controlled through the REST API --- [Skip to main content](#main-content) # Data Labels in the REST API Data Labels, described in the "Data Labels" topic of the [Tableau Cloud](https://help.tableau.com/current/online/en-us/dm_labels.htm) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels.htm) 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm). 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](/tableau/next/en-us/api/rest_api/en-us/Img/dm_label_properties-246.png) 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](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm), 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm#limitations-for-editing-labels) and [Tablau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm#limitations-for-editing-labels) 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: - [Get Label](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#get_label) - [Get Labels](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#get_labels_on_assets) - [Update Label](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_label) - [Update Labels](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_labels_on_assets) - [Delete Label](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_label) - [Delete Labels](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_labels_on_assets) ### 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm#name) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm#name) 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm#category) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm#category) 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm#visibility) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm#visibility) 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm) and [Tableau Server](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm) 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: - [Get labelValue](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#get_labelvalue) - [List labelValues on Site](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#list_labelvalues_on_site) - [Create or Update labelValue](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#create_or_update_labelvalue) - [Update labelValue](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_labelvalue) - [Delete labelValue](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_labelvalue) ### 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm#name) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm#name) 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. 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm#category) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm#category) product help. 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm#description) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm#description) 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: - [List Label Categories on Site](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#list_label_categories_on_site) - [Create Label Category](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#create_label_category) - [Update Label Category](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#update_label_category) - [Delete Label Category](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_metadata.htm#delete_label_category) ### 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](https://help.tableau.com/current/online/en-us/dm_labels_manage.htm#category) and [Tableau Server](https://help.tableau.com/current/server/en-us/dm_labels_manage.htm#category) 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 nameCategory
CertifiedCertification
DeprecatedData Quality Warning
Stale dataData Quality Warning
Under maintenanceData Quality Warning
WarningData Quality Warning
Extract refresh failedData Quality Warning
Flow run failedData Quality Warning
Sensitive data1Sensitivity
1_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](https://help.tableau.com/current/developer/webhooks/en-us/docs/webhooks-events-payload.html). ## The Tableau REST API Postman Collection The [Tableau REST API Postman Collection](https://github.com/tableau/tableau-postman) contains an open source collection of methods for easy learning, development, and testing.