Tableau REST API Help

Add Database Permissions

Add permissions to a database asset.

To add permissions, the database asset must be associated with a published data source.

URI

PUT api/api-version/sites/site-luid/databases/database-luid/permissions

Parameter Values

Request Body

<tsRequest>
  <permissions>
    <database id="8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" />
    <granteeCapabilities>
      <user id="user-luid" />
      <capabilities>
        <capability name="ChangePermissions" mode="allow" />
        <!-- ...  additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-luid" />
 	  <capabilities>
	    <capability name="Read" mode="Allow" />
	    <!-- ...  additional capabilities ... -->
	  </capabilities>
	</granteeCapabilities>
    <!-- ... additional grantee capability sets ...  -->
  </permissions>
</tsRequest>

{
  "permissions": {
    "database": {
      "id": "1d4aa9f-3d1a-4b49-8d6d-27f113cbd25e"
    },
    "granteeCapabilities": [
      {
        "user": {
          "@id": "2d4aa9f-3d1a-4b49-8d6d-27f113cbd25e"
        },
        "capabilities": {
          "capability": {
            "name": "ChangePermissions",
            "mode": "allow"
          }
        }
      },
      {
        "group": {
          "id": "3d4aa9f-3d1a-4b49-8d6d-27f113cbd25e"
        },
        "capabilities": {
          "capability": {
            "name": "Read",
            "mode": "Allow"
          }
        }
      }
    ]
  }
}

Request Attributes

Response Code

200

Response Body

<tsResponse>
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.tsi.lan:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

{
  "permissions": {
    "database": {
      "id": "e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e",
      "name": "oracle.test.tsi.lan:1521"
    },
    "granteeCapabilities": {
      "user": {
        " id": "6265b714-7533-465d-b6db-6d0be92bfd07"
      },
      "capabilities": {
        "capability": {
          "name": "Read",
          "mode": "Allow"
        }
      }
    }
  }
}

Errors

Add Default Database Permissions

Adds default permission capabilities to a user or group for table resources in that database.

Default permissions function as a permissions template for the database's table assets.

Note: If a database is in a project, default database permissions are not evaluated to determine table permissions. Use the Add Default Permissions method to control default permission capabilities on tables through projects instead.

How default permissions are enforced depends on whether the database is locked or unlocked.

• Locked to the database: If the permissions on a database are locked or Locked to the database, existing child table assets and new child table assets that get indexed by Catalog will inherit the default permissions applied to the parent database asset. Note: If the database is locked, explicit permissions cannot be made for individual tables.

• Managed by the owner: If the permissions on a database are unlocked or Managed by the owner, only new child table assets that get indexed by Catalog will inherit the default permissions applied to the parent database asset. Note: If the database is unlocked, explicit permissions for the table can be made in a separate request.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT /api/api-version/sites/site-luid/databases/database-luid/default-permissions/tables

Parameter Values

Request Body

<tsRequest>
  <permissions>
    <granteeCapabilities>
      <user id="user-luid" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!-- ... additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-luid" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!-- ...  additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <!-- ... additional grantee capability sets ... -->
  </permissions>
</tsRequest>

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users set default permissions for the database asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

<tsResponse>
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.tsi.lan:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Add Data Quality Warning

Add a data quality warning to a database, table, column, published data source, flow, virtual connection, or virtual connection table.

The Add Data Quality Warning method adds a data quality warning to an asset. (An automatically-generated monitoring warning does not count towards this limit.) In Tableau Cloud February 2024 and Tableau Server 2024.2 and earlier, adding a data quality warning to an asset that already has one causes an error.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

Request Body

<tsRequest>
  <dataQualityWarning type="type" isActive="state" message="message" isSevere="severity"/>
</tsRequest>

Attribute Values

Any combination of attributes inside the <dataQualityWarning> element is valid, but the data quality warning type is required. If the data quality warning type is not included, an error is thrown.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add the data quality warning:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

201

Response Body

Example response:

<tsResponse>
   <dataQualityWarning id="1c8ebdfc-270a-4414-812c-3306a1c95e07" userDisplayName="Steve Nguyen"
	contentId="0d7465f2-4989-417e-b88d-f787359edc63" contentType="DATABASE" message="Delayed"
	type="WARNING" isActive="true" createdAt="2020-10-08T00:00:35Z" isSevere="false">
	<site id="a946d998-2ead-4894-bb50-1054a91dcab3"/>
	<owner id="cdfe8548-84c8-418e-9b33-2c0728b1234a"/>
   </dataQualityWarning>
</tsResponse>     

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Batch Add or Update Data Quality Warnings

Add or update multiple data quality warnings on assets.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-id/dataQualityWarnings/createOrUpdate

Parameter Values

Request Body

<tsRequest>
  <contentList>
	<content contentType="content" id="database-id" />
	<content contentType="content" id="table-id" />
	<content contentType="content" id="column-id" />
	<content contentType="content" id="datasource-id" />
	<content contentType="content" id="flow-id" />
	<content contentType="content" id="virtualconnection-id" />
	<content contentType="content" id="virtualconnectiontable-id" />
  </contentList>
  <dataQualityWarning type="type" message="message" isActive="state" isSevere="severity" />
</tsRequest>
      

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to batch add or update data quality warnings:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsRequest>
  <dataQualityWarningList>
	<dataQualityWarning id="8f58aa47-7313-4504-8537-52d869552e18" userDisplayName="Mark Nguyen" contentId="7cfd2ac8-a934-4aa8-bf24-96bff08a019c" contentType="DATABASE" message="Contact admin with questions" type="WARNING" isActive="true" createdAt="2021-06-26T21:34:46Z" updatedAt="2021-06-26T21:34:46Z" isSevere="true">
	  <site id="1e4b3aa0-b48a-4b8e-9bdf-74b7596b9f0a" />
	  <owner id="adcc51d7-8558-4099-9f87-dc1a1615d297" />
	</dataQualityWarning>
	<dataQualityWarning id="c8f0b332-a1c1-48f1-b650-86f342ab937f" userDisplayName="Mark Nguyen" contentId="f6dcfd24-7c65-40f4-a3f3-c29f91b7731e" contentType="DATASOURCE" message="Contact admin with questions" type="WARNING" isActive="true" createdAt="2021-06-26T21:34:46Z" updatedAt="2021-06-26T21:34:46Z" isSevere="true">
	  <site id="1e4b3aa0-b48a-4b8e-9bdf-74b7596b9f0a" />
	  <owner id="adcc51d7-8558-4099-9f87-dc1a1615d297" />
	<dataQualityWarning>
  </dataQualityWarningList>
</tsRequest>     

Version

Version 3.12 and later. For more information, see REST API and Resource Versions.

Errors

Batch Add or Update Data Quality Certifications

Create or update one or more data quality certifications for different content and asset items.

A content or asset item can only have up to one data quality certification applied to it. Adding a data quality certification to an item that already has one will update the data quality certification with the latest specified values.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-id/dataQualityCertifications

Parameter Values

Request Body

<tsRequest>
  <contentList>
	<content contentType="content" id="database-id" />
	<content contentType="content" id="table-id" />
	<content contentType="content" id="datasource-id" />
	<content contentType="content" id="virtualconnection-id" />
	<content contentType="content" id="virtualconnectiontable-id" />
  </contentList>
  <dataQualityIndicator type="type" message="message"
	active="state" elevated="severity" />
</tsRequest> 

Attribute Values

Any combination of attributes inside the <dataQualityIndicator> element is valid, however type and message attributes are required.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add or update data quality certifications:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

201

Response Body

Example response

<tsRequest>
  <dataQualityIndicatorList>
	<dataQualityIndicator id="8f58aa47-7313-4504-8537-52d869552e18"
	    userDisplayName="Mark Nguyen" contentId="7cfd2ac8-a934-4aa8-bf24-96bff08a019c" contentType="DATABASE" message="Marketing approved" type="CERTIFIED" active="true" createdAt="2021-09-26T21:34:46Z" updatedAt="2021-09-26T21:34:46Z" elevated="true">
	  <site id="1e4b3aa0-b48a-4b8e-9bdf-74b7596b9f0a" />
	  <owner id="adcc51d7-8558-4099-9f87-dc1a1615d297" />
	</dataQualityIndicator>
	<dataQualityIndicator id="c8f0b332-a1c1-48f1-b650-86f342ab937f"
	    userDisplayName="Mark Nguyen" contentId="f6dcfd24-7c65-40f4-a3f3-c29f91b7731e" contentType="DATASOURCE" message="Marketing approved" type="CERTIFIED" active="true" createdAt="2021-09-26T21:34:46Z" updatedAt="2021-09-26T21:34:46Z" elevated="true">
	  <site id="1e4b3aa0-b48a-4b8e-9bdf-74b7596b9f0a" />
	  <owner id="adcc51d7-8558-4099-9f87-dc1a1615d297" />
	<dataQualityIndicator>
  </dataQualityIndicatorList>
</tsRequest>    

Version

Version 3.13 and later. For more information, see REST API and Resource Versions.

Errors

Add or Update Monitoring Quality Warning on Content

Create or update one or more monitoring quality warnings.

You can monitor for extract refresh failures on extract data sources or flow run failures on flows. An asset can only have one instance of monitoring. Adding monitoring to an asset that already has it will update it to use the latest specified values.

Note: An asset can have one monitoring warning in addition to other data quality warnings.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

Add or update a monitoring quality warning for an asset

POST api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid]

Add or update a monitoring quality warning for multiple assets

POST api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid1,content-luid2,content-luid3,...]

Note: The square brackets are required around the single LUID or comma-separated list of LUIDs.

Parameter Values

Request Body

<tsRequest>
  <dataQualityTrigger type="type" active="status" message="message" severe="severity"/>
</tsRequest>
      

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add a monitoring quality warning:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <dataQualityTriggerList>
	<dataQualityTrigger id="{trigger-luid}" siteId="{site-luid}"
		userId="{user-luid}" userDisplayName="Joe Nguyen" contentId="{content-luid}"
		contentType="DATASOURCE" message=" This message is specified by the user."
		type="EXTRACT_REFRESH" active="true" createdAt="Wed Sep 22 05:49:52 UTC 2020"
		updatedAt="Wed Sep 22 05:49:52 UTC 2020" severe="false"/>
  </dataQualityTriggerList>
</tsResponse>
      

Version

Version 3.11 and later. For more information, see REST API and Resource Versions.

Errors

Add Table Permissions

Add permissions to a table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-luid/tables/table-luid/permissions

Parameter Values

Request Body

<tsRequest>
  <permissions>
    <table id="table-luid" />
    <granteeCapabilities>
      <user id="user-luid" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!-- ... additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-luid" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!-- ... additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <!-- ... additional grantee capability sets ... -->
  </permissions>
</tsRequest>
    

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add table asset permissions:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse>
  <permissions>
	<table id="d0fe66ae-1407-4338-8520-9489d7ce959c" name="_WarehouseConfig"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Add Tags to Column

Add one or more tags to a column.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

PUT api/api-version/sites/site-id/columns/column-id/tags

Parameter Values

Request Body

<tsRequest>
  <tags>
	<tag label="tag-value1" />
	<tag label="tag-value2" />
  </tags>
</tsRequest>
      

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add tags:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <tags>
	<tag label="Noteworthy" />
	<tag label="PII" />
  </tags>
</tsResponse>
      

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

Add Tags to Database

Add one or more tags to a database.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

PUT api/api-version/sites/site-id/databases/database-id/tags

Parameter Values

Request Body

<tsRequest>
  <tags>
	<tag label="tag-value1" />
	<tag label="tag-value2" />
  </tags>
</tsRequest>
      

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add tags:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <tags>
	<tag label="Noteworthy" />
	<tag label="PII" />
  </tags>
</tsResponse>
      

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

Add Tags to Table

Add one or more tags to a table.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

PUT api/api-version/sites/site-id/tables/table-id/tags

Parameter Values

Request Body

<tsRequest>
  <tags>
	<tag label="tag-value1" />
	<tag label="tag-value2" />
  </tags>
</tsRequest>
      

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add tags:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <tags>
	<tag label="Noteworthy" />
	<tag label="PII" />
  </tags>
</tsResponse>
      

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

Batch Add Tags

Add multiple tags to items that are different content and asset types.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

PUT api/api-version/sites/site-id/tags:batchCreate

Parameter Values

Request Body

<tsRequest>
  <tagBatch>
	<tags>
	   <tag label="tag-value1"></tag>
	   <tag label="tag-value2"></tag>
	</tags>
	<contents>
	   <content id="database-id"></content>
	   <content id="table-id"></content>
	   <content id="column-id"></content>
	   <content id="datasource-id"></content>
	   <content id="workbook-id"></content>
	   <content id="flow-id"></content>
	</contents>
  </tagBatch>
</tsRequest>
      

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add tags:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsRequest>
  <tagBatch>
	<tags>
	   <tag label="PII"></tag>
	   <tag label="Noteworthy"></tag>
	</tags>
	<contents>
	   <content id="21cade8c-d4eb-4fef-bd4a-bdb9d8b09b7d" contentType="Database"></content>
	   <content id="a0314be1-afd4-4a4f-ab85-d75dac661c41" contentType="Table"></content>
	   <content id="8fec4046-e054-476d-a6d0-e808b0d5448b" contentType="Column"></content>
	   <content id="c8c3a0be-3ac8-4de7-8bd6-f912900a1ccd" contentType="Datasource"></content>
	   <content id="ec2b7845-d627-430e-b99c-8543ed50b25c" contentType="Workbook"></content>
	   <content id="c4a560eb-c8a6-48c6-86f4-c9d5e518d027" contentType="Flow"></content>
	</contents>
  </tagBatch>
</tsRequest>
      

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

Add Tags to Virtual Connection

Adds tags to a virtual connection.

<tsRequest>
  <tags>
    <tag label="tag" />
    <!-- ...additional tag elements... -->
  </tags>
</tsRequest>

<tsRequest>
  <tags>
    <tag label="Office" />
    <!-- ...additional tag elements... -->
  </tags>
</tsRequest>

<tsResponse>
  <tags>
    <tag label="tag"/>
    <!-- ...additional tags... -->
  </tags>
</tsResponse>

Create Label Category

Creates a data label category.

Note that category is one property of a label value (labelValue), which is itself a property of a label on an asset. Other properties of a labelValue include name and description. These properties determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

A Data Management license is not required to create, update, or delete label categories, but one is required to create, update, delete, and see labels on assets.

URI

POST api/api-version/sites/site-luid/labelCategories

Parameter Values

Request Body

<tsRequest>
  <labelCategory name="label-category-name"
    description="label-category-description" />
</tsRequest>

Attribute Values

Permissions

• Only a site or server administrator can create, update, or delete label categories.

Response Code

200

Version

Introduced in Tableau Cloud October 2023 (API 3.21) / Server 2023.3 (API 3.21).

Response Body

<tsResponse>
  <labelCategory name="label-category-name"
    description="label-category-description"/>
</tsResponse>

Errors

Create or Update labelValue

Creates a label value with the specified name if it doesn't exist, or updates the existing label value if the label value name already exists.

Note: You can update an existing label value using either this method or the Update labelValue method. If you want to change the name on an existing label value, use the Update labelValue method.

Note that a label value (labelValue) is one property of a label. A label value has its own properties like name, category, and description that determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

A Data Management license is not required to create, update, or delete label values, but one is required to create, update, delete, and see labels on assets.

URI

PUT api/api-version/sites/site-luid/labelValues

Parameter Values

Request Body

<tsRequest>
   <labelValue name="label-value-name"
     category="label-value-category"
     description="label-value-description" />
</tsRequest>

Attribute Values

Permissions

• Only a site or server administrator can create, update, or delete label values.

Response Code

200

Version

Introduced in Tableau Cloud June 2023 (API 3.20) and Tableau Server 2023.3 (API 3.21).

Response Body

<tsResponse>
  <labelValue name="label-value-name"
    category="label-value-category"
    description="label-value-description"
    internal="true-or-false"
    elevatedDefault="true-or-false"
    builtIn="true-or-false">
    <site id="site-luid"/>
  </labelValue>
</tsResponse>

Errors

Delete Database Permissions

Permanently remove the permissions applied to a database asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-luid/databases/database-luid/permissions/users/user-luid/capability-name/capability-mode

DELETE api/api-version/sites/site-luid/databases/database-luid/permissions/groups/group-luid/capability-name/capability-mode

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users have permissions to delete the permissions on the database asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Delete Default Database Permissions

Permanently remove the default permissions on a database asset.

Removing the default permissions from the database asset means that any new child table assets that are indexed by Catalog won't have any default permissions set.

Note: If a database is in a project, default database permissions are not evaluated to determine table permissions. Use the Delete Default Permissions method to control default permission capabilities on tables through projects instead.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-luid/databases/database-luid/default-permissions/tables/users/user-luid/capability-name/capability-mode

DELETE api/api-version/sites/site-luid/databases/database-luid/default-permissions/tables/groups/group-luid/capability-name/capability-mode

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users have permissions to delete the permissions on the database asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Delete Data Quality Warning by ID

Delete a data quality warning from an asset using the data quality warning ID.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete the data quality warning:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Delete Data Quality Warning by Content

Delete the data quality warnings from an asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete the data quality warning:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Batch Delete Data Quality Warnings

Delete multiple data quality warnings from assets.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityWarnings/batchDelete

Parameter Values

Request Body

<tsRequest>
  <contentList>
	<content contentType="content" id="database-id" />
	<content contentType="content" id="table-id" />
	<content contentType="content" id="column-id" />
	<content contentType="content" id="datasource-id" />
	<content contentType="content" id="flow-id" />
	<content contentType="content" id="virtualconnection-id" />
	<content contentType="content" id="virtualconnectiontable-id" />
  </contentList>
</tsRequest>
      

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete data quality warnings:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.12 and later. For more information, see REST API and Resource Versions.

Errors

Delete Data Quality Certification by ID

Delete a data quality certification from an asset using the data quality certification ID.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityCertifications/certification-luid

Parameter Values

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete a data quality certification:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Version

Version 3.13 and later. For more information, see REST API and Resource Versions.

Errors

Delete Data Quality Certifications by Content

Delete multiple data quality certifications from assets.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityCertifications

Parameter Values

Request body

<tsRequest>
  <contentList>
	<content contentType="content" id="database-id" />
	<content contentType="content" id="table-id" />
	<content contentType="content" id="datasource-id" />
	<content contentType="content" id="virtualconnection-id" />
	<content contentType="content" id="virtualconnectiontable-id" />
  </contentList>
</tsRequest>

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete data quality certifications:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Version

Version 3.13 and later. For more information, see REST API and Resource Versions.

Errors

Delete Quality Warning Trigger by ID

Permanently remove a quality warning trigger using the quality warning trigger ID.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityTriggers/trigger-id

Parameter Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete a quality warning trigger:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

None

Version

Version 3.11 and later. For more information, see REST API and Resource Versions.

Errors

Delete Quality Warning Triggers by Content

Permanently remove all quality warning triggers for one or more data sources or flows, or both.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

Delete one quality warning trigger

DELETE api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid]

Delete multiple quality warning triggers

DELETE api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid1,content-luid2,content-luid3,...]

Parameter Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete quality warning triggers:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

None

Version

Version 3.10 and later. For more information, see REST API and Resource Versions.

Errors

Delete Label

Deletes a data label by its LUID.

You can't delete extract refresh or flow run monitoring warnings (the extract_refresh_failure and flow_run_failure label values) using this method because those warnings are set and cleared automatically, depending on their triggers. See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

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

URI

DELETE api/api-version/sites/site-luid/labels/label-luid

Parameter Values

Request Body

None

Permissions

• To delete a data label other than a certification label, you must have write permission on the associated asset.
• To delete a certification label, you must be an administrator, or else you must be a project leader or product owner for the project the asset is in.
• To delete a certification label for an external asset not in a project, you must have the change permissions permission on the associated asset.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:labels:delete

Response Code

204

Version

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Errors

Delete Labels

Deletes the data labels on one or more assets.

You can optionally limit the data labels to delete by category using a query string.

You can't delete extract refresh or flow run monitoring warnings (the extract_refresh_failure and flow_run_failure label values) using this method because those warnings are set and cleared automatically, depending on their triggers. See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

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

URI

DELETE api/api-version/sites/site-luid/labels

DELETE api/api-version/sites/site-luid/labels?categories=category-list

Parameter Values

Request Body

<tsRequest>
  <contentList>
    <content contentType="asset-type"
      id="asset-luid" />
    <!-- ... additional content elements ... -->
  </contentList>
</tsRequest>      

Attribute Values

Permissions

• To delete a data label other than a certification label, you must have write permission on the associated asset.
• To delete a certification label, you must be an administrator, or else you must be a project leader or product owner for the project the asset is in.
• To delete a certification label for an external asset not in a project, you must have the change permissions permission on the associated asset.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:labels:delete

Response Code

204

Version

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Errors

Delete labelValue

Deletes a label value.

If you use this method on a built-in label value that was customized, this method reverts the label to its built-in defaults instead of deleting it. (Afterwards, assets with the label that you reverted will reflect the built-in default.)

Note that a label value (labelValue) is one property of a label. A label value has its own properties like name, category, and description that determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

A Data Management license is not required to create, update, or delete label values, but one is required to create, update, delete, and see labels on assets.

URI

DELETE api/api-version/sites/site-luid/labelValues/label-value-name

Parameter Values

Request Body

None

Permissions

Only a site or server administrator can create, update, or delete label values.

Response Code

200

Version

Introduced in Tableau Cloud June 2023 (API 3.20) and Tableau Server 2023.3 (API 3.21).

Response Body

None

Errors

Delete Label Category

Deletes a label category.

Note that category is one property of a label value (labelValue), which is itself a property of a label on an asset. Other properties of a labelValue include name and description. These properties determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

A Data Management license is not required to create, update, or delete label categories, but one is required to create, update, delete, and see labels on assets.

URI

DELETE api/api-version/sites/site-luid/labelCategories/label-category-name

Parameter Values

Request Body

None

Permissions

Only a site or server administrator can create, update, or delete label categories.

Response Code

200

Version

Introduced in Tableau Cloud October 2023 (API 3.21) / Server 2023.3 (API 3.21).

Response Body

None

Errors

Delete Table Permissions

Permanently remove the permissions applied to a table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-luid/tables/table-luid/permissions/users/user-luid/capability-name/capability-mode

DELETE api/api-version/sites/site-luid/tables/table-luid/permissions/groups/group-luid/capability-name/capability-mode

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete the permissions on a table asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Delete Tag from Column

Delete a tag from a column.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

DELETE api/api-version/sites/site-id/columns/column-id/tags/tag-name

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete tags:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

Delete Tag from Database

Delete a tag from a database.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

DELETE api/api-version/sites/site-id/databases/database-id/tags/tag-name

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete tags:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

Delete Tag from Table

Delete a tag from a table.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

DELETE api/api-version/sites/site-id/tables/table-id/tags/tag-name

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete tags:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

Batch Delete Tags

Delete multiple tags from items that are different content and asset types.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

DELETE api/api-version/sites/site-id/tags:BatchDelete

Parameter Values

Request Body

<tsRequest>
  <tagBatch>
	<tags>
	   <tag label="tag-value1"></tag>
	   <tag label="tag-value2"></tag>
	</tags>
	<contents>
	   <content id="database-id"></content>
	   <content id="table-id"></content>
	   <content id="column-id"></content>
	   <content id="datasource-id"></content>
	   <content id="workbook-id"></content>
	   <content id="flow-id"></content>
	</contents>
  </tagBatch>
</tsRequest>
      

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete tags:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

Example response

<tsRequest>
  <tagBatch>
	<tags>
	   <tag label="PII"></tag>
	   <tag label="Noteworthy"></tag>
	</tags>
	<contents>
	   <content id="database-id"></content>
	   <content id="table-id"></content>
	   <content id="column-id"></content>
	   <content id="datasource-id"></content>
	   <content id="workbook-id"></content>
	   <content id="flow-id"></content>
	</contents>
  </tagBatch>
</tsRequest>
      

Version

Version 3.9 and later. For more information, see REST API and Resource Versions.

Errors

Delete Tag from Virtual Connection

Deletes a tag from a virtual connection.

Get Label

Gets a data label by its LUID.

For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

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

URI

GET api/api-version/sites/site-luid/labels/label-luid

Parameter Values

Request Body

None

Permissions

To view a data label, you must have read permissions on the associated asset.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:labels:read

Response Code

200

Response Body

<tsResponse>
  <label id="label-luid"
      userDisplayName="user-display-name"
      contentId="asset-luid"
      contentType="asset-type"
      message="label-message"
      value="label-value-name"
      category="label-category"
      active="true-or-false"
      elevated="true-or-false"
      createdAt="datetime"
      updatedAt="datetime" >
    <site id="site-luid"/>
    <owner id="user-luid"/>
  </label>
</tsResponse>

Version

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Errors

Get Labels

Displays information about the data labels on one or more assets.

You can optionally limit the data labels to show by category using a query string.

For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

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

URI

POST api/api-version/sites/site-luid/labels

POST api/api-version/sites/site-luid/labels?categories=category-list

Parameter Values

Request Body

<tsRequest>
  <contentList>
    <content contentType="asset-type"
      id="asset-luid" />
    <!-- ... additional content elements ... -->
  </contentList>
</tsRequest>      

Attribute Values

Permissions

To view a data label, you must have read permissions on the associated asset.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:labels:read

Response Code

200

Response Body

<tsResponse>
  <labelList>
    <label id="label-luid"
        userDisplayName="user-display-name"
        contentId="asset-luid"
        contentType="asset-type"
        message="label-message"
        value="label-value-name"
        category="label-category"
        active="true-or-false"
        elevated="true-or-false"
        createdAt="datetime"
        updatedAt="datetime">
      <site id="site-luid"/>
      <owner id="user-luid"/>
    </label>
    <!-- ... additional label elements ... –->
  </labelList>
</tsResponse>

Version

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Errors

When more than one asset appears in the request (the contentList element contains more than one content element), this method will fail if an error is encountered operating on any of them. For example, if you are getting labels for a database and a table, but you provide the wrong table LUID, the method will return an error even if the database LUID was correct.

Get labelValue

Displays label value properties for a single label value.

Note that a label value (labelValue) is one property of a label. A label value has its own properties like name, category, and description that determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

A Data Management license is not required to create, update, or delete label values, but one is required to create, update, delete, and see labels on assets.

URI

GET api/api-version/sites/site-luid/labelValues/label-value-name

Parameter Values

Request Body

None

Permissions

Any logged in user can view the label values for their site.

Response Code

200

Version

Introduced in Tableau Cloud June 2023 (API 3.20) and Tableau Server 2023.3 (API 3.21).

Response Body

<tsResponse>
  <labelValue name="label-value-name"
    category="labe-value-category"
    description="label-value-description"
    internal="true-or-false"
    elevatedDefault="true-or-false"
    builtIn="true-or-false">
    <site id="site-luid"/>
  </labelValue>
</tsResponse>

Errors

Get Metadata Suggestion

Gets a suggestion from Einstein about asset metadata.

As of June 2024, the type of suggestion is limited to the description for a workbook, data source, or table. Einstein generates the description based on the chosen asset's metadata, such as asset name, field names, and/or column names. This method can't apply the suggested description to the asset.

More than one request results in alternative suggestions.

Note:

• This REST API method uses generative AI. Generative AI can produce inaccurate or harmful responses. Check the output before using. For more information, see Tableau AI and Trust.
• Salesforce's generative AI is built on the Einstein Trust Layer. Your data stays safe and secure through data and privacy controls that are seamlessly integrated into the user experience. For more information, see Einstein Trust Layer(Link opens in a new window).

<tsRequest>
    <contentList>
        <content contentType="asset-type" id="asset-luid" />
    </contentList>
</tsRequest>

{
 "contentList": {
  "content": [
   {"contentType":"asset-type","id":"asset-luid"}
  ]
 }
}

curl --location 'https://cd-main.online.dev.tabint.net//api/3.23/sites/f480b345-8ab5-4e0b-98e6-9553de5748f9/metadataSuggestions?suggestionType=description' --header 'X-Tableau-Auth: 5Jgp0n2lSUaYbTB7NA6Wrw|mtqLBgKQEoup31yMme7la61kywW6LaTm|f480b345-8ab5-4e0b-98e6-9553de5748f9' --header 'Content-Type: application/xml' --data data.xml'

<tsRequest>
  <contentList>
    <content contentType="datasource"
      id="d6092e66-8cb5-495d-990c-823385c6c8db" />
  </contentList>
</tsRequest>

<tsResponse>
    <suggestionList>
        <suggestion suggestionId="suggestion-luid"
            contentType="asset-type"
            contentId="asset-luid"
            suggestionType="suggestion-type"
            text="suggested-description"/>
    </suggestionList>
</tsResponse>

{
    "suggestionList": {
        "suggestion": [
            {
                "suggestionId": "suggestion-luid",
                "contentType": "asset-type",
                "contentId": "asset-luid",
                "suggestionType": "suggestion-type",
                "text": "suggested-description"
            }
        ]
    }
}

Errors

For more information, see Handling Errors.

Get Databases and Tables from Connection

Query databases and tables from the connection information in the data source (.tds or .tdsx) or workbook (.tws or .twbx) file's XML.

Note: This method can't be used to query databases and tables when the database is an embedded asset. For more information about embedded assets see one of the following: 

• For Tableau Cloud, see Embedded asset appears in External Assets(Link opens in a new window).
• For Tableau Server, see Embedded asset appears in External Assets(Link opens in a new window).

URI

POST api/api-version/sites/site-id/databaseAndTables/lookup

Parameter Values

Request Body

<tsRequest>
  <databaseAnchor isArchived="embedded"
    datasourceName="datasource_name" datasourceFormattedName="datasource_format">
	<connectionParams>
	   <base64xml>encoded_xml</base64xml>
  	</connectionParams>
  </databaseAnchor>
</tsRequest> 

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query databases and tables from the connection:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
  <databaseAnchors>
	<databaseAnchor connectionName="mysql.myco" id="71081fcd-d142-4d19-98b5-c87192d837f5">
	  <tableAnchors>
		<tableAnchor id="85e7b082-20c0-433d-9bfe-70506a93452b" name="Marketing" fullName="[Marketing]"/>
	  </tableAnchors>
	</databaseAnchor>
	<databaseAnchor connectionName="sqlserver.myco" id="1ef8c5cc-7d82-4062-aff7-2d9305cab8a1">
	  <tableAnchors>
		<tableAnchor id="8b8c639a-864e-4f29-b1d8-23057d2d59f3" name="Advertising" fullName="[dbo].[Advertising]"/>
	  </tableAnchors>
	</databaseAnchor>
  </databaseAnchors>
</tsResponse>

Note: Both databaseAnchor and tableAnchor IDs returned from this request correspond to database and table IDs that you can use to retrieve additional information about databases and tables endpoints using other REST endpoints, including Query Database and Query Table.

Version

Version 3.13 and later. For more information, see REST API and Resource Versions.

Errors

List labelValues on Site

Lists all label values on the site.

You can optionally limit the list of returned data label values using a query string in the URI.

Note that a label value (labelValue) is one property of a label. A label value has its own properties like name, category, and description that determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

A Data Management license is not required to create, update, or delete label values, but one is required to create, update, delete, and see labels on assets.

URI

GET api/api-version/sites/site-luid/labelValues

GET api/api-version/sites/site-luid/labelValues?categories=category-list

GET api/api-version/sites/site-luid/labelValues?isInternal=internal-flag

Parameter Values

Request Body

None

Permissions

Any logged in user can view the label values for their site.

Response Code

200

Version

Introduced in Tableau Cloud June 2023 (API 3.20) and Tableau Server 2023.3 (API 3.21).

Response Body

<tsResponse>
  <labelValueList>
    <labelValue name="label-value-name"
      category="label-value-category"
      description="label-value-description"
      internal="true-or-false"
      elevatedDefault="true-or-false"
      builtIn="true-or-false">
      <site id="site-luid"/>
    </labelValue>
    <!-- ... additional labelValue elements ... –->
  </labelValueList>
</tsResponse>				

Errors

List Label Categories on Site

Lists all data label categories on the site.

Note that category is one property of a label value (labelValue), which is itself a property of a label on an asset. Other properties of a labelValue include name and description. These properties determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

URI

GET api/api-version/sites/site-luid/labelCategories

Parameter Values

Request Body

None

Permissions

Any logged in user can view the label categories for their site.

Response Code

200

Version

Introduced in Tableau Cloud October 2023 (API 3.21) / Server 2023.3 (API 3.21).

Response Body

<tsResponse>
  <labelCategoryList>
    <labelCategory name="label-category-name"
      description="label-category-description"/>
    <!-- ... additional labelCategory elements ... –->
  </labelCategoryList>
</tsResponse>

Errors

Move Database

Move one or more databases to a project.

You can move the database and its tables, or move only the database. To move a table independently of its database, use the Move Table method.

Note: Starting in Tableau Cloud June 2022 and Tableau Server 2022.3, projects can contain databases and tables, and database and table permissions can be managed at the project level through inheritance. In Tableau Cloud March 2022 and Tableau Server 2022.1 and earlier, projects couldn't contain databases or tables.

The Move Database method can either:

• Move a database from one project to another project.
• Move a database not in a project to a project.

This method can't remove a database from all projects. (The only way to remove a database from all projects is to delete the project that the database is in.)

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-luid/databases

Parameter Values

Request Body

<tsRequest>
  <contentLocationRequest>
    <location id="project-luid" type="location-type" />
    <contentAction action="action-type" />
    <resourceList>
      <resource id="database-luid" contentType="asset-type"/>
      <!-- ... more database resources ... -->
    </resourceList>
  </contentLocationRequest>
</tsRequest>

The contentAction element is optional.

• If the contentAction element is not included, moving the database will also move its tables.
• If the contentAction element is included and the action attribute is set to MoveDatabaseOnly, moving the database will not move its tables.

The resourceList element can contain a minimum of 1 and a maximum of 1000 resource elements.

Attribute Values

Permissions

If you are moving a database without its tables, you must have read and changeHierarchy permissions for the database, and write permission for the target project.

If you are moving both a database and its tables, you must have read and changeHierarchy permissions for both the database and its tables, and write permission for the target project.

Note: Currently, you can only set the ChangeHierarchy permission for databases and tables using the REST API. See Add Database Permissions and Add Table Permissions for information on adding this permission.

Setting the required database and table permissions depends on whether the database is in a project or not.

• If the database is in a project, the database and table permissions will follow the rules for permissions on content inside of projects. See Set Permissions(Link opens in a new window) for information on these rules.
• If the database is not in a project, the database and table permissions will follow the rules for permissions on external assets. See Set permissions on individual external assets(Link opens in a new window) for information on these rules.

Response Code

200

Response Body

Example response when all elements were moved successfully:

<tsResponse />

Example response when not all elements were moved successfully.:

When some database resource elements of a request with multiple database resource elements can’t be moved, the HTTP status 400 is returned, and the response contains additional information about failures. Resource elements from the request body that are not referenced in the response body were successfully moved. A response indicating partial success looks like:

<tsResponse>
  <error code="400000">
    <summary>Bad Request</summary>
    <detail>There was a problem completing one or more requests.</detail>
  </error>
  <warnings>
    <warning message="Database '12ab34cd-56ef-78ab-90cd-12ef34ab56cd' could not be found."
        id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd"
        errorCode="404031"/>
  </warnings>
</tsResponse>     

Version

Introduced Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17). For more information, see REST API and Resource Versions.

Errors

For more information, see Handling Errors.

Example

curl --location --request POST 'http://MY-SERVER/api/3.16/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/databases' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd' -d @move-database.xml

Content of move-database.xml:

<tsRequest>
  <contentLocationRequest>
  <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT" />
    <resourceList>
      <resource id="dd9eb9de-50b3-4f90-a224-e6170e044766" contentType="DATABASE"/>
    </resourceList>
  </contentLocationRequest>
</tsRequest>

Example response:

<tsresponse />

Move Table

Moves one or more tables to a project.

Note: Starting in Tableau Cloud June 2022 and Tableau Server 2022.3, projects can contain databases and tables, and database and table permissions can be managed at the project level through inheritance. In Tableau Cloud March 2022 and Tableau Server 2022.1 and earlier, projects couldn’t contain databases or tables.

The Move Table method can either:

• Move a table from one project to another project.
• Move a table not in a project to a project.

This method can’t remove a table from all projects. (The only way to remove a table from all projects is to delete the project that the table is in.)

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-luid/tables

Parameter Values

Request Body

<tsRequest>
  <contentLocationRequest>
    <location id="project-luid" type="location-type" />
      <resourceList>
        <resource id="table-luid" contentType="asset-type"/>
        <!-- ...more resources... -->
      </resourceList>
  </contentLocationRequest>
</tsRequest>

The resourceList element can contain a minimum of 1 and a maximum of 1000 resource elements.

Attribute Values

Permissions

You must have read and changeHierarchy permissions for the table, and write permission for the target project.

If you are moving both a database and its tables, you must have read and changeHierarchy permissions for both the database and its tables, and write permission for the target project.

Note: Currently, you can only set the ChangeHierarchy permission for databases and tables using the REST API. See Add Database Permissions and Add Table Permissions for information on adding this permission.

Setting the required table permissions depends on whether the parent database is in a project or not.

• If the table is in a project, the table permissions will follow the rules for permissions on content inside of projects. See Set Permissions(Link opens in a new window) for information on these rules.
• If the table is not in a project, the table permissions will follow the rules for permissions on external assets. See Set permissions on individual external assets(Link opens in a new window) for information on these rules.

Response Code

200

Response Body

Example response when all elements were moved successfully:

<tsResponse />

Example response when not all elements were moved successfully.:

When some table resource elements of a request with multiple table resource elements can’t be moved, the HTTP status 400 is returned, and the response contains additional information about failures. Resource elements from the request body that are not referenced in the response body were successfully moved. A response indicating partial success looks like:

<tsResponse>
  <error code="400000">
    <summary>Bad Request</summary>
    <detail>There was a problem completing one or more requests.</detail>
  </error>
  <warnings>
    <warning message="Table '12ab34cd-56ef-78ab-90cd-12ef34ab56cd' could not be found."
      id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd"
      errorCode="404032"/>
    </warnings>
</tsResponse>    

Version

Introduced Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17). For more information, see REST API and Resource Versions.

Errors

For more information, see Handling Errors.

Example

curl --location --request POST 'http://MY-SERVER/api/3.16/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tables' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd' -d @move-table.xml

Content of move-table.xml:

<tsRequest>
  <contentLocationRequest>
  <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT" />
    <resourceList>
      <resource id="ac353e22-3e78-43a7-914f-73e9bd05ec97" contentType="TABLE"/>
    </resourceList>
  </contentLocationRequest>
</tsRequest>

Example response:

<tsresponse />

Query Column in a Table

Get information about a column in a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query a column asset in a table:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
	<column id="0b589fc9-1523-4aae-b711-62d48672ac6a" name="StateProvinceID" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
	  <site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Query Columns in a Table

Get information about the columns in a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/columns

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query column assets in a table:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <columns>
	<column id="38cb9944-4b81-4107-8946-5adf9e047d23" name="AddressID" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
	<column id="c6dcdb0e-9b2a-4224-bf3b-58662fe72b09" name="AddressLine1" remoteType="WSTR" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
  </columns>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Query Database

Get information about a database asset.

URI

GET api/api-version/sites/site-luid/databases/database-luid

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query a database asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse>
  <database id="c495c67b-2a17-4706-991c-b3b14f881e20" name="dataengine_42020_789079537040lea.hyper" connectionType="hyper" isEmbedded="true" isCertified="true" certificationNote="Verified" type="File" filePath="dataengine_42020_789079537040lea.hyper" contentPermissions="ManagedByOwner">
    <site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
    <contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="fsuzuki"/>
    <certifier id="2c5ea058-6408-46a6-9aa2-09f795a31237" name="snguyen"/>
    <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT"/>
    <tags/>
  </database>
</tsResponse>
      

Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Query Databases

Get information about all database assets for a site.

URI

GET api/api-version/sites/site-luid/databases

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query database assets:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse>
  <databases>
	<pagination pageNumber="1" pageSize="100" totalAvailable="496">
	<database id="b749a80e-43eb-4805-9e6d-44c615ee10e2" name="airlines" connectionType="sqlserver" isEmbedded="false" description="This is about airlines and other stuff but mainly airlines"
		isCertified="true" certificationNote="THIS IS ALSO FROM THE REST API"
        type="DatabaseServer" hostName="mssql.test.example.com" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
		<contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="jsmith"/>
        <certifier id="2c5ea058-6408-46a6-9aa2-09f795a31237" name="snguyen"/>
        <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT"/>
        <tags/>
	</database>
	<database id="522f8295-5a07-4ba7-89be-cbbd9617928d" name="small.csv" connectionType="textscan" isEmbedded="true"
        isCertified="false"
         type="File" filePath="small.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
		<contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="fsuzuki"/>
        <tags/>
	</database>
	<database id="fcd0f91e-8c8d-45c4-848a-0aa3b42990c6" name="ows.json" connectionType="semistructpassivestore-direct" isEmbedded="true"
        isCertified="false"
        type="File" filePath="ows.json" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
        <tags/>
	</database>
	<database id="24010777-0e17-43ed-8624-577a85e8043b" name="/Users/awang/Dropbox (Tableau Software)/911_calls_short.csv" connectionType="textscan" isEmbedded="false"
        isCertified="false"
        type="File" filePath="/Users/jsmith/Dropbox (Tableau Software)/911_calls_short.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
        <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT"/>
        <tags/>
	</database>
	<database id="1d1879b2-789d-46c2-950f-f82a4d77e150" name="911_calls_short.csv" connectionType="textscan" isEmbedded="true"
        isCertified="false"
        type="File" filePath="911_calls_short.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
        <tags/>
	</database>
	<database id="bc872610-aa3e-4071-8a39-2c1a847cf39c" name="Prince.xlsx" connectionType="excel-direct" isEmbedded="true"
        isCertified="false"
        type="File" filePath="Prince.xlsx" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
        <tags/>
	</database>
  </databases>
</tsResponse>
      

Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

List Database Permissions

Get information about the permissions on a database asset.

URI

GET api/api-version/sites/site-luid/databases/database-luid/permissions

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users have permissions to query the permissions on the database asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

Example response with explicit permissions set on a database asset:

<tsResponse>
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.example.com:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

Example response without explicit permissions set on a database asset:

<tsResponse>
  <permissions>
	<database id="0f206b0e-da69-4746-bb95-87695f522b4d" name="stage"/>
  </permissions>
</tsResponse>
    

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

List Default Database Permissions

Get the default permissions applied to the database asset and its children tables.

Note: If a database is in a project, default database permissions are not evaluated to determine table permissions. Use Query Default Permissions to see default permissions for projects instead.

URI

GET /api/api-version/sites/site-luid/databases/database-luid/default-permissions/tables

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users set default permissions for the database asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.example.com:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
		
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Query Data Quality Warning by ID

Get information about a specific data quality warning.

URI

GET api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query the data quality warning:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse>
   <dataQualityWarning id="1c8ebdfc-270a-4414-812c-3306a1c95e07" userDisplayName="Steve Nguyen" contentId="0d7465f2-4989-417e-b88d-f787359edc63" contentType="DATABASE" message="Delayed" type="WARNING" isActive="true" createdAt="2020-10-08T00:00:35Z" updatedAt="2020-10-08T00:00:35Z" isSevere="false">
	<site id="a946d998-2ead-4894-bb50-1054a91dcab3"/>
	<owner id="cdfe8548-84c8-418e-9b33-2c0728b1234a"/>
   </dataQualityWarning>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Query Data Quality Warning by Content

Get information about the data quality warning for the database, table, column, published data source, flow, virtual connection, or virtual connection table.

URI

GET api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query the data quality warning:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse>
   <dataQualityWarningList>
	<dataQualityWarning id="3b9fa2df-0915-4cda-9e29-bccb64a2eb7b" userDisplayName="Steve Nguyen" contentId="924ae707-a915-498d-b909-a86cd5135b8d" contentType="DATABASE" message="Talk to admin" type="WARNING" isActive="true" createdAt="2021-01-12T01:04:55Z" updatedAt="2021-01-12T01:04:55Z" isSevere="false">
	   <site id="3d512018-64c4-4b66-a1fa-1c83710e323c"/>
	   <owner id="2bfe6c21-17e0-449a-8e5c-382e740eca85"/>
	</dataQualityWarning>
   </dataQualityWarningList>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Query Data Quality Certification by ID

Get information about a data quality certification.

URI

GET api/api-version/sites/site-id/dataQualityCertification/certification-luid

Parameter Values

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query a data quality certification:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
   <dataQualityIndicator>
	id="d5a4006c-0276-4c5a-bb98-712815c91ce7"
	userDisplayName="Mark Nguyen"
	contentId="a34884d0-1d80-4505-bf21-c6b7ce10814a" contentType="DATASOURCE"
	message="Marketing approved"
	type="CERTIFIED" active="true"
	createdAt="2021-06-08T17:22:20Z"
	updatedAt="2021-09-08T17:27:57Z" severe="false"/>
	siteID="284e2a17-65c8-47bf-b88f-ff96d69c2303"
	ownerID="f95180e7-0c64-4a58-86da-b9f4d3db2583"
   </dataQualityIndicator>
</tsResponse>

Version

Version 3.13 and later. For more information, see REST API and Resource Versions.

Errors

Query Data Quality Certifications by Content

Get all data quality certifications for content or asset items.

URI

GET api/api-version/sites/site-id/dataQualityCertifications/content-type/content-luid

Parameter Values

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query data quality certifications:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
   <dataQualityIndicator>
	id="d5a4006c-0276-4c5a-bb98-712815c91ce7"
	userDisplayName="Mark Nguyen" contentId="a34884d0-1d80-4505-bf21-c6b7ce10814a"
	contentType="DATASOURCE"
	message="Marketing approved"
	type="CERTIFIED" active="true"
	createdAt="2021-06-08T17:22:20Z"
	updatedAt="2021-09-08T17:27:57Z"
	severe="false"/>
	siteID="284e2a17-65c8-47bf-b88f-ff96d69c2303"
	ownerID="f95180e7-0c64-4a58-86da-b9f4d3db2583"
   </dataQualityIndicator>
</tsResponse>

Version

Version 3.13 and later. For more information, see REST API and Resource Versions.

Errors

Query Quality Warning Trigger

Get information about a quality warning trigger.

URI

GET api/api-version/sites/site-id/dataQualityTriggers/trigger-id

Parameter Values

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query a quality warning trigger:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
  <dataQualityTriggerList>
	<dataQualityTrigger id="{trigger-luid}" siteId="{site-luid}"
		userId="1c8ebdfc-270a-4414-812c-3306a1c95e07" userDisplayName="Joe Nguyen" contentId="{content-luid}"
		contentType="DATASOURCE" message=" This message is specified by the user."
		type="EXTRACT_REFRESH" active="true" createdAt="Wed Sep 22 05:49:52 UTC 2020"
		updatedAt="Wed Sep 22 05:49:52 UTC 2020" severe="false"/>
  </dataQualityTriggerList>
</tsResponse>     

Version

Version 3.11 and later. For more information, see REST API and Resource Versions.

Errors

Query All Quality Warning Triggers by Content

Get information about all quality warning triggers for a content item.

URI

GET api/api-version/sites/site-id/dataQualityTriggers/content-type/content-luid

Parameter Values

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query quality warning triggers:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
  <dataQualityTriggerList>
	<dataQualityTrigger id="{trigger-luid}" siteId="{site-luid}"
		userId="f95180e7-0c64-4a58-86da-b9f4d3db2583" userDisplayName="Mark Nguyen" contentId="a34884d0-1d80-4505-bf21-c6b7ce10814a"
		contentType="DATASOURCE" message=" This message is specified by the user."
		type="EXTRACT_REFRESH" active="true" createdAt="Wed Sep 22 05:49:52 UTC 2020"
		updatedAt="Wed Sep 22 05:49:52 UTC 2020" severe="false"/>
  </dataQualityTriggerList>
</tsResponse>    

Version

Version 3.11 and later. For more information, see REST API and Resource Versions.

Errors

Query Table

Get information about a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query the table asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <table id="917b1438-7000-4a9e-a949-13b90a0237dd" name="[Orders$]" isEmbedded="true" isCertified="false">
	<site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
  </tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Query Tables

Get information about all table assets for a site.

URI

GET api/api-version/sites/site-id/tables

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query table assets:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <tables>
	<table id="6a9b6058-671d-44bc-ad6d-c58b225f5d4c" name="Culture" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
 	</table>
	<table id="917b1438-7000-4a9e-a949-13b90a0237dd" name="[Orders$]" isEmbedded="true" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
	<table id="58d94f3f-1339-4721-8674-e53dc9dfe02e" name="Batters" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
	<table id="5e8ca1e3-9752-430c-abae-11104084b469" name="[911_calls_short#csv]" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
  </tables>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

List Table Permissions

Get information about the permissions on a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/permissions

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users have permissions to query the permissions on the table asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

Example response with explicit permissions set:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<table id="d0fe66ae-1407-4338-8520-9489d7ce959c" name="_WarehouseConfig"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

Example response without explicit permissions set:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<parent id="95ac9b30-5b2c-48ed-af56-cab9b0d4b064" type="Database"/>
	  <table id="4ef842be-5c90-4878-a048-99a896b59996" name="BigMachines"/>
  </permissions>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Remove Column

Permanently remove the column from a table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to remove the column:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Remove Database

Permanently remove the database asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/databases/database-id

Parameter Values

Request Body

None

Permissions

Server or site administrators only.

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to remove the database asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Remove Table

Permanently remove the table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/tables/table-id

Parameter Values

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to remove the table asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Update Column

Update the description of the column.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

Request Body

<tsRequest>
  <column description="new-description-value">
  </column>
</tsRequest>
      

Attribute Values

Any combination of attributes inside the <column> element is valid. Only the attributes and child elements that are included result in updates to the table. If no attributes or nested elements are included, no update is made.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update the column:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <column id="0b589fc9-1523-4aae-b711-62d48672ac6a" name="StateProvinceID" description="Validated against maps" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
  </column>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Update Database

Update the database description, certify a database, set database permissions, or assign a Tableau Cloud or Server user as the database contact.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-luid/databases/database-luid

Parameter Values

Request Body

<tsRequest>
  <database isCertified="certification-status"
      certificationNote="certification-note"
      description="new-description-value"
      contentPermissions="new-content-permissions">
    <contact id="new-contact-luid" />
  </database>
</tsRequest>
      

Attribute Values

Any combination of attributes inside the <database> element is valid. Only the attributes and child elements that are included result in updates to the database asset. If no attributes or nested elements are included, no update is made.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update the database asset:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse>
  <database id="31d6ab16-3821-489b-8197-39453ce94a49" name="coffee" connectionType="sqlserver" isEmbedded="false" description="Contact Susan Nguyen (database admin) for changes." isCertified="true" certificationNote="Removed certification via REST" type="DatabaseServer" hostName="mssql.test.tsi.lan" contentPermissions="LockedToDatabase">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	<contact id="2a80c15e-87c8-4b07-a5f4-e49f95e9fb0b" name="fsuzuki"/>
	<certifier id="26183d16-82f7-4fcf-b163-0e607bf292bc" name="admin"/>
  </database>
</tsResponse>
      

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Update Data Quality Warning

Update the warning type, status, and message of a data quality warning.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

Request Body

<tsRequest>
  <dataQualityWarning type="type" isActive="status" message="message" isSevere="severity"/>
</tsRequest>    

Attribute Values

Any combination of attributes inside the <dataQualityWarning> element is valid, but the data quality warning type is required. If the data quality warning type is not included, an error is thrown.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update the data quality warning:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse>
   <dataQualityWarning id="3b9fa2df-0915-4cda-9e29-bccb64a2eb7b" userDisplayName="Steve Nguyen"
	contentId="924ae707-a915-498d-b909-a86cd5135b8d" contentType="DATABASE" message="OUT OF DATE - DO NOT USE"
	type="WARNING" isActive="true" createdAt="2021-01-12T01:04:55Z" updatedAt="2021-01-12T01:23:04Z"
	isSevere="true">
	<site id="3d512018-64c4-4b66-a1fa-1c83710e323c" />
	<owner id="2bfe6c21-17e0-449a-8e5c-123e740eca45" />
   </dataQualityWarning>
</tsResponse>     

Version

Version 3.5 and later. For more information, see REST API and Resource Versions.

Errors

Update Monitoring Quality Warning

Update a monitoring quality warning.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-id/dataQualityTriggers/trigger-id

Parameter Values

Request Body

<tsRequest>
  <dataQualityTrigger type="type" active="status" message="message" severe="severity"/>
</tsRequest>

Attribute Values

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update a monitoring quality warning:

• Tableau Server admins or Tableau Cloud site admins
• Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <dataQualityTriggerList>
	<dataQualityTrigger id="{trigger-luid}" siteId="{site-luid}"
		userId="{user-luid}" userDisplayName="Joe Nguyen" contentId="{content-luid}"
		contentType="DATASOURCE" message=" This message is specified by the user."
		type="EXTRACT_REFRESH" active="true" createdAt="Wed Sep 22 05:49:52 UTC 2020"
		updatedAt="Wed Sep 22 05:49:52 UTC 2020" severe="false"/>
  </dataQualityTriggerList>
</tsResponse>

Version

Version 3.11 and later. For more information, see REST API and Resource Versions.

Errors

Update Label

Updates a label by its LUID.

This method can update the label value, message, active flag, and elevated flag.

You can't update the label category. If you choose a label value name that's associated with a different category, you get an error. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

You can't update extract refresh or flow run monitoring warnings (the extract_refresh_failure and flow_run_failure label values) using this method because those warnings are set and cleared automatically, depending on their triggers. See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

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

URI

PUT api/api-version/sites/site-luid/labels/label-luid

Parameter Values

Request Body

<tsRequest>
  <label
    value="label-value-name"
    message="label-message"
    active="active-flag"
    elevated="elevated-flag" />
</tsRequest>

Attribute Values

Permissions

• To add or update a data label other than a certification label, you must have write permission on the associated asset.
• To add or update a certification label, you must be an administrator, or else you must be a project leader or product owner for the project the asset is in.
• To add or update a certification label for an external asset not in a project, you must have the change permissions permission on the associated asset.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:labels:update

Response Code

200

Response Body

<tsResponse>
  <label id="label-luid"
      userDisplayName="user-display-name"
      contentId="asset-luid"
      contentType="asset-type"
      message="label-message"
      value="label-value-name"
      category="label-category"
      active="true-or-false"
      elevated="true-or-false"
      createdAt="datetime"
      updatedAt="datetime" >
    <site id="site-luid"/>
    <owner id="user-luid"/>
  </label>
</tsResponse>

Version

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Errors

Update Labels

Creates or updates labels on one or more assets.

Each asset listed in the request body is updated to have a label with the specified value, message, active flag, and elevated flag.

If the request body specifies a label value that is already on the asset, the label on the asset is updated to match the request body. Otherwise, a label is created and attached to the asset.

Note: On Tableau Server 2023.3 and earlier, only one label of a category is allowed on an asset. If the request body specifies a label value with the same category as a label already on the asset, the label on the asset is updated to match the request body. Otherwise, a label is created and attached to the asset.

Note that the label category is not an attribute in the request body, because you do not set it explicitly. Instead you implicitly set the category by using the label value name. For example, choosing a label value name of stale means that the label value category will be warning. Also, you can't update the label category on an existing label. If you set the label value to one that's in a different category, you get an error. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.

You can't update extract refresh or flow run monitoring warnings (the extract_refresh_failure and flow_run_failure label values) using this method because those warnings are set and cleared automatically, depending on their triggers. See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

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

URI

PUT api/api-version/sites/site-luid/labels

Parameter Values