Tableau REST API Help

Add analytics extension connection to site

Adds an analytics extensions connection for an external service to a site.

POST {server}/api/-/settings/site/extensions/analytics/connections

view details

Add Ask Data Lens Permissions - Retired in API 3.22

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).

Adds permissions to the specified ask data lens for a user or group. You can specify multiple sets of permissions using one request.

If a specified permission has already been granted or denied for a given user or group, the system ignores it.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
content-type	The type of asset that the data quality warning is being attached to. To specify the type, use: database table column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3) datasource flow virtual connection virtual connection table These values are not case sensitive.
content-luid	The unique ID of the asset (database, table, column, published data source, flow, virtual connection, or virtual connection table). This is the same as the content ID.

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.

type	Type of data quality warning to apply to the asset. To specify the type, use one of the following values: DEPRECATED WARNING STALE SENSITIVE_DATA MAINTENANCE These values are case sensitive.
state	(Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default. For more information about data quality warnings, see "Set a Data Quality Warning" in the Server Help or Cloud Help.
message	(Optional. Was required in Tableau Server 2023.3 and earlier.) A custom message to accompany the data quality warning.
severity	(Optional) Enables high visibility for the data quality warning when set to "true". Value can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400108	Generic add data quality warning error	The data quality warning could not be added for some other reason than those specified in this table.
400	400109	Bad request	The request body is missing the data quality warning type.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The requested asset could not be found.
409	409004	Invalid parameter	One or more values in the request body are invalid.

Add Data Source Permissions

Adds permissions to the specified data source for a user or group. You can specify multiple sets of permissions using one call.

If a specified permission has already been granted or denied for a given user or group, the system ignores it.

If the request body includes a child workbook or <project> element, the request is invalid.

Add Data Source to Favorites

Adds the specified data source to the user's favorites.

If the user already has the data source listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

Add Data Source to Server Schedule

Adds a task to refresh a data source to an existing server schedule on Tableau Server.
For Tableau Cloud, see Create Cloud Extract Refresh Task.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
database-luid	The LUID of the database asset.

Request Body

Request Attributes

database	The LUID of the database asset you want to add permissions to.
user id	The LUID of the user to add permissions for.
capability name	The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a database are: Read (view) Write (edit) ChangePermissions (set permissions) ChangeHierarchy (move) These values are case sensitive.
capability mode	Use one of the following capabilities: Allow Deny These values are case sensitive.
group id	The LUID of the group to add permissions for.

Response Code

200

Response Body

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400120	Bad request	Permissions could not be added because support for explicit permissions is available for database assets associated with published data sources only.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
404	404031	Database not found	The requested database could not be found.
405	405000	Invalid request method	Request type was not PUT.
409	409045	Database error	An unknown database asset error occurred.
409	409050	Database update error	An unknown error occurred and the database asset could not be updated.
409	409051	Database update forbidden	A user without "write" permissions to the database asset attempted an update.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
database-luid	The LUID of the database asset to set default permissions for.

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

user-luid	The LUID of the user to add default permissions for.
group-luid	The LUID of the group to add permissions for.
capability-name	The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a databases are the following: Read (view) Write (edit) ChangePermissions (set permissions) ChangeHierarchy (move) These values are case sensitive.
capability-mode	Use one of the following capabilities: Allow Deny These values are case sensitive.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	Permissions setting forbidden	A non-administrator user called this method but doesn't have permission to add permissions on the project.
403	403114	Permissions setting forbidden	Default permissions cannot be added because the database asset is locked.
404	404000	Site not found	The site LUID in the URI doesn't correspond to an existing site.
404	404003	Resource not found	The database LUID in the URI doesn't correspond to a database asset on the site.
404	404002	User not found	A user LUID in the request body as the grantee doesn't correspond to an existing user.
404	404012	Group not found	A group LUID in the request body doesn't correspond to an existing group.
404	404013	Capability not found	The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405	405000	Invalid request method	Request type was not PUT.

Add Default Permissions

Adds default permission rules for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also adds default permission rules for database or table resources in a project for a user or group. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project. For more information, see Permissions(Link opens in a new window).

Content owners can override default permissions for their content, but only if project permissions have not been locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project(Link opens in a new window).

Add Flow Permissions

Adds permissions to the specified flow for a Tableau Server user or group. You can specify multiple sets of permissions using one call.

Add Flow Task to Server Schedule

The Add Flow Task to Schedule method is renamed and retired for Tableau Cloud in API 3.22 (Tableau Cloud March 2024). It will remain available for Tableau Server only. For Tableau Cloud in March 2024, this method will be replaced with Create Cloud Flow Task method.

Adds a task to run a flow to an existing schedule.

Note: This method is unavailable if you do not have a Data Management license or Tableau Prep Conductor is disabled for your site.

Add Flow to Favorites

Adds the specified flow to the user's favorites.

If the user already has the flow listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

Add Group to Group Set

Adds group to a group set.

URI

PUT api/api-version/sites/site-id/groupsets/group-set-id/groups/group-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
group-set-id	The unique ID of the group set you want to add the group to.
group-id	The unique ID of the group you want to add to the group set.

Request Body

None

Response Code

200

Response Body

None

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404012	Group not found	The group ID in the request body doesn't correspond to an existing group.
409	409120	Group set not found	The group set ID in the request body doesn't correspond to an existing group.

For more information, see Handling Errors.

Add Metric to Favorites - Retired in API 3.22

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).

Adds the specified metric to the user's favorites.

If the user already has the metric listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
content-type	The type of content the monitoring is being applied to. Use one of the following values: datasource flow These values are not case sensitive.
content-luid	The LUID of the asset. This is the same as the content ID. The square brackets are required around the single LUID or comma-separated list of LUIDs.

Request Body

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

Attribute Values

type	Type of monitoring quality warning. To specify the type, use one of the following values: EXTRACT_REFRESH FLOW_RUN These values are not case sensitive.
status	Monitoring status. Values can be "true" or "false". If set to "true", the data source is monitored for extract refresh failures or the flow is monitored for flow run failures). If an extract refresh or flow run failure occurs, the specified data quality warning is attached to the data source or flow (depending on type). The data quality warning is removed when the extract refresh or flow run is successful. For more information about monitoring quality warnings, see the monitoring quality warning section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.
message	(Optional) A custom message for the data quality warning.
severity	High visibility status of the data quality warning. Values can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

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

HTTP status	error Code	Condition	Details
400	400136	Generic quality warning trigger error	The monitoring quality warning could not be added or updated for some other reason than those specified below.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
409	409004	Invalid parameter	One or more values in the request body are invalid.

Add Project Permissions

Adds permissions to the specified project for a user or group. You can specify multiple sets of permissions using one call.

If the request body includes a child datasource or <project> element, the request is invalid.

Add Project to Favorites

Adds the specified project to a user's favorites.

If the user already has the project listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
table-luid	The LUID of the table asset.

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

table-luid	The LUID for the table asset you want to add permissions to.
user-luid	The LUID of the user to add permissions for.
capability-name	The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a database are: Read (view) Write (edit) ChangePermissions (set permissions) ChangeHierarchy (move) These values are case sensitive.
capability-mode	Use one of the following capabilities: Allow Deny These values are case sensitive.
group-id	The LUID of the group to add permissions for.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400120	Bad request	Permissions could not be added because support for explicit permissions is available for table assets associated with published data sources only.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
403	403117	Database locked	Permissions for the table asset cannot be deleted because the database asset is locked.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
404	404032	Table not found	The requested table asset could not be found.
409	409052	Table error	An unknown table asset error occurred.
409	409057	Table update error	An unknown error occurred and the table asset could not be updated.
409	409058	Table update forbidden	A user without "write" permissions to the table asset attempted an update.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
column-id	The unique ID of the column asset.

Request Body

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

Attribute Values

tag-value1	Keyword text you want to add to the asset.
tag-value2	Keyword text you want to add to the asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
409	409062	Generic column tag error	The tag or tags could not be added (or deleted) for some other reason than those specified above.
409	409066	Column not found	The column asset does not exist.

Add Tags to Data Source

Adds one or more tags to the specified data source.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
database-id	The unique ID of the database asset.

Request Body

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

Attribute Values

tag-value1	Keyword text you want to add to the asset.
tag-value2	Keyword text you want to add to the asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404031	Database not found	The database asset does not exist.
409	409048	Generic database tag error	The tag or tags could not be added (or deleted) for some other reason than those specified above.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the column asset.

Request Body

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

Attribute Values

tag-value1	Keyword text you want to add to the asset.
tag-value2	Keyword text you want to add to the asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404032	Table not found	The table asset does not exist.
409	409055	Generic table tag error	The tag or tags could not be added (or deleted) for some other reason than those specified above.

Add Tags to View

Adds one or more tags to the specified view.

Add Tags to Virtual Connection

Adds tags to a virtual connection.

Add Tags to Workbook

Adds one or more tags to the specified workbook.

Add User to Data-Driven Alert

Adds a specified user to the recipients list for a data-driven alert.

URI

POST /api/api-version/sites/site-id/dataAlerts/data-alert-id/users

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the specified data-driven alert.
data-alert-id	The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

Add User to Group

Adds a user to the specified group.

Beginning in API 3.21, you can bulk add users to a group by specifying multiple user IDs.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Add User to Identity Pool

Add a user to a specified identity pool.

This enables the user to sign in to Tableau Server using the specified identity pool. This method is not available for Tableau Cloud.

For more information about identity pools, see Provision and Authenticate Users Using Identity Pools(Link opens in a new window).

Add User to Site

Adds a user to Tableau Server or Tableau and assigns the user to the specified site.

Tableau Server

If Tableau Server is configured to use local authentication, the information you specify is used to create a new user in Tableau Server.

Note: After creating the user, you must set a full name, password, and email address for the user with the call to Update User. If you are using SAML with local authentication, the user information that you add is not synchronized with the SAML IdP, as it would be if you were using Active Directory. Even if it is not used by SAML, the user information must be present.

If Tableau Server is configured to use Active Directory for authentication, the user you specify is imported from Active Directory into Tableau Server.

Tableau Cloud

When you add a user to Tableau Cloud, the name of the user must be the email address that is used to sign in to Tableau Cloud. After you add a user, Tableau Cloud sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password.

If you try to add a user using a specific site role but you have already reached the limit on the number of licenses for your users, the user is added as an unlicensed user. In that case, the response code is 201 (which indicates success), but the siteRole value in the response body is set to Unlicensed.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Add View Permissions

Adds permissions to the specified view (also known as a sheet) for a user or group. You can specify multiple sets of permissions using one call.

Add View to Favorites

Adds the specified view to a user's favorites.

If the user already has the view listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

Add Virtual Connection Permissions

Adds permissions to the specified virtual connection for a user or group. You can specify multiple sets of permissions using one call.

If a specified permission has already been granted or denied for a given user or group, the system ignores it.

Add Workbook Permissions

Adds permissions to the specified workbook for a user or group. You can specify multiple sets of permissions using one call.

Add Workbook to Favorites

Adds the specified workbook to a user's favorites.

If the user already has the workbook listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

Add Workbook to Server Schedule

Adds a task to refresh or accelerate a workbook to an existing schedule on Tableau Server.

The task type must match the schedule type. For a list of schedule types, see Create a Schedule.
For Tableau Cloud, see Create Cloud Extract Refresh Task.

This method is not available for Tableau Cloud.

Starting in Tableau version 2022.1 (API v3.16), with the introduction of View Acceleration(Link opens in a new window), the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases resulting in error codes being returned.

Allow dashboard extension on site - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

POST {server}/api/-/settings/site/extensions/dashboard/safeListItems

view details

Append to File Upload

Uploads a block of data and appends it to the data that is already uploaded. This method is called after an upload has been initiated using Initiate File Upload.

You call Append to File Upload as many times as needed in order to upload the complete contents of a file. When the final block of data has been uploaded, you call Publish Data Source, Publish Flow, or Publish Workbook to commit the file.

For more information, see Publishing Resources.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

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.

content	The type of content or asset the data quality warning is attached to. To specify type, use one of the following values: database table datasource virtualconnection virtualconnectiontable
database-id	The unique ID of the database asset.
table-id	The unique ID of the table asset.
datasource-id	The unique ID of the data source content.
virtualconnection-id	The unique ID of the virtual connection asset.
virtualconnectiontable-id	The unique ID of the virtual connection table asset.
type	Use the following value to apply a data quality certification: CERTIFIED.
message	A custom message to accompany the data quality certification.
state	(Optional) Controls whether the data quality certification displays. Value can be "true" or "false". If the state is not specified, the data quality certification is set to "true" and is visible by default. For more information about data quality certifications, see "Set a Data Quality Certification" in the Server Help or Cloud Help.
severity	(Optional) Enables high visibility for when the data quality certification is set to "true". Value can be "true" or "false". If the severity is not specified, the data quality certification is set to "false." This setting is available only through the REST API.

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

HTTP status	error Code	Condition	Details
400	400108	Generic data quality certification error	The data quality certification could not be added for some reason other than those specified in this table.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404029	Content not found	The content does not exist.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

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

content	The type of content or asset the data quality warning is attached to. To specify type, use one of the following values: database table column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3) datasource flow virtualconnection virtualconnectiontable
database-id	The unique ID of the database asset.
table-id	The unique ID of the table asset.
column-id	The unique ID of the column asset.
datasource-id	The unique ID of the data source content.
flow-id	The unique ID of the flow content.
virtualconnection-id	The unique ID of the virtual connection.
virtualconnectiontable-id	The unique ID of the virtual connection table.
type	The type of data quality warning to apply to the content or asset. To specify type, use one of the following values: DEPRECATED WARNING STALE SENSITIVE_DATA MAINTENANCE
message	(Optional) A custom message to accompany the data quality warning.
state	(Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default. For more information about data quality warnings, see "Set a Data Quality Warning" in the Server Help or Cloud Help.
severity	(Optional) Enables high visibility for when the data quality warning is set to "true". Value can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

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

HTTP status	error Code	Condition	Details
400	400109	Bad request	The content of the request body (content type, content id, or dataQualityWarning attributes) is missing, incomplete, or contains malformed XML.
400	400108	Generic add data quality warning error	The data quality warning could not be added for some other reason than those specified in this table.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404029	Content not found	The content does not exist.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

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

tag-value1	Keyword text you want to add to item.
tag-value2	Keyword text you want to add to item.
database-id	The unique ID of the database asset.
table-id	The unique ID of the table asset.
column-id	The unique ID of the column asset.
datasource-id	The unique ID of the data source content.
workbook-id	The unique ID of the workbook content.
flow-id	The unique ID of the flow content.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404029	Content not found	The content does not exist.
404	404031	Database not found	The database asset does not exist.
404	404032	Table not found	The table asset does not exist.
409	409004	Invalid parameter	One or more values in the request body are invalid.
409	409066	Column not found	The column asset does not exist.

Batch create subscriptions

Creates multiple subscriptions to a metric for specified users and/or groups.

POST {server}/api/-/pulse/subscriptions:batchCreate

view details

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

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

content	The type of content or asset the data quality warning is attached to. To specify type, use one of the following values: database table column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3) datasource flow virtualconnection virtualconnectiontable
database-id	The unique ID of the database asset.
table-id	The unique ID of the table asset.
column-id	The unique ID of the column asset.
datasource-id	The unique ID of the data source content.
flow-id	The unique ID of the flow content.
virtualconnection-id	The unique ID of the virtual connection.
virtualconnectiontable-id	The unique ID of the virtual connection table.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404029	Content not found	The content does not exist.
404	404031	Database not found	The database asset does not exist.
404	404032	Table not found	The table asset does not exist.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

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

tag-value1	Keyword text you want to add to item.
tag-value2	Keyword text you want to add to item.
database-id	The unique ID of the database asset.
table-id	The unique ID of the table asset.
column-id	The unique ID of the column asset.
datasource-id	The unique ID of the data source content.
workbook-id	The unique ID of the workbook content.
flow-id	The unique ID of the flow content.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404029	Content not found	The content does not exist.
404	404031	Database not found	The database asset does not exist.
404	404032	Table not found	The table asset does not exist.
409	409004	Invalid parameter	One or more values in the request body are invalid.
409	409066	Column not found	The column asset does not exist.

Batch get subscriber counts

Gets the number of unique users subscribed to a set of metrics specified in a comma separated list of metric LUIDs.

GET {server}/api/-/pulse/subscriptions:batchGetMetricFollowerCounts

view details

Batch get subscriptions

Gets a batch of subscriptions, specified in a comma delimited list of subscriptions LUIDs.

GET {server}/api/-/pulse/subscriptions:batchGet

view details

Batch list metric definitions

Gets a batch of metric definitions and metrics available on a site.

GET {server}/api/-/pulse/definitions:batchGet

view details

Batch list metrics

Gets a batch of metrics from a definition, specified in a comma delimited list.

GET {server}/api/-/pulse/metrics:batchGet

view details

Block dashboard extension on server - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

POST {server}/api/-/settings/server/extensions/dashboard/blockListItems

view details

Cancel Flow Run

Cancels a flow run that is in progress.

Cancel Job

Cancels a job specified by job ID. To get a list of job IDs for jobs that are currently queued or in-progress, use the Query Jobs method.

The following jobs can be canceled using the Cancel Job method:

• Full extract refresh
• Incremental extract refresh
• Subscription
• Flow Run
• Data Acceleration (Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)
• Bridge full extract refresh
• Bridge incremental extract refresh
• Queue upgrade Thumbnail (Job that puts the upgrade thumbnail job on the queue)
• Upgrade Thumbnail

Configure Identity Store

Configure a new local identity store to provision users.

POST {server}/api/-/authn-service/identity-stores

view details

Create a Webhook

Creates a new webhook for a site.

Create an Extract for a Data Source

Create an extract for a data source in a site. Optionally, encrypt the extract if the site and workbooks using it are configured to allow it.

Create ask data lens - Retired in API 3.22

---

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau GPT and Tableau Pulse are reimagining the data experience.

---

POST {server}/api/-/askdata/lenses

view details

Create Authentication Configuration

Create an instance of OpenID Connect (OIDC) authentication.

POST {server}/api/-/authn-service/auth-configurations

view details

Create Cloud Extract Refresh Task

Creates a custom schedule for an extract refresh on Tableau Cloud.
For Tableau Server, see Add data source to server schedule and Add workbook to server schedule.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
404	404026	Task not found	The task for the extract refresh could not be found.
409	409004	invalid parameter value	The request is malformed or contains an invalid or missing schedule or interval parameter value. When the difference between start and end times are not increments of one hour, this error will result.

For more information, see Handling Errors.

Create Cloud Flow Task

Creates a flow task on Tableau Cloud, and set its schedule.

Note: This method is unavailable if you do not have a Data Management license or Tableau Prep Conductor is disabled for your site.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.

For more information, see Handling Errors.

Create Connected App

Create a connected app.

A connected app can be used to securely authenticate your users to Tableau content embedded in a custom application or for REST API authorization (introduced to Tableau Cloud in June 2022 and Tableau Server 2023). By creating a connected app, you can establish a trusted relationship between Tableau and any custom application.

For more information about connected apps, see one of the following:

• For Tableau Server: Configure Tableau Connected Apps to Enable SSO for Embedded Content
• For Tableau Cloud: Configure Tableau Connected Apps with Direct Trust(Link opens in a new window)

URI

POST api/api-version/sites/site-id/connected-apps/direct-trust

Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

Request Body

Tableau Cloud and Tableau Server using API 3.23 or later

<tsRequest>
  <connectedApplication
		name="name"
		enabled="enabled"
		domainSafelist="domainSafelist"
		unrestrictedEmbedding="unrestrictedEmbedding">
				<projectIds>
					<projectId>project_id</projectId>
					<projectId>project_id</projectId>
					<projectId>project_id</projectId>
				</projectIds>
  <connectedApplication />
</tsRequest>

Tableau Server (or Tableau Cloud) using API 3.21 or earlier

<tsRequest>
  <connectedApplication
		name="name"
		enabled="enabled"
		projectId="project_id"
		domainSafelist="domainSafelist"
	unrestrictedEmbedding="unrestrictedEmbedding" />
</tsRequest>

Attribute Values

Any combination of attributes inside the <connectedApplication> element is valid, however name is required.

name	Name of the connected app.
enabled	(Optional) Controls whether the connected app is enabled or not. Value can be "true" or "false". If the state is not specified, the connected app is set to "false" and not enabled by default.
project_id	(Optional, embedding workflows only) The IDs of the projects that the connected app's access level is scoped to. To get a project's project ID, see Query Projects. You can specify one project, multiple projects, all projects on a site. Single project: For Tableau Cloud (using API 3.22 or later) and Tableau Server (using API 3.23 or later), to scope the connected app's access to one project, the recommended workflow is to specify the projectIds and projectId attributes and projectId value. For Tableau Server (or Tableau Cloud) using API 3.21 or earlier, specify the projectId parameter and its value. Multiple projects: Beginning with API 3.22 (February 2024) for Tableau Cloud and API 3.23 for Tableau Server, you can specify the projectIds attribute and projectId values to scope the connected app's access to multiple projects. All projects: For Tableau Cloud (using API 3.22 or later) and Tableau Server (using API 3.23 or later), to scope the connected app's access to all projects on a site, omit the projectIds attribute from the request. For Tableau Server (or Tableau Cloud) using API 3.21 or earlier, to scope the connected app's access to all projects on a site, omit the projectId attribute from the request. Note: Specifying "all projects" in an update request for a connected app is handled differently. For more information, see update project(Link opens in a new window). Note: The stand-alone projectId attribute will be retired in a future release so we recommend using projectIds attribute instead.
domainSafelist	(Optional, embedding workflows only) A list of domains the connected app is allowed to be hosted. Specify one or more URLs, separated by spaces, using a format described in Domain allowlist rules(Link opens in a new window) in the Tableau Server Help or Domain allowlist rules(Link opens in a new window) in the Tableau Cloud Help. Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. For example: https://tableau.com https://myco.com:552 marketing.example.com
unrestrictedEmbedding	(Optional, embedding workflows only) Controls whether the connected app can be hosted on all domains. If "true" value is specified, the connected app can be hosted on all domains. If "false" value is specified, the connected app can only be hosted on the domains specified in the <domainSafelist> attribute.

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

201

Response Body

Example response:

<tsResponse>
  <connectedApplication>
	<name>ConnectedApp_MyCo</name>
	<enabled>true</enabled>
	<clientId>ac95d175-c844-4779-9d58-415e01fe7dab</clientId>
	<projectIds>
		<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
		<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
	</projectIds>
	<createdAt>2021-08-10T18:46:30Z</createdAt>
	<unrestrictedEmbedding>true</unrestrictedEmbedding>
  </connectedApplication>
</tsResponse>

Note: When the scope of the connected app's access is set to all projects, the request does not return the projectId attribute.

Version

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

The resource, POST /api/api-version/sites/site-id/connected-apps/direct-trust, was added in version 3.17. The original resource, POST /api/api-version/sites/site-id/connected-applications, was deprecated in API 3.17 and will be retired in a future release.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400109	Bad request	The request body can't be empty.
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404041	Connected app not found	The requested connected app could not be found.

Create Connected App Secret

Generate a secret for a connected app.

Secrets are tokens shared by Tableau and a custom application, and used to establish a trusted relationship.

A maximum of two secrets can be associated with a connected app. These secrets do not expire and remain valid until deleted. If a connected app has already reached its two secret maximum when another one is generated, an error is thrown.

URI

POST api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets

Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
client-id	The unique ID of the connected app.

Request Body

None

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

201

Response Body

The request returns details about the generated secret, including the secret value <value>.

Example response:

<tsResponse>
  <connectedApplicationSecret>
	<value>TO7/wkW+45U001IBtyNbtyIMYQ/GBM0XlRXqsgYqPlY=</value>
	<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
	<createdAt>2021-08-10T18:48:40Z</createdAt>
  </connectedApplicationSecret>
</tsResponse>

Version

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

The resource, POST /api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets, was added in version 3.17. The original resource, POST /api/api-version/sites/site-id/connected-applications/client-id/secrets, was deprecated in version 3.17 and will be retired in a future release.

Errors

HTTP status	error Code	Condition	Details
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
400	400144	Secret limit exceeded	The connected app has already reached its two secret maximum.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404041	Connected app not found	The requested connected app could not be found.
404	404042	Secret not found	The requested secret for the connected app could not be found.

Create Data Driven Alert

Create a data driven alert (DDA) for a view with a single data axis.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
400	403165	DDA creation failed	A data driven alert could not be created because there is a missing value in the request body.
401	401002	Unauthorized Access	The user does not have permissions to create a data driven alert. Causes may include: authentication token provided in the request header was invalid or has expired; the user does not have administrator, creator, or explorer permissions; the user does not have permissions to view the sheet.
403	403164	DDA not enabled	Data driven alerts are not enabled for the site, or the user visibility site setting is configured as limited.
404	404011	View not found	The view specified in the request could not be found.
404	409004	Request is malformed	A data driven alert could not be created because there is an unexpected value in the request body.

For more information, see Handling Errors.

Create Extracts for Embedded Data Sources in a Workbook

Create extracts for all embedded data sources of a workbook. Optionally, encrypt the extracts if the site and workbook using them are configured to allow it.

When you create an extract for a data source in a workbook, the extract is available only to the workbook and may have configuration specific to the workbook, such as hiding of unused fields.

You can create workbook extracts for both embedded and published data sources used by the workbook. When you create a workbook data source for a published data source, then refreshing the workbook extract will retrieve any changes to data from the published datasource, or from the published data source's extract if it is using one.

Note: This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

Create Group

Creates a group on Tableau Server or Tableau Cloud site.

If Tableau Server is configured to use Active Directory for authentication, this method can create a group and then import users from an Active Directory group.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

To add users to a group, call Add User To Group. To make changes to an existing group, call Update Group.

For Tableau Server, if you use the method to import users from an Active Directory, the import process can be performed immediately (synchronously) or as a background job (asynchronously).

Note: If Active Directory contains a large number of users, you should import them asynchronously; otherwise, the process can time out.

The Create Group response returns information in two ways: in the response header and in the response body. The ID of the new group is always returned as the value of the Location header. If you create a local group or import an Active Directory group (Tableau Server only) immediately, the response body contains the name and ID of the new group. If you import an Active Directory group (Tableau Server only) using a background process, the response body contains a <job> element that includes a job ID. You can use the job ID to check the status of the operation by calling Query Job.

Create Group Set

Creates a group set with a specified name.

Note: You can't use this method to populate the group set with groups. After you create a group set and its ID is available, you can add a group to the group set by calling Add Group to Group Set.

Create Identity Pool

Create an identity pool.

POST {server}/api/-/authn-service/identity-pools

view details

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.

Request Body

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

Attribute Values

label-category-name	The label category name. Required. Must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.)
label-category-description	The label category description. Required. Must be 1-500 characters in length.

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

HTTP status	error Code	Condition	Details
400	400189	Generic create label categories error	An unknown error occurred.
403	403004	Operation on resource unauthorized	You must be an administrator to create, update, or delete label values.
409	409004	Invalid parameter	The category name must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, the category name must be 1-24 characters long.) The category name, when stripped of spaces, dashes, and underscores, must not case insensitively match one of Tableau's built-in label categories names. The category description must be 1-500 characters in length.

Create metric

Creates a metric.

POST {server}/api/-/pulse/metrics

view details

Create metric definition

Creates a metric definition.

POST {server}/api/-/pulse/definitions

view details

Create OpenID Connect Configuration

Create the Tableau Cloud site's OpenID Connect (OIDC) configuration.

After you've configured OIDC authentication, you can use the Tableau Cloud's UI to test the configuration(Link opens in a new window) and add users(Link opens in a new window).

For more information about OIDC authentication in Tableau Cloud, see OpenID Connect(Link opens in a new window) in the Tableau Cloud Help.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.

Request Body

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

Attribute Values

label-value-name	The label value name. Required. If you specify an existing label value name, this method will update the label value. If you specify a label value name that's different than existing label value names, this method will create the label value. Required. Must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.)
label-value-category	The label value category. Required. If you're updating an existing label value, this must match the existing category for that label value.
label-value-description	The label value description. Required, but does not need to be different than the existing description. Must be 1-500 characters in length.

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

HTTP status	error Code	Condition	Details
401	4000173	Generic create label values error	An unknown error occurred.
403	403004	Operation on resource unauthorized	You must be a site or server administrator to create or update label values.
403	403157	Bad request	You may see this error if you try to create or update a label in the certification category.
409	409004	Invalid parameter	The label value name must be 1-128 characters long in Tableau Cloud. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.) The name, when stripped of spaces, dashes, and underscores, must not case insensitively match one of Tableau's built-in label value names. The category must match an existing category. You can't change the category on an existing label value. The description can't be empty or over 500 characters.

Create Project

Creates a project on the specified site. You can also create project hierarchies by creating a project under the specified parent project on the site. To make changes to an existing project, call Update Project.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Create Server Schedule

Creates a new server schedule on Tableau Server.
For Tableau Cloud, see Create Cloud Extract Refresh Task and Create subscription.

Schedules are not specific to sites. For more information, see Creating a Flow Schedule(Link opens in a new window), Extracts and Refresh Schedules(Link opens in a new window) and Create or Modify a Schedule(Link opens in a new window) in the Tableau Server documentation. Scheduling flows requires Tableau Prep Conductor to be enabled on your Tableau Server. For more information, see Enable Tableau Prep Conductor(Link opens in a new window).

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Create Site

Creates a site on Tableau Server. To make changes to an existing site, call Update Site. This method isn’t available for Tableau Cloud.

For more information, see Work with Sites(Link opens in a new window) and Add or Edit Sites(Link opens in a new window) in the Tableau Server documentation.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Create Subscription

Creates a new, unsuspended subscription to a view or workbook for a specific user on Tableau Server and Tableau Cloud. When a user is subscribed to the content, Tableau sends the content to the user in email on the schedule that you define.

For more information, see Subscribe to Views(Link opens in a new window) in the Tableau Server documentation.

Tableau Server and Tableau Cloud each have a different model for schedules and tasks. On Tableau Server, you create a schedule and add a task to it. On Tableau Cloud you create a task and define it's frequency. While the Create Subscription endpoint path and parameters are the same for both Server and Cloud, because the models are different, the request and response bodies are different.

• Tableau Server Request
• Tableau Cloud Request

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Create subscription

Creates a subscription to a specified metric for a specified user or group.

POST {server}/api/-/pulse/subscriptions

view details

Decrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).

Decrypts all extracts on a site.

Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

Delete a Webhook

Deletes the specified webhook.

Delete analytics extension connection from site

Deletes a specific analytics extension connection for an external service from a site.

DELETE {server}/api/-/settings/site/extensions/analytics/connections/{connection_luid}

view details

Delete ask data lens - Retired in API 3.22

---

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau GPT and Tableau Pulse are reimagining the data experience.

---

DELETE {server}/api/-/askdata/lenses/{lens_id}

view details

Delete Ask Data Lens Permission - Retired in API 3.22

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau AI and Tableau Pulse are reimagining the data experience(Link opens in a new window).

Deletes the specified permissions to the specified ask data lens for a user or group.

Delete Authentication Configuration

Delete an authentication instance.

DELETE {server}/api/-/authn-service/auth-configurations/{id}

view details

Delete Connected App

Permanently remove a connected app.

Deleting the connected app also deletes the secrets associated with the connected app. For more information about deleting a connected app, see one of the following: 

• For Tableau Server: Effects of deleting a connected app(Link opens in a new window)
• For Tableau Cloud: Effects of deleting a connected app(Link opens in a new window)

URI

DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id

Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
client-id	The unique ID of the connected app.

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

204

Response Body

None

Version

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

The resource, DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id, was added in version 3.17. The original resource, DELETE api/api-version/sites/site-id/connected-applications/client-id, was deprecated in version 3.17 and will be retired in a future release.

Errors

HTTP status	error Code	Condition	Details
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404041	Connected app not found	The requested connected app could not be found.

Delete Connected App Secret

Permanently remove a secret associated with a connected app.

For more information about deleting a connected app, see one of the following:

• For Tableau Server: Effects of deleting a secret(Link opens in a new window)
• For Tableau Cloud: Effects of deleting a secret(Link opens in a new window)

URI

DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id

Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
client-id	The unique ID of the connected app.
secret-id	The unique ID of the connected app secret.

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

204

Response Body

None

Version

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

The resource, DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id, was added in version 3.17. The original resource, DELETE api/api-version/sites/site-id/connected-applications/client-id/secrets/secret-id, was deprecated in version 3.17 and will be retired in a future release.

Errors

HTTP status	error Code	Condition	Details
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404041	Connected app not found	The requested connected app could not be found.
404	404042	Secret not found	The requested secret for the connected app could not be found.

Delete Custom View

Deletes the specified custom view.

Required scope for JWT authorization

Introduced in Tableau Cloud December 2022 (API 3.18) .

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.

tableau:views:update

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Delete Data Acceleration Task

Deletes a data acceleration task.

This method is not available for Tableau Cloud.

Starting in Tableau version 2022.1 (API v3.16), with the introduction of View Acceleration(Link opens in a new window), the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases resulting in error codes being returned.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
certification-luid	The unique ID of the data quality certification.

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

HTTP status	error Code	Condition	Details
400	400105	Generic data quality certification error	The data quality certification could not be deleted for some reason other than those specified in this table.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
indicator-id	The unique ID of the data quality certification.

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

content	The type of content or asset the data quality warning is attached to. To specify type, use one of the following values: database table datasource virtualconnection virtualconnectiontable
database-id	The unique ID of the database asset.
table-id	The unique ID of the table asset.
datasource-id	The unique ID of the data source content.
virtualconnection-id	The unique ID of the virtual connection.
virtualconnectiontable-id	The unique ID of the virtual connection table.

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

HTTP status	error Code	Condition	Details
400	400106	Generic data quality certification error	The data quality certifications could not be deleted for some reason other than those specified in this table.
404	404029	Content not found	The content does not exist.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
content-type	The type of asset that the data quality warning is being attached to. To specify the type, use: database table column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3) datasource flow virtualconnection virtualconnectiontable Types are not case sensitive.
content-luid	The LUID of the content (database, table, column, published data source, flow, virtual connection, or virtual connection table).

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
409	400106	Data quality warning delete error	An unknown error occurred and the data quality warning could not be deleted.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The requested asset could not be found.
404	404030	Data quality warning not found	The data quality warning for the requested asset could not be found.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
dataqualitywarning-id	The unique ID of the data quality warning.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400105	Data quality warning delete error	An unknown error occurred and the data quality warning could not be deleted.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The requested asset could not be found.
404	404030	Data quality warning not found	The data quality warning for the requested asset could not be found.

Delete Data Source

Deletes the specified data source from a site. When a data source is deleted, its associated data connection is also deleted. Workbooks that use the data source are not deleted, but they will no longer work properly.

Delete Data Source from Favorites

Deletes the specified data source from the user's favorites. If the specified data source is not a favorite, the operation has no effect.

Delete Data Source Permission

Removes the specified data source permission for the specified group or user.

Delete Data-Driven Alert

Deletes the specified data-driven alert from the specified site.

URI

DELETE /api/api-version/sites/site-id/dataAlerts/data-alert-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the specified data-driven alert.
data-alert-id	The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site.
database-luid	The LUID of the database asset.
user-luid	The LUID of the user to remove the permissions for.
group-luid	The LUID of the group to remove the permissions for.
capability-name	The explicit permissions capability to remove. Capabilities that can be removed are Read, Write, ChangePermissions, or ChangeHierarchy.
capability-mode	The permissions mode to remove. Modes that can be removed are Allow or Deny.

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

HTTP status	error Code	Condition	Details
400	400120	Bad request	Permissions could not be deleted because support for explicit permissions is available for database assets associated with published data sources only.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
403	403117	Database locked	Permissions for the database asset cannot be deleted because the database asset is locked.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
404	404031	Database not found	The requested database could not be found.
409	409045	Database error	An unknown database asset error occurred.
409	409051	Database update forbidden	A user without "write" permissions to the database asset attempted an update.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
database-luid	The LUID of the database asset.
user-luid	The LUID of the user to remove the default permission for.
group-id	The LUID of the group to remove the default permission for.
capability-name	The capability to remove the permissions for. Valid capabilities for databases are the following: Read (view) Write (edit) ChangePermissions (set permissions) ChangeHierarchy (move) For more information, see Permissions.
capability-mode	Allow to remove the allow permission, or Deny to remove the deny permission.

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

HTTP status	error Code	Condition	Details
400	400120	Bad request	Permissions could not be deleted because support for explicit permissions is available for database assets associated with published data sources only.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
403	403117	Database locked	Default permissions cannot be deleted because the database asset is locked.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
404	404031	Database not found	The requested database could not be found.
409	409045	Database error	An unknown database asset error occurred.
409	409051	Database update forbidden	A user without "write" permissions to the database asset attempted an update.

Delete Default Permission

Removes default permission rules for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also removes default permission rules for database or table resources in a project for a user or group. After removing default permission rules, new resources of the type you specify that are added to the project will no longer have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project.

Delete EAS

Delete a registered external authorization server (EAS).

URI

DELETE api/api-version/sites/site-id/connected-apps/external-authorization-servers/eas-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
eas-id	The unique ID of the registered EAS.

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

204

Response Body

None

Version

Errors

HTTP status	error Code	Condition	Details
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404047	EAS not found	The requested EAS could not be found.

Delete Extract Refresh Task

Deletes the specified extract refresh task on Tableau Server or Tableau Cloud.

Delete Extracts of Embedded Data Sources from a Workbook

Delete all extracts of embedded data sources in a workbook.

Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

Delete Flow

Deletes a flow. When a flow is deleted, its associated connections, the output and input steps, any associated scheduled tasks, and run history are also deleted.

Delete Flow from Favorites

Deletes the specified flow from the user's favorites. If the specified flow is not a favorite, the operation has no effect.

Delete Flow Permission

Deletes the specified permission from the specified flow for a group or user.

Delete Group

Deletes the group on a specific site. Deleting a group does not delete the users in group, but users are no longer members of the group. Any permissions that were previously assigned to the group no longer apply.

Note: You cannot delete the All Users group.

Delete Group Set

Deletes the group set on a specific site. Deleting a group set doesn’t delete the users in the group set, but users are no longer members of the group set. Any permissions that were previously assigned to the group set no longer apply.

Delete Identity Pool

Delete an identity pool.

DELETE {server}/api/-/authn-service/identity-pools/{uuid}

view details

Delete Identity Store

Delete an identity store.

DELETE {server}/api/-/authn-service/identity-stores/{id}

view details

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
label-luid	The unique LUID of the label asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	400105	Generic delete label error	An unknown error occurred. Confirm that the LUID in the URI is correct.
403	403004	Operation on resource unauthorized	Insufficient permissions to perform the operation.
409	409004	Invalid parameter	The URI does not contain a properly-formatted LUID.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
label-category-name	The label category name. URL encode the label category name (as it appears in the Tableau web interface) if it has spaces or non-alphanumeric characters in it.

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

HTTP status	error Code	Condition	Details
400	400191	Generic delete label category error	An unknown error occurred.
403	403004	Operation on resource unauthorized	You must be an administrator to create, update, or delete label values.
409	409004	Invalid parameter	The category name in the URI must exist. The category name can't be one of the built-in categories.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site.
category-list	(Optional) A comma-separated list of label value categories used to limit the label deletions to only the listed categories. See Data Labels in the REST API for information on label values and categories.

Request Body

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

Attribute Values

asset-type	The type of asset. Valid asset types are: database table column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3) datasource flow virtualconnection virtualconnectiontable
asset-luid	The asset LUID.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	400106	Generic delete labels error	An unknown error occurred.
403	403004	Operation on resource unauthorized	Insufficient permissions to perform the operation.
404	404029	Resource not found	The contentType and contentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrect contentType, an incorrect contentID, or both.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
label-value-name	The label value name. URL encode the label value name if it has spaces or non-alphanumeric characters in it.

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

HTTP status	error Code	Condition	Details
403	403004	Operation on resource unauthorized	You must be a site or server administrator to create or update label values.
409	409004	Invalid parameter	The label value name in the URI must exist. The label value name can't be one of the built-in labels, unless that label has a customized description (in which case, this method reverts the description to the built-in default).
401	4000173	Generic add labels to content error	An unknown error occurred.

Delete metric

Deletes a metric.

DELETE {server}/api/-/pulse/metrics/{metric_id}

view details

Delete Metric - Retired in API 3.22

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).

Deletes a specified metric from a site.

Delete metric definition

Deletes a metric definition.

DELETE {server}/api/-/pulse/definitions/{definition_id}

view details

Delete Project

Deletes the specified project on a specific site. When a project is deleted, all Tableau assets inside of it are also deleted, including assets like associated workbooks, data sources, project view options, and rights.

External assets, such as databases and tables, are not deleted. Starting in Tableau Cloud December 2022 / Server 2023.1, external assets from deleted projects are moved to the External Assets Default Project, and can also be found in External Assets. In Tableau Cloud October 2022 / Server 2022.3 and earlier, external assets are not moved to any other project, but can be found in External Assets.

Use this method with caution.

Delete Project from Favorites

Deletes the specified project from the user's favorites. If the specified project is not a favorite, the operation has no effect.

Delete Project Permission

Removes the specified project permission for the specified group or user.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
trigger-id	The unique ID of the quality warning trigger.

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

HTTP status	error Code	Condition	Details
400	400138	Generic quality warning trigger error	The quality warning trigger could not be deleted for some other reason than those specified below.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404037	Quality warning not found	The requested quality warning trigger was not found.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
content-type	The type of content the quality warning trigger has been applied to. In this case, use one of the following values: datasource flow These values are not case sensitive.
content-luid	The unique ID of the asset. This is the same as the content ID.

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

HTTP status	error Code	Condition	Details
400	400138	Generic quality warning trigger error	The quality warning trigger could not be deleted for some other reason than those specified below.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404037	Quality warning not found	The requested quality warning trigger was not found.
409	409004	Invalid parameter	One or more values in the request body are invalid.

Delete Server Schedule

Deletes the specified schedule on Tableau Server.
For Tableau Cloud, see Delete Extract Refresh Task and Delete Subscription.

Delete Server Session

Deletes a specified session. This method is not available for Tableau Cloud and is typically used in programmatic management of the life cycles of embedded Tableau sessions.

URI

DELETE api/api-version/sessions/session-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
session-id	The unique ID of the session to be deleted. A session's ID and other metadata can be queried from the Tableau Server Postgres repository. Reading the Postgres repository excessively can impact performance and that writing directly to the repository is not supported in any form. For more information, see Collect Data with the Tableau Server Repository and Tableau Server Postgres Data Dictionary.

Request Body

None.

Permissions

This method can only be called by server administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400105	Session delete error	An unknown error occurred and the session could not be deleted.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The requested asset could not be found.

Delete Site

Deletes the specified site.

You can specify the site to delete by using the site ID, the site name, or the content URL. You use the key query string parameter to indicate how you are specifying the site, as shown in the URIs.

Beginning in API version 3.18, you can delete a site asynchronously, which allows you to track the site deletion progress.

This method is not available for Tableau Cloud.

Note: You must have previously called the Sign In method and signed in to a site in order to delete the site. When you call this method, you must include the authentication token that you got back when you signed into the site.

Delete Subscription

Deletes the specified subscription on Tableau Server or Tableau Cloud.

Delete subscription

Deletes a specified subscription to a metric.

DELETE {server}/api/-/pulse/subscriptions/{id}

view details

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
table-luid	The LUID of the table asset.
user-luid	The LUID of the user to remove the permissions for.
group-luid	The LUID of the group to remove the permissions for.
capability-name	The explicit permissions capability to remove. Capabilities that can be removed are Read, Write, ChangePermissions, or ChangeHierarchy.
capability-mode	The permissions mode to remove. Modes that can be removed are Allow or Deny.

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

HTTP status	error Code	Condition	Details
400	400120	Bad request	Permissions could not be deleted because support for explicit permissions is available for table assets associated with published data sources only.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
403	403117	Database locked	Permissions for the table asset cannot be deleted because the database asset is locked.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
409	409051	Database update forbidden	A user without "write" permissions to the database asset attempted an update.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
column-id	The unique ID of the column asset.
tag-name	The keyword text of the tag.

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

HTTP status	error Code	Condition	Details
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404007	Tag not found	The tag does not exist.
409	409062	Generic database tag error	The tag or tags could not be deleted (or added) for some other reason than those specified in this table.
409	409066	Column not found	The column asset does not exist.

Delete Tag from Data Source

Deletes a tag from the specified data source.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
database-id	The unique ID of the database asset.
tag-name	The keyword text of the tag.

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

HTTP status	error Code	Condition	Details
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404007	Tag not found	The tag does not exist.
404	404031	Database not found	The database asset does not exist.
409	409048	Generic database tag error	The tag or tags could not be deleted (or added) for some other reason than those specified above.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.
tag-name	The keyword text of the tag.

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

HTTP status	error Code	Condition	Details
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404007	Tag not found	The tag does not exist.
404	404032	Table not found	The table asset does not exist.
409	409055	Generic database tag error	The tag or tags could not be deleted (or added) for some other reason than those specified above.

Delete Tag from View

Deletes a tag from the specified view.

Delete Tag from Virtual Connection

Deletes a tag from a virtual connection.

Delete Tag from Workbook

Deletes a tag from the specified workbook.

Delete the Extract from a Data Source

Delete the extract of a data source in a site.

Delete User from Data-Driven Alert

Removes a specified user from the recipients list for a data-driven alert.

Delete Users from Site with CSV

Creates a job to remove a list of users, specified in a .csv file, from a site.

The .csv file should comply with the rules described in one of the following topics:

• For Tableau Cloud - CSV Import File Guidelines(Link opens in a new window)

• For Tableau Server - CSV Import File Guidelines(Link opens in a new window)

Delete View from Favorites

Deletes the specified view from user's favorites. If the specified view is not a favorite, the operation has no effect.

Delete View Permission

Deletes permission to the specified view (also known as a sheet) for a Tableau Server user or group.

Delete Virtual Connection

Deletes a virtual connection.

Response Body

None

Errors

HTTP status	error Code	Condition	Details
403	403004	User not authorized.	Check to make sure the user has the required permissions.
404	404049	Virtual connection not found	Check the virtual connection LUID.
409	409122	Generic error	An unknown error occurred.

For more information, see Handling Errors.

Delete Virtual Connection Permission

Removes the specified virtual connection permission for the specified group or user.

Delete Workbook

Deletes a workbook. When a workbook is deleted, all of its assets are also deleted, including associated views, data connections, and so on.

Delete Workbook from Favorites

Deletes a workbook from a user's favorites. If the specified workbook is not a favorite of the specified user, this call has no effect.

Delete Workbook Permission

Deletes the specified permission from the specified workbook for a group or user.

Disallow dashboard extension on site - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

DELETE {server}/api/-/settings/site/extensions/dashboard/safeListItems/{safe_list_item_luid}

view details

Download Data Source

Downloads a data source in .tdsx format.

Download Data Source Encrypted Keychain

Gets an encrypted version of the embedded credentials from the data source. These credentials can only be migrated to the linked destination Tableau Cloud or Tableau Server.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404004	Data source not found	The data source ID in the URI doesn't correspond to an existing data source.
405	405000	Invalid request method	Request type was not POST.

For more information, see Handling Errors.

Download Data Source Revision

Downloads a specific version of a data source prior to the current one in .tdsx format. To down load the current version of a data source use the Download Data Source method.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

Download Flow

Downloads a flow in .tfl or .tflx format.

Download User Credentials

Gets credentials for a user who is being migrated to another Tableau Cloud or Tableau Server site.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404002	User not found	The user ID in the URI doesn't correspond to an existing user.
405	405000	Invalid request method	Request type was not POST.

For more information, see Handling Errors.

Download View Crosstab Excel

Downloads an Excel (.xlsx) file containing crosstab data from a view that the user has permission to access in a workbook. If a crosstab is exported from a dashboard, data from only the first view in the dashboard will appear in the .xlsx file. Downloads of data from story dashboards are not supported at this time.

If you make multiple requests for an .xlsx, subsequent calls return a cached version of the file. This means that the returned .xlsx might not include the latest changes to the workbook. To decrease the amount of time that a workbook is cached, use the maxAge parameter.

Note the data exported is at a summary level only. Detail level data is only available as a download option in the user interface.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

Download Virtual Connection

Downloads a JSON-representation of a virtual connection.

The response body contains the project LUID, owner LUID, and a content element (for XML output) or content property (for JSON output) containing the virtual connection schema rendered as JSON.

If the response is XML, the content element is unescaped JSON.

If the response is JSON, the content property is escaped JSON.

Errors

HTTP status	error Code	Condition	Details
400	400200	Generic error	An unknown error occurred.
403	403174	User not authorized.	Check to make sure the user has the required permissions.
404	404049	Virtual connection not found	Check the virtual connection LUID.

For more information, see Handling Errors.

Download Virtual Connection Revision

Downloads a JSON-representation of an earlier revision of a virtual connection.

The response body contains the project LUID, owner LUID, and a content element (for XML output) or content property (for JSON output) containing the virtual connection schema rendered as JSON.

If the response is XML, the content element is unescaped JSON.

If the response is JSON, the content property is escaped JSON.

Errors

HTTP status	error Code	Condition	Details
400	400200	Generic error	An unknown error occurred. Check to make sure the revision number is a revision and not the active virtual connection.
403	403174	User not authorized.	Check to make sure the user has the required permissions.
404	404049	Virtual connection not found	Check the virtual connection LUID. Check that the revision number exists.

For more information, see Handling Errors.

Download Workbook

Downloads a workbook in .twb or .twbx format.

Security note: Content in .twb or .twbx files downloaded using this method is stored in plain text. All data, including filter values that may give semantic clues to the data, will be readable by anyone who opens the files.

Download Workbook Encrypted Keychain

Gets an encrypted version of the embedded credentials from the workbook. These credentials can only be migrated to the linked destination Tableau Cloud or Tableau Server.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not POST.

For more information, see Handling Errors.

Download Workbook PDF

Downloads a .pdf containing images of the sheets that the user has permission to view in a workbook. Download Images/PDF permissions must be enabled for the workbook (true by default). If Show sheets in tabs is not selected for the workbook, only the default tab will appear in the .pdf file.

If you make multiple requests for a PDF, subsequent calls return a cached version of the file. This means that the returned PDF might not include the latest changes to the workbook. To decrease the amount of time that a workbook is cached, use the maxAge parameter.

Download Workbook PowerPoint

Downloads a PowerPoint (.pptx) file containing slides with images of the sheets that the user has permission to view in a workbook. Download Images/PDF permissions must be enabled for the workbook (true by default). If Show sheets in tabs is not selected for the workbook, only the default tab will appear in the .pptx file.

If you make multiple requests for a .pptx, subsequent calls return a cached version of the file. This means that the returned .pptx might not include the latest changes to the workbook. To decrease the amount of time that a workbook is cached, use the maxAge parameter.

Download Workbook Revision

Downloads a specific version of a workbook in .twb or .twbx format.

Note: This method is available only if version history is enabled for the specified site. For more information, see

Security note: Content in .twb or .twbx files downloaded using this method is stored in plain text. All data, including filter values that may give semantic clues to the data, will be readable by anyone who opens the files.

Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

Enable or disable analytics extensions on server

Enables or disables analytics extensions on a server.

PUT {server}/api/-/settings/server/extensions/analytics

view details

Encrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).

Encrypts all extracts on a site.

Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

Generate current metric value insight bundle

Generates a bundle the current aggregated value for each metric.

POST {server}/api/-/pulse/insights/ban

view details

Generate detail insight bundle

Generates a detail insight bundle.

POST {server}/api/-/pulse/insights/detail

view details

Generate springboard insight bundle

Generates a springboard insight bundle.

POST {server}/api/-/pulse/insights/springboard

view details

Get a Webhook

Returns information about the specified webhook.

Get allowed dashboard extension on site - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

GET {server}/api/-/settings/site/extensions/dashboard/safeListItems/{safe_list_item_luid}

view details

Get analytics extension details

Get the details of a specified analytics extension connection to an external service.

GET {server}/api/-/settings/site/extensions/analytics/connections/{connection_luid}

view details

Get ask data lens - Retired in API 3.22

---

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau GPT and Tableau Pulse are reimagining the data experience.

---

GET {server}/api/-/askdata/lenses/{lens_id}

view details

Get batch content usage statistics

Gets usage statistics for multiple content items. The batch of can include multiple content types.

POST {server}/api/-/content/usage-stats

view details

Get blocked dashboard extension on server - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

GET {server}/api/-/settings/server/extensions/dashboard/blockListItems/{block_list_item_luid}

view details

Get Connected App

Query a connected app by its ID.

URI

GET api/api-version/sites/site-id/connected-apps/direct-trust/client-id

Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
client-id	The unique ID of the connected app.

Request Body

None

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

200

Response Body

Example response:

<tsResponse>
  <connectedApplications>
	<connectedApplication>
	  <secret>
		<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
		<createdAt>2021-08-10T18:48:40Z</createdAt>
	  </secret>
	  <name>ConnectedApp_MyCo</name>
	  <enabled>true</enabled>
	  <clientId>ac95d175-c844-4779-9d58-415e01fe7dab</clientId>
	  <projectIds>
		<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
		<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
	  </projectIds>
	  <createdAt>2021-08-10T18:46:30Z</createdAt>
	  <unrestrictedEmbedding>false</unrestrictedEmbedding>
	</connectedApplication>
  <connectedApplications>
</tsResponse>

Version

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

The resource, GET api/api-version/sites/site-id/connected-apps/direct-trust/client-id, was added in version 3.17. The original resource, GET api/api-version/sites/site-id/connected-applications/client-id, was deprecated in version 3.17 and will be retired in a future release.

Errors

HTTP status	error Code	Condition	Details
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404041	Connected app not found	The requested connected app could not be found.

Get Connected App Secret

Query a connected app secret and the token value using the connected app's ID.

Secrets are tokens shared by Tableau and a custom application, and used to establish a trusted relationship.

A maximum of two secrets can be associated with a connected app. These secrets do not expire and remain valid until deleted.

URI

GET api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id

Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
client-id	The unique ID of the connected app.
secret-id	The unique ID of the connected app secret.

Request Body

None

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

200

Response Body

Example response:

<tsResponse>
  <connectedApplicationSecret>
	<value>TO7/wkW+45U001IBtyNbtyIMYQ/GBM0XlRXqsgYqPlY=</value>
	<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
	<createdAt>2021-08-10T18:48:40Z</createdAt>
  </connectedApplicationSecret>
</tsResponse>

Version

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

The resource, GET api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id, was added in version 3.17. The original resource, GET api/api-version/sites/site-id/connected-applications/client-id/secrets/secret-id, was deprecated in version 3.17 and will be retired in a future release.

Errors

HTTP status	error Code	Condition	Details
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404041	Connected app not found	The requested connected app could not be found.
404	404042	Secret not found	The requested secret for the connected app could not be found.

Get content search results

Searches across all supported content types for objects relevant to the search expression specified in the querystring of the request URI.

GET {server}/api/-/search

view details

Get Content Suggestions

Returns a specified number of suggestions for auto-completion of user input as they type. You can specify content types of suggestions and prioritize recently viewed content.

GET {server}/api/-/suggestions

view details

Get current analytics extension for workbook

Gets basic details, including connection type and name, of the analytics extension connection to an external service that the specified workbook is currently using.

GET {server}/api/-/settings/site/extensions/analytics/workbooks/{workbook_luid}/selected_connection

view details

Get Current Server Session

Returns details of the current session of Tableau Server.

Get Custom View

Gets the details of a specified custom view.

Required scope for JWT authorization

Introduced in Tableau Cloud December 2022 (API 3.18) .

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.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Get Custom View Image

Downloads a .png format image file of a specified custom view.

Required scope for JWT authorization

Introduced in Tableau Cloud December 2022 (API 3.18) .

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.

tableau:views:download

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Get Data Acceleration Report for a Site

Returns a report about data acceleration for the site. It lets you compare page load times for before and after data acceleration is enabled.

This method is not available for Tableau Cloud.

Starting in Tableau version 2022.1 (API v3.16), with the introduction of View Acceleration(Link opens in a new window), the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases resulting in error codes being returned.

Get Data Acceleration Tasks in a Site

Returns a list of data acceleration tasks for the site.

This method is not available for Tableau Cloud.

Starting in Tableau version 2022.1 (API v3.16), with the introduction of View Acceleration(Link opens in a new window), the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases resulting in error codes being returned.

Get Data Source Revisions

Returns a list of revision information (history) for the specified data source.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

To get a specific version of the data source from revision history, use the Download Data Source Revision method.

Get Data-Driven Alert

Returns details on a specified data-driven alert, including the recipients of the alert.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

Request Body

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

Attribute Values

embedded	(Optional) Indicates whether the database is embedded or not. Use "false" if the database is not embedded and "true" if the database is embedded. For more information about embedded databases (and tables), see one of the following topics:  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).
datasource-name	(Optional) The data source name that can be found in the XML of the data source (.tds or .tdsx) or workbook (.tws or .twbx) file.
datasource-format	(Optional) The format of the data source that can be found in the XML of the data source (.tds or .tdsx) or workbook (.tws or .twbx) file.
encoded_xml	This is the encoded version of the connection element (<connection>...</connection>) in the XML of the data source (.tds or .tdsx) or workbook (.tws or .twbx) file. Before you begin, make a copy of the data source or workbook file to ensure you have a backup. To encode the connection element, you can use a free online base64 encoding tool or write a simple script. Note: Make sure there are no extra spaces between the connection element's start and end tags. For example, after encoding the connection element, the generated encoding should look like <base64xml>...</base64xml>. If the generated encoding looks like <base64xml> ... </base64xml>, you might see an invalid parameter (409097) error.

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

HTTP status	error Code	Condition	Details
409	409095	Generic asset retrieval error	The database and table information could not be queried for some reason other than those specified in this table.
409	409096	Unauthorized operation	Insufficient permissions to perform the operation.
409	409097	Invalid parameter	One or more values in the request body are invalid.

Get Embedding Settings for a Site

Returns the current embedding settings for a specific site.

Embedding settings can be used to restrict embedding Tableau views to only certain domains. This setting impacts all embedding scenarios including, Tableau Javascript API v2, Embedding API v3, and the embed code from the share dialog. For more information, see the Tableau Site Settings for Embedding topic in the Tableau Embedding v3 Help.

Beginning in version 2023.2 (June 2023) for Tableau Cloud and in version 2023.3 for Tableau Server, this setting might impact embedding scenarios that use Tableau connected apps. For more information, see the “Control where content can be embedded(Link opens in a new window)” section in the connected apps topic in the Tableau Cloud Help.

Get enabled state of analytics extensions on server

Gets the enabled/disabled state of analytics extensions on a server.

GET {server}/api/-/settings/server/extensions/analytics

view details

Get enabled state of analytics extensions on site

Gets the enabled/disabled state of analytics extensions on a site.

GET {server}/api/-/settings/site/extensions/analytics

view details

Get Extract Refresh Task

Returns information about the specified extract refresh task.

This method shows you information about the scheduled task for the data source extract or a published workbook that connects to the data extract.

Note: This method doesn't work for scheduled tasks associated with virtual connection extracts.

Get Favorites for User

Returns a list of favorite projects, data sources, views, workbooks, and flows for a user.

Get Flow Run

Gets a flow run.

Get Flow Run Task

Returns information about the specified flow run task. This method shows you information about the scheduled task for the flow.

Get Flow Run Tasks

Returns a list of scheduled flow tasks for the site.

Get Flow Runs

Get flow runs.

Get Group Set

Returns information about the specified group set including ID, name, and member groups.

Get Groups for a User

Gets a list of groups of which the specified user is a member.

Get Identity Pool

Get information about an identity pool.

GET {server}/api/-/authn-service/identity-pools/{uuid}

view details

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
label-luid	The unique LUID of the label asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	400103	Generic query label error	An unknown error occurred.
403	403004	Operation on resource unauthorized	Insufficient permissions to perform the operation.
404	404030	Label not found	The label LUID doesn't correspond to an existing project.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
category-list	(Optional) A comma-separated list of label value categories used to limit the labels shown to only the listed categories. See Data Labels in the REST API for information on label values and categories.

Request Body

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

Attribute Values

asset-type	The type of asset. Valid asset types are: database table column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3) datasource flow virtualconnection virtualconnectiontable
asset-luid	The asset LUID.

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.

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	400104	Generic delete label error	An unknown error occurred.
403	403004	Operation on resource unauthorized	Insufficient permissions to perform the operation.
404	404029	Resource not found	The contentType and contentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrect contentType, an incorrect contentID, or both.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
label-value-name	The label value name. URL encode the label value name if it has spaces or non-alphanumeric characters in it.

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

HTTP status	error Code	Condition	Details
400	4000171	Generic query label value error	An unknown error occurred.
404	404029	No label value matches the request parameter	Check the label value name in the URI. Remember to URL-encode non-alphanumeric characters.

Get Linked Task

Returns information about a specific linked task. This method shows you information about the scheduled linked task

Get Linked Tasks

Returns a list of scheduled linked tasks for a site.

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

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400192	Missing or incomplete payload	Make sure the request body is present and complete.
400	400193	Generic error	An unknown error occurred.
403	403004	Permission denied	Check permissions for the asset. Check the asset type and asset LUID.
403	403157	Feature disabled	This method is only available on Tableau Cloud with Tableau+.
404	404055	Asset not found	Can't find selected asset. Check the asset type and asset LUID.
409	409004	Invalid parameter	URI parameter may be incorrect. The suggestionType parameter is case sensitive, and must be description.

For more information, see Handling Errors.

Get metric

Gets the details of the specified metric.

GET {server}/api/-/pulse/metrics/{metric_id}

view details

Get Metric - Retired in API 3.22

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).

Returns the details of the specified metric.

Get Metric Data - Retired in API 3.22

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).

Returns the data for the specified metric as comma separated (CSV) format. The maximum number of rows returned is 10,000.

Get metric definition

Gets a metric definition and optionally metrics it contains.

GET {server}/api/-/pulse/definitions/{definition_id}

view details

Get Mobile Security Settings for Server

Gets the mobile security settings for the server.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The request is incomplete is malformed.
400	400174	Mobile security settings error	An uknown mobile security settings error has occured.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403004	Unauthorized Access	The user does not have the required administrtor permissions.
403	403157	Forbidden	Mobile security settings are not enabled on the server.

For more information, see Handling Errors.

Get Mobile Security Settings for Site

Gets the mobile security settings for the specified site.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The request is incomplete is malformed.
400	400174	Mobile security settings error	An uknown mobile security settings error has occured.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403004	Unauthorized Access	The user does not have the required administrtor permissions.
403	403157	Forbidden	Mobile security settings are not enabled on the server.

For more information, see Handling Errors.

Get OpenID Connect Configuration

Get details about the Tableau Cloud site's OpenID Connect (OIDC) configuration.

Get or create metric

Returns the details of a metric in a definition if it exists, or creates a new metric if it does not. Also returns 'true' if a new metric was created, or 'false' if it already existed.

POST {server}/api/-/pulse/metrics:getOrCreate

view details

Get Recently Viewed for Site

Gets the details of the views and workbooks on a site that have been most recently created, updated, or accessed by the signed in user. The 24 most recently viewed items are returned, though it may take some minutes after being viewed for an item to appear in the results.

Get Recommendations for Views

Gets a list of views that are recommended for a user. Using machine learning, the server will match preferences between similar users and recommend content that is most popular and recently viewed. When a recommended view is selected and not marked as hidden, it appears on the server Home and Recommendations pages.

Get Server Schedule

Returns detailed information about the specified server schedule on Tableau Server.

Not available for Tableau Cloud.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Get site entitlements

Returns entitlements available for a site. If entitlements are True, then Pulse premium features are enabled for the site.

GET {server}/api/-/pulse/entitlements

view details

Get Subscription

Returns information about the specified subscription.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Get subscription

Gets a specified subscription to a metric.

GET {server}/api/-/pulse/subscriptions/{id}

view details

Get usage statistics for content item

Gets the usage statistics for a Tableau content item, specified by LUID and content type, such as workbook, datasource, or flow.

GET {server}/api/-/content/usage-stats/{type}/{luid}

view details

Get User Notification Preferences

Returns the notification preferences for the specified site. You can filter by channel and notification type. For more information about notifications, see Manage Your Account Settings.

Get Users in Group

Gets a list of users in the specified group.

Get Users on Site

Returns the users associated with the specified site.

Get View

Gets the details of a specific view.

Get View by Path

Gets the details of all views in a site with a specified name.

Get Workbook

Returns information about the specified workbook, including information about views and tags.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Get Workbook Downgrade Info

Returns a list of the features that would be impacted, and the severity of the impact, when a workbook is exported as a downgraded version (for instance, exporting a v2019.3 workbook to a v10.5 version).

Get Workbook Revisions

Returns a list of revision information (history) for the specified workbook.

Note: This method is available only if version history is enabled for the specified site.

To get a specific version of the workbook from revision history, use the Download Workbook Revision method. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

Hide a Recommendation for a View

Hides a view from being recommended by the server by adding it to a list of views that are dismissed for a user. If hidden, a view will not be displayed on the server Home or Recommendation pages.

Import ask data lens - Retired in API 3.22

---

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau GPT and Tableau Pulse are reimagining the data experience.

---

POST {server}/api/-/askdata/lenses/import

view details

Import Users to Site from CSV

Creates a job to import the users listed in a specified .csv file to a site, and assign their roles and authorization settings.

The .csv file should comply with the rules described in one of the following topics:

• For Tableau Cloud - CSV Import File Guidelines(Link opens in a new window)

• For Tableau Server - CSV Import File Guidelines(Link opens in a new window)

URI

POST api/api-version/sites/site-id/users/import

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

Request Body

Because this method involves a file that is external to Tableau a multi-part request is required. For more information on multi-part requests, See Importing CSV files with Multipart Requests(Link opens in a new window).

--boundary-string
Content-Disposition: name="tableau_user_import"
Content-Type: file
path_to_csv
--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <user
    name="user-name"
	authSetting="auth-setting"
	idpConfigurationId="idp-configuraion-id" />
  <!--    more users    -->
</tsRequest>
--boundary-string--

A request-payload without user name or authSetting is valid, but must be present in the request in the form: <tsRequest><user /></tsRequest>.

Attribute Values

path-to-csv	The file path to the .csv list users to be imported.
user-name	(Optional) The name of the user. If the server uses local authentication, this can be any name. If you are using Active Directory authentication, or if you are using Tableau Cloud, there are specific requirements for the name. For Tableau Server: If Tableau Server uses Active Directory authentication, this must be the name of an existing user in Active Directory. If the user name is not unique across domains, you must include the domain as part of the user name (for example, example\Adam or adam@example.com). Note: Active Directory specifies a user name using two attributes: sAMAccountName and userPrincipalName (UPN) prefix. For most Active Directory users, these attributes are the same. By default, if you are adding a user from Active Directory, the name that you provide in the user-name is matched against the Active Directory sAMAccountName attribute, which becomes the name that the user signs in to Tableau Server with. Two exceptions are when the name that you provide: is longer than 20 characters; and includes an @ character. In these cases, Tableau imports the user using the Active Directory UPN. For more information, see User Naming Attributes(Link opens in a new window) on the MSDN site. For Tableau Cloud: The user-name is the email address that the user will use to sign in to Tableau Cloud. When you add a user to the site, Tableau Cloud sends an email invitation. The user can click the link in the invitation to sign in and update their full name and password.
auth-setting	(Optional) The authentication type for the user. Important: For Tableau Server, the authSetting attribute only applies when adding users to sites with site-specific SAML enabled settings. For Tableau Cloud, starting in API 3.24, multiple authentication configurations can be created and enabled. Therefore, use authSetting attribute to assign user authentication if only one authentication configuration exists on your site. If working with multiple authentication configurations on a site, use the idpConfigurationId attribute instead to assign user authentication. See idp-configuration-id. You can assign the following values for this attribute: SAML - The user signs in using the identity provider (IdP) configured for the site. For Tableau Cloud configuration, see Enable SAML Authentication on a Site(Link opens in a new window). For Tableau Server, see Configure Site-Specific SAML(Link opens in a new window). ServerDefault - The user signs in using the default authentication method that's set for the server. For Tableau Cloud ServerDefault corresponds to TableauID in authentication settings. For Tableau Server, the SAML(Link opens in a new window) Server help page describes default authentication options. OpenID - Tableau Cloud only The user signs in using Google, Salesforce, or their OpenID Connect provider credentials. In Tableau Cloud authentication settings, OpenID corresponds to Google, Salesforce, or OIDC configuration. TableauIDWithMFA - Tableau Cloud only: The user signs in using a combination of Tableau ID credentials and a registered verification method. For more information, see About multi-factor authentication and Tableau Cloud(Link opens in a new window). Assigning user auth settings with this method The request payload enables you to set auth settings for individual users, or all users in the .csv file. To prevent the payload from having any impact on auth settings, omit the name and authSetting attributes of the user object: <tsrequest><user /></tsrequest>. To set the default auth settings for all users being imported, omit the name attribute and specify the authSetting attribute of the user object: <tsRequest><user authSetting="OpenID"/><tsRequest> If the auth setting for a user is defined in both the imported .csv and in a request payload, the setting in the .csv will take precedence. If no auth setting is defined for a user in either the .csv and the request payload, then the default setting of the site is assigned.
idp-configuration-id	(Optional, Tableau Cloud only) Starting in API 3.24, multiple authentication configurations can be created and enabled at the same time. Include the idpConfigurationId to assign a specific authentication to a user. Include the idpConfigurationId attribute instead of the authSetting attribute to assign a specific authentication to a user, but not both. If idpConfigurationId or authSetting is not specified, then TableauIdWithMFA (or in some cases ServerDefault if that option is still available for your site) is the authentication assigned to the user. To find the idpConfigurationId value, use the List Authentication Configurations method. For more information, see Authentication(Link opens in a new window) in the Tableau Cloud Help.
isVerbose	Tableau Cloud only When set to false, this method only returns the top three errors in a batch of users. When set to true, the method displays a full list of errors during CSV upload. Available in REST API 3.22 (Tableau Cloud February 2024)

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

201

Version

REST API version 3.15 and later. For more information, see REST API and Resource Versions.

Response Body

<tsResponse>
  <job id="job-luid"
	mode="Asynchronous"
	type="UserImport"
	progress="progress-status-code"
	createdAt="created-date"
  finishCode="job-finish-status-code" />
</tsResponse>

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request payload is missing or incomplete, or contains malformed XML.
500	500000	Internal Server Error	The request could not be completed.

For more information, see Handling Errors.

Example

curl -X POST \
http://10.108.21.238//api/3.15/sites/8aa3291f-1b5a-4f52-a3be-6512661f574d/users/import \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'x-tableau-auth: AVjAKZb3SQimzoqyMmQXEg|9OSHQrwCXF83SIR2XCuDEK91AM7v3FZr' \
-F tableau_user_import=@users.csv \
-F 'request_payload=<tsRequest><user name="jdoe" idpConfigurationId="00000000-0000-0000-0000-0000000000"/></tsRequest>'

Response

<tsResponse>
<job id=">c8c2ee06-624f-4c11-a88d-8c9ec3b5813d"
  mode="Asynchronous"
  type="UserImport"
  progress="0"
  createdAt="2022-02-10T18:46:04Z"
  finishCode="1" />
</tsResponse>

Initiate File Upload

Initiates the upload process for a file. After the upload has been initiated, you call Append to File Upload to send individual blocks of the file to the server. When the complete file has been sent to the server, you call Publish Data Source, Publish Flow, or Publish Workbook to commit the upload.

Initiate File Upload returns an upload session ID that you pass to Append to File Upload or one of the publishing methods in order to identify the upload session.

The file size that is returned in the response is initialized to zero (0) megabytes, because no data has yet been loaded. Subsequent calls to Append to File Upload or the publishing APIs update this value.

For more information, see Publishing Resources.

List All Registered EAS

Get all external authorization servers (EASs) registered to a site.

URI

GET api/api-version/sites/site-id/connected-apps/external-authorization-servers

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

Request Body

None

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

200

Response Body

The request returns details about the EAS, including the following:

• <name>: The name of the connected app.

• <id>: The ID of the EAS.

• <issuerUrl>: The issuer URL of the EAS.

Example response:

<tsResponse>
   <externalAuthorizationServerList>
	<externalAuthorizationServer>
	   <name>External Authorization Server</name>
	   <id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
	   <issuerUrl>https://dev-57741098.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
	   <createdAt>2022-04-07T03:50:34Z</createdAt>
	</externalAuthorizationServer>
	<externalAuthorizationServer>
	   <name>EAS_1</name>
	   <id>be5f8262-6ae4-407c-9765-dfe5b37cb4b5</id>
	   <issuerUrl>https://dev-57741099.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
	   <createdAt>2022-05-15T13:00:34Z</createdAt>
	</externalAuthorizationServer>
   <externalAuthorizationServerList>
</tsResponse>

Version

Errors

HTTP status	error Code	Condition	Details
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.

List allowed dashboard extensions on site - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

GET {server}/api/-/settings/site/extensions/dashboard/safeListItems

view details

List analytics extension connections of workbook

Lists basic details of each analytics extension connection available for a specified workbook, including connection type and name.

GET {server}/api/-/settings/site/extensions/analytics/workbooks/{workbook_luid}/connections

view details

List analytics extension connections on site

Lists a site's analytics extension connections for external services.

GET {server}/api/-/settings/site/extensions/analytics/connections

view details

List Ask Data Lens Permissions

List all permissions configured for the specified ask data lens that the user has read capability for.

List ask data lenses in site - Retired in API 3.22

---

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau GPT and Tableau Pulse are reimagining the data experience.

---

GET {server}/api/-/askdata/lenses

view details

List Authentication Configurations

List all authentications configurations on the site.

For more information, see Authentication(Link opens in a new window) in the Tableau Cloud Help.

List Authentication Configurations

List information about all authentication instances.

GET {server}/api/-/authn-service/auth-configurations

view details

List blocked dashboard extensions on server - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

GET {server}/api/-/settings/server/extensions/dashboard/blockListItems

view details

List Connected Apps

Query all connected apps configured on a site.

URI

GET api/api-version/sites/site-id/connected-apps/direct-trust

Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

Request Body

None

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

200

Response Body

Example response:

<tsResponse>
  <connectedApplications>
	<connectedApplication>
	  <secret>
		<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
		<createdAt>2021-08-10T18:48:40Z</createdAt>
	  </secret>
	  <name>ConnectedApp_MyCo</name>
	  <enabled>true</enabled>
	  <clientId>ac95d175-c844-4779-9d58-415e01fe7dab</clientId>
	  <projectIds>
			<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
			<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
	  </projectIds>
	  <createdAt>2021-08-10T18:46:30Z</createdAt>
	  <domainSafelist>https://myco.com</domainSafelist>
	  <unrestrictedEmbedding>false</unrestrictedEmbedding>
	</connectedApplication>
	<connectedApplication>
	  <name>ConnectedApp_MyCo_stage1</name>
	  <enabled>false</enabled>
	  <clientId>7370df14-2741-43f9-bbdd-450f707530a0</clientId>
	  <projectIds>
			<projectId>11213e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
			<projectId>21234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
	  </projectIds>
	  <createdAt>2021-08-18T00:49:05Z</createdAt>
	  <unrestrictedEmbedding>true</unrestrictedEmbedding>
	</connectedApplication>
	<connectedApplication>
	  <name>ConnectedApp_MyCo_stage2</name>
	  <enabled>false</enabled>
	  <clientId>f1e57298-ecd4-46a9-b8d9-e5ab0bf76a82</clientId>
	  <createdAt>2021-08-18T00:54:30Z</createdAt>
	</connectedApplication>
  <connectedApplications>
</tsResponse>

Version

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

The resource, GET api/api-version/sites/site-id/connected-apps/direct-trust, was added in version 3.17. The original resource, GET api/api-version/sites/site-id/connected-applications, was deprecated in version 3.17 and will be retired in a future release.

Errors

HTTP status	error Code	Condition	Details
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404041	Connected app not found	The requested connected app could not be found.

List Custom Views

Gets a list of custom views on a site. The list includes details of each custom view.

Required scope for JWT authorization

Introduced in Tableau Server 2022.3 (API 3.17).

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

tableau:content:read

Permissions Details

For users who do not have administrator permissions:
The custom views present in the response to a request, and the details of those views that are displayed, depend on four things:

• Does the user have both Write and WebAuthoring permissions for the custom view?
• Is the user is the owner of the custom view
• Is there filter applied in the request parameters.
• Is site user visibility(Link opens in a new window) set to Limited?

The expected behavior in a response is as follows:

• If the request has no filter parameters: Users will see only custom views that they own.
• If the filter parameters include ownerId: Users will see only custom views that they own.
• If the filter parameters include viewId and/or workbookId, and don't include ownerId:
  • Users will see those custom views that they have Write and WebAuthoring permissions for.
  • If site user visibility in not set to Limited, the Users will see those custom views that are "public", meaning the value of their shared attribute is true.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

List dashboard extension settings of site - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

GET {server}/api/-/settings/site/extensions/dashboard

view details

List Data Source Permissions

Returns a list of permissions for a specific data source.

List Data-Driven Alerts on Site

Returns a list of data-driven alerts in use on the specified site.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
database-luid	The LUID of the database asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400120	Bad request	Permissions could not be returned because support for explicit permissions is available for database assets associated with published data sources only.
401	401000	Unauthorized access	No authorization credentials were provided.
400	400120	Bad request	Support for explicit permissions is available for database assets associated with published data sources only.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
404	404031	Database not found	The requested database could not be found.
409	409045	Database error	An unknown database asset error occurred.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
database-luid	The LUID of the database asset to set default permissions for.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400120	Bad request	Permissions could not be returned because support for explicit permissions is available for database assets associated with published data sources only.
404	404000	Site not found	The site LUID in the URI doesn't correspond to an existing site.
404	404003	Resource not found	The database LUID in the URI doesn't correspond to a database asset on the site.

List Default Permissions

Returns details of default permission rules granted to users and groups for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, this method can also return details of default permission rules granted to users and groups for database or table resources in a project.

List Extract Refresh Tasks in Server Schedule

Returns a list of the extract refresh tasks for a specified server schedule on the specified site on Tableau Server.

To get the ID of a schedule, call the List Server Schedules method. Note that the List Server Schedules method is global to the server; schedules are not specific to a site. Therefore, the URI for the List Server Schedules method does not include /sites/ or a site ID. However, individual scheduled tasks are specific to a site, and the URI for Query Extract Refresh Tasks must include the site information.

For more information about refresh tasks, see Manage Refresh Tasks(Link opens in a new window).

Not available for Tableau Cloud.

List Extract Refresh Tasks in Site

Returns a list of extract refresh tasks for the site.

This method shows you information about the scheduled tasks on the specified site for data source extracts or a published workbooks that connect to data extracts.

Note: Virtual connection extracts are listed in the response, but are not identified by an element the way that workbooks and published data sources are.

List Flow Permissions

Returns a list of permissions for the specific flow.

List followed metrics groups

Gets the user's followed metrics. Optionally metrics can be grouped by characteristics like datasource, and sorted. If no grouping and sorting is specified then returns are grouped and sorted by existing user preferences. If no user preferences exist or are specified, then metrics are grouped by most recently followed, in descending order. If metrics are grouped by most recently followed then they are returned in a single group, that is sorted by the specified, existing, or default order.

GET {server}/api/-/pulse/metrics:followedMetricsGroups

view details

List Group Sets

Lists all group sets matching optional filter and ordered by optional sort expression.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

List Identity Pools

List all identity pools.

GET {server}/api/-/authn-service/identity-pools

view details

List Identity Stores

List information about all identity store instances used to provision users.

GET {server}/api/-/authn-service/identity-stores

view details

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.

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

HTTP status	error Code	Condition	Details
400	400188	Generic get label category error	An unknown error occurred.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
category-list	(Optional) A comma-separated list of categories for limiting the list to only one category of labels. Valid categories are the built-in categories warning, certification, and sensitivity, or custom categories that an administrator created. (Custom categories were released with Tableau Cloud October 2023 and Tableau Server 2023.3.).
internal-flag	(Optional) A Boolean value that specifies if you want to return label values that are internal or aren't. (The data quality warnings that arise from extract refresh monitoring and flow run monitoring are internal labels.)

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

HTTP status	error Code	Condition	Details
400	400172	Generic query label values error	An unknown error occurred.
409	409004	Bad Request	One or more values in the request are invalid. If filtering by categories in the URI, check spelling of category. If filtering by isInternal in the URI, confirm you've provided a Boolean value.

List metric definitions

Lists the metric definitions configured for a site or, optionally, the details and definition for a specific metric.

GET {server}/api/-/pulse/definitions

view details

List Metrics for Site - Retired in API 3.22

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).

Returns the metrics configured for a site.

If the user is not an administrator, the method returns just the metrics for which the user has permissions.

List metrics in definition

Lists the metrics contained in a metric definition.

GET {server}/api/-/pulse/definitions/{definition_id}/metrics

view details

List Personal Access Tokens

List all personal access tokens (PATs). If you're a site admin, list PATs of a user when you are the site admin on all sites that the PAT owner is a member of.

This method is not available for Tableau Server.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403004	Forbidden	You can only list PATs that are yours.
403	403010	Cross-site access is forbidden	You're a site admin and can't list PATs when you're not the site admin for all sites the PAT owner is a member of.

For more information, see Handling Errors.

List Project Permissions

Returns information about the set of permissions allowed or denied for groups and users in a project.

List Registered EAS

Get an external authorization server (EAS) registered to a site.

URI

GET api/api-version/sites/site-id/connected-apps/external-authorization-servers/eas-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
eas-id	The unique ID of the registered EAS.

Request Body

None

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

200

Response Body

The request returns details about the EAS, including the following:

• <name>: The name of the connected app.

• <id>: The ID of the EAS.

• <issuerUrl>: The issuer URL of the EAS.

Example response:

<tsResponse>
   <externalAuthorizationServerList>
	<externalAuthorizationServer>
	   <name>EAS_1</name>
	   <id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
	   <issuerUrl>https://dev-57741098.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
	   <createdAt>2022-04-07T03:50:34Z</createdAt>
	</externalAuthorizationServer>
   <externalAuthorizationServerList>
</tsResponse>

Version

Errors

HTTP status	error Code	Condition	Details
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404047	EAS not found	The requested EAS could not be found.

List Server Active Directory Domains

Returns the details of the Active Directory domains that are in use on the server, including their full domain names, nicknames and IDs. If the server is configured to use local authentication, the command returns only the domain name local.

List Server Schedules

Returns a list of flows, extract and subscription server schedules on Tableau Server. For each schedule, the API returns the name, frequency, priority, and other information.

For more information about schedules, see Create or Modify a Schedule(Link opens in a new window).

Not available for Tableau Cloud.

List settings for dashboard extensions on server - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

GET {server}/api/-/settings/server/extensions/dashboard

view details

List Subscriptions

Returns a list of all the subscriptions on the specified site.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

List subscriptions

Lists the subscriptions to a specified metric and/or for a specified user.

GET {server}/api/-/pulse/subscriptions

view details

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400120	Bad request	Permissions could not be returned because support for explicit permissions is available for table assets associated with published data sources (not embedded data sources) only.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404032	Table not found	The requested table asset could not be found.
409	409052	Table error	An unknown table asset error occurred.
409	409053	Unknown table query error	An unknown error occurred and the table query could not complete.

List Tableau extensions server settings

Lists the settings for extensions of a server.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403000	Non-admin access forbidden	The client attempted to access an API method while signed in as a non-administrator user.
404	404000	Bad Request	The requested resource could not be found.
500	500000	Internal Server Error	The request could not be completed.

For more information, see Handling Errors.

List Tableau extensions site settings

Lists the settings for extensions of a site.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403000	Non-admin access forbidden	The client attempted to access an API method while signed in as a non-administrator user.
404	404000	Site Not Found	The site ID in the URI doesn't correspond to an existing site.
500	500000	Internal Server Error	The request could not be completed.

For more information, see Handling Errors.

List Users with Custom View as Default - Preview Release

Gets the list of users whose default view is the specified custom view.

Note: This method is currently available as a preview release in some regions. We will update this page when the method is generally available.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions.
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

List View Permissions

Returns a list of permissions for the specific view.

List Virtual Connection Database Connections

Returns information about database connections in the specified virtual connection

Errors

HTTP status	error Code	Condition	Details
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for virtual connections at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
401	401002	Unauthorized	The authentication token provided in the request header was invalid or has expired.
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

List Virtual Connection Permissions

Returns a list of permissions for a specific virtual connection.

List Virtual Connection Revisions

Lists revisions for a virtual connection.

The current property of a revision shows false for all revisions except for the currently active virtual connection revision, in which case it shows true.

Errors

HTTP status	error Code	Condition	Details
400	400058	Generic error	An unknown error occurred.
403	403054	User not authorized.	User doesn't have permissions to revisions on this virtual connection. Check the user's permissions.
403	403173	User not authorized.	User forbidden from listing virtual connection revisions. Check the user's permissions and site role.
403	403053	Revision history is disabled on the site.	Check the revision history setting.
404	404049	Virtual connection not found	Check the virtual connection LUID.

For more information, see Handling Errors.

List Virtual Connections

Returns a list of available virtual connection names and IDs.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for virtual connections at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
400	400008	Invalid parameter value	A parameter in the request body is missing or invalid.
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

List Webhooks

Returns a list of all the webhooks on the specified site.

List Workbook Permissions

Returns a list of permissions for the specific workbook.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site that contains the database.

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

project-luid	The LUID of the destination project.
location-type	The destination type. Currently, this value must be "PROJECT".
action-type	To move a database without moving its tables, this value must be "MoveDatabaseOnly".
database-luid	The LUID of the database.
asset-type	The type of asset being moved. Currently, this value must be "DATABASE".

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	409100	Invalid location type	The location element's type attribute must be "PROJECT".
400	409103	Invalid content type	The resource element's contentType attribute must be "DATABASE".
403	403004	Operation on resource unauthorized	Insufficient permissions or operation not allowed. Make sure Tableau Catalog is enabled.
403	403030	Permissions denied	The user does not have permission to move the database.
403	403112	Invalid Operation	The database may be embedded, and therefore cannot be moved.
403	403156	External assets can not be moved	The user does not have appropriate permissions.
404	404005	Project not found	The project LUID doesn't correspond to an existing project.
404	404031	Database not found	The database LUID doesn't correspond to an existing database. In a case where multiple databases were specified in the request, other database moves could have succeeded.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site that contains the table.

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

project-luid	The LUID of the destination project.
location-type	The destination type. Currently, this value must be "PROJECT".
table-luid	The LUID of the table.
asset-type	The type of asset being moved. Currently, this value must be "TABLE".

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	409100	Invalid location type	The location element's type attribute must be "PROJECT".
400	409103	Invalid content type	The resource element's contentType attribute must be "TABLE".
403	403004	Operation on resource unauthorized	Insufficient permissions or operation not allowed. Make sure Tableau Catalog is enabled.
403	403030	Permissions denied	The user does not have permission to move the table.
403	403112	Invalid Operation	The table may belong to an embedded database, and therefore cannot be moved.
403	403156	External assets can not be moved	The user does not have appropriate permissions.
404	404005	Project not found	The project LUID doesn't correspond to an existing project.
404	404032	Table not found	The table LUID doesn't correspond to an existing table. In a case where multiple tables were specified in the request, other table moves could have succeeded.

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

Organize Favorites

Move an item to organize a user's favorites.

Publish Data Source

Publishes a data source on the specified site, or appends data to an existing data source. To make other changes to a published data source, call Update Data Source or Update Data Source Connection.

This method is used in two ways. You can call it to publish a data source in a single request. To do that, you include the content of the data source file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make data source publication asynchronous.

Alternatively, you can publish a data source in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Data Source. In this case, Publish Data Source doesn't contain the file to publish.

Extracts with multiple table options
Starting in v2021.4, you can publish multi table Hyper extract files created using the Hyper API(Link opens in a new window). The data must include a single fact table(Link opens in a new window) containing the foreign keys that relate the tables to each other. The Hyper API infers the data object model, but does not perform any validation, such as referential integrity checking. If the Hyper API can’t infer the data object model of a Hyper extract, for instance, because there is more than one fact table, then attempting to publish the extract will fail. Prior to v2021.4, there was no way to append data to an extract with multiple tables using the REST API.

Data Sources stored locally
When you publish a data source from your local computer to the server, you must make sure that the server has all the components that are required in order for other users to see and interact with the data source. For example, if the data source is based on an Excel spreadsheet, you typically publish a packaged data source (.tdsx file) that contains all the components for that data source.

Working with Parquet files
- When publishing a Parquet file to a data source through a live-to-Hyper connection, the files are converted to Hyper files. You may want to publish a copy of your original Parquet file to retain that data in its native format.
- A data source with a live-to-Hyper connection to data in a Hyper file converted from Parquet can only have a single connection.
- When incrementally updating that data from that connection, using the Update Hyper in Data Source method, the Parquet file is not converted to Hyper.

For more information, see Publishing Resources.

Publish Flow

Publishes a flow on the specified site. To make other changes to a published flow, call Update Flow or Update Flow Connection.

You can do publish a flow in a single request or in multiple parts.

To publish a flow in a single request you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB.

To publish a flow in multiple parts, you initiate a file upload by calling Initiate File Upload(Link opens in a new window), send portions of the file to the server using Append to File Upload(Link opens in a new window), and then commit the upload by calling Publish Flow. In this case, Publish Flow doesn't contain the file to publish but the uploadSessionId and the flowType parameters are required.

Publish Virtual Connection

Publishes a downloaded JSON-representation of a virtual connection.

If the virtual connection does not exist, it will be published as a new virtual connection. If it already exists, and you've chosen to overwrite it, the virtual connection will be published as a revision of the existing virtual connection.

The virtual connection can be published as a draft or as an active virtual connection.

Errors

HTTP status	error Code	Condition	Details
400	400201	Generic error	An unknown error occurred.
403	403175	User not authorized.	Check to make sure the user has the required permissions.

For more information, see Handling Errors.

Publish Workbook

Publishes a workbook on the specified site. To make changes to a published workbook, call Update Workbook or Update Workbook Connection.

This method is used in two ways. You can call it to publish a workbook in a single request. To do that, you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make workbook publication asynchronous.

Alternatively, you can publish a workbook in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Workbook. In this case, Publish Workbook doesn't contain the file to publish.

Hiding views in a published workbook
To exclude certain sheets (also known as views) when you publish a workbook, configure them in the request as hidden. You cannot publish a workbook if all sheets are hidden.

Extracts with multiple table options
If an extract was stored using the multiple tables option, you can't append data to it.

Workbooks that rely on external local resources
When you publish a workbook from your local computer to the server, the publish process will fail if the workbook relies on resources (such as an Excel file or other data file) that are on your local computer but are not available on the server. (Unlike the publish process that is used in Tableau Desktop, the REST API publish process cannot automatically include extracts or other resources that the workbook uses.) If you are publishing a workbook that gets its data from a source on your computer, save the workbook as a packaged workbook (.twbx file) and publish the package so that workbook has all the resources it needs on the server.

For more information, see Publishing Resources.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
content-type	The type of content that the quality warning trigger has been applied to. To specify the type, use one of the following values: datasource flow These values are not case sensitive.
content-luid	The unique ID of the asset. This is the same as the content ID.

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

HTTP status	error Code	Condition	Details
400	400134	Generic quality warning trigger error	The quality warning triggers could not be queried for some other reason than those specified below.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404037	Quality warning not found	The requested quality warning trigger was not found.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.
column-id	The unique ID of the column asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
409	409059	Unknown column error	An unknown column asset error occurred.
409	409060	Unknown column query error	An unknown error occurred and the column query could not complete.
409	409066	Column not found	The requested column asset could not be found.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
409	409059	Unknown column error	An unknown column asset error occurred.
409	409060	Unknown column query error	An unknown error occurred and the column query could not complete.
409	409066	Column not found	The requested column assets could not be found.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
certification-luid	The unique ID of the data quality certification.

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

HTTP status	error Code	Condition	Details
400	400103	Generic data quality certification error	The data quality certification could not be queried for some reason other than those specified in this table.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404030	Data quality indicator not found	The requested data quality certification was not found.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
content-type	The type of content the data quality certification has been applied to. To specify the type, use one of the following values: database table datasource virtualconnection virtualconnectiontable These values are not case sensitive.
content-luid	The LUID of the content (database, table, published data source, flow, virtual connection, or virtual connection table).

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

HTTP status	error Code	Condition	Details
400	400104	Generic data quality certification error	The data quality certification could not be queried for some reason other than those specified in this table.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404029	Data quality indicator not found	The requested data quality certification was not found.
409	409004	Invalid parameter	One or more values in the request body are invalid.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
content-type	The type of asset that the data quality warning is being attached to. To specify the type, use one of the following values: database table column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3) datasource flow virtualconnection virtualconnectiontable These values are not case sensitive.
content-luid	The LUID of the content (database, table, column, published data source, flow, virtual connection, or virtual connection table).

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400104	Unknown data quality warning query error	An unknown error occurred and the data quality warning query could not complete.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The requested asset could not be found.
404	404030	Data quality warning not found	The data quality warning for the requested asset could not be found.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
dataqualitywarning-id	The unique ID of the data quality warning.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400103	Unknown data quality warning query error	An unknown error occurred and the data quality warning query could not complete.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404030	Data quality warning not found	The data quality warning for the requested asset could not be found.

Query Data Source

Returns information about the specified data source.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Data Source Connections

Returns a list of data connections for the specified data source.

Query Data Sources

Returns a list of published data sources on the specified site, with optional parameters for specifying the paging of large results. To get a list of data sources embedded in a workbook, use the Query Workbook Connections method.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Database

Get information about a database asset.

URI

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

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
database-luid	The LUID of the database asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
404	404031	Database not found	The requested database could not be found.
409	409045	Database error	An unknown database asset error occurred.
409	409046	Unknown database query error	An unknown error occurred and the database query could not complete.

Query Databases

Get information about all database assets for a site.

URI

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

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
404	404031	Database not found	The requested databases could not be found.
409	409045	Database error	An unknown database asset error occurred.
409	409046	Unknown database query error	An unknown error occurred and the database query could not complete.

Query Flow

Returns information about the specified flow, including information about the project, owner, and output steps.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Flow Connections

Returns a list of data connections for the specific flow.

Query Flows for a Site

Returns the flows on a site. If the user is not an administrator, the method returns just the flows that the user has permissions to view.

Query Flows for User

Returns the flows that the specified user owns in addition to those that the user has Read (view) permissions for.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Groups

Returns a list of groups on the specified site, with optional parameters for specifying the paging of large results.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Job

Returns status information about an asynchronous process that is tracked using a job. This method can be used to query jobs that are used to do the following:

• Import users from Active Directory (the result of a call to Create Group).
• Synchronize an existing Tableau Server group with Active Directory (the result of a call to Update Group).
• Run extract refresh tasks (the result of a call to Run Extract Refresh Task).
• Publish a workbook asynchronously (the result of a call to Publish Workbook).
• Run workbook or view subscriptions (the result of a call to Create Subscription or Update Subscription)
• Run a flow task (the result of a call to Run Flow Task)
• Status of Tableau Server site deletion (the result of a call to asynchronous Delete Site(Link opens in a new window) beginning API 3.18)
  Note: To query a site deletion job, the server administrator must be first signed into the default site (contentUrl=" ").

Query Jobs

Returns a list of active jobs on the specified site. To get details on a specific job, pass a job ID returned by this method to the Query Job method. To cancel an active job, pass a job ID returned by this method to the Cancel Job method.

Calls to this method can be filtered, as shown in the URI examples shown below. To learn more about filtering, see Filtering and Sorting in the REST API.

Query Projects

Returns a list of projects on the specified site, with optional parameters for specifying the paging of large results.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Quality Warning Trigger

Get information about a quality warning trigger.

URI

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

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
content-type	The type of content the quality warning trigger has been applied to. To specify the type, use on of the following values: datasource flow These values are not case sensitive.
trigger-id	The unique ID of the quality warning trigger.

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

HTTP status	error Code	Condition	Details
400	400134	Generic quality warning trigger error	The quality warning trigger could not be queried for some reason other than those specified below.
403	403004	Unauthorized operation	Insufficient permissions to perform the operation.
404	404037	Quality warning not found	The requested quality warning trigger was not found.
409	409004	Invalid parameter	One or more values in the request body are invalid.

Query Site

Returns information about the specified site, with the option to return information about the storage space and user count for the site.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

You can specify the site to delete by using the site ID, the site name, or the content URL. You use the key query string parameter to indicate how you are specifying the site, as shown in the URIs.

Note: You can only get site information for the site that you have signed in to.

Query Sites

Returns a list of the sites on the server that the caller of this method has access to. This method is not available for Tableau Cloud.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Table

Get information about a table asset.

URI

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

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404032	Table not found	The requested table could not be found.
409	409052	Unknown table error	An unknown table asset error occurred.
409	409053	Unknown table query error	An unknown error occurred and the table query could not complete.

Query Tables

Get information about all table assets for a site.

URI

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

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404032	Table not found	The requested tables could not be found.
409	409052	Unknown table error	An unknown table asset error occurred.
409	409053	Unknown table query error	An unknown error occurred and the table query could not complete.

Query User On Site

Returns information about the specified user.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query View Data

Returns a specified view rendered as data in comma-separated-value (CSV) format.

CSV data is provided in the response body, rather than as a download. If the request is for a dashboard, only data for the dashboard's first view is returned.

If you make multiple requests for a view's data, subsequent calls return a cached version of the data. This means that the returned data might not include the latest changes to the view. To decrease the amount of time that an data is cached, use the maxAge parameter.

For Tableau Cloud, concurrent requests to endpoints that start long-running jobs, including this one, are limited to 20 at a time. A 429 HTML reponse means that a request exceeded the limit and should be retried at a later time. (introduced September 2021).

Note the data exported is at a summary level only. Detail level data is only available as a download option in the user interface.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

Query View Image

Returns an image of the specified view.

If you make multiple requests for an image, subsequent calls return a cached version of the image. This means that the returned image might not include the latest changes to the view. To decrease the amount of time that an image is cached, use the maxAge parameter.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

Note: If you want to disable this endpoint, use TSM to set the sheet_image.enabled setting to false. For more information, see tsm configuration set options in the Tableau Server help.

Query View PDF

Returns a specified view rendered as a .pdf file.

If you make multiple requests for a PDF, subsequent calls return a cached version of the file. This means that the returned PDF might not include the latest changes to the view. To decrease the amount of time that an PDF is cached, use the maxAge parameter.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

Query View Preview Image

Returns the thumbnail image for the specified view.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Views for Site

Returns all the views for the specified site, optionally including usage statistics.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Views for Workbook

Returns all the views for the specified workbook, optionally including usage statistics.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Workbook Connections

Returns a list of data connections for the specific workbook.

Query Workbook Preview Image

Returns the thumbnail image as a PNG file for the specified workbook. Usually the image that is returned is for the first sheet in the workbook.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Query Workbooks for Site

Returns the workbooks on a site.

If the user is not an administrator, the method returns just the workbooks that the user has permissions to view.

Query Workbooks for User

Returns the workbooks that the specified user owns in addition to those that the user has Read (view) permissions for.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

Reencrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).

Reencrypt all extracts on a site with new encryption keys. If no site is specified, extracts on the default site will be reencrypted.

Note: Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

Register EAS

Create a connected app with OAuth 2.0 trust by registering an external authorization server (EAS) to a site.

You can register an external authorization server (EAS) to establish a trust relationship between your Tableau Server site or Tableau Cloud site and EAS using the OAuth 2.0 standard protocol. By establishing a trust relationship, you’re able to provide your users with a single sign-on (SSO) experience to Tableau content embedded in your custom applications or REST API authorization through an identity provider (IdP) you've already configured.

For more information, see one of the following:

• For Tableau Server: Register EAS to Enable SSO for Embedded Content(Link opens in a new window)
• For Tableau Cloud: Register EAS to Enable SSO for Embedded Content

URI

POST api/api-version/sites/site-id/connected-apps/external-authorization-servers

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.

Request Body

<tsRequest>
  <externalAuthorizationServer
	issuerUrl="URL" jwksUri="URI" name="name"/>
</tsRequest>

Attribute Values

A combination of attributes inside the <externalAuthorizationServer> element is valid, however issuerUrl is required.

URL	The entity id of your identity provider (IdP) or URL that uniquely identifies your IdP.
URI	(Optional) The JSON Web Key (JKWS) of the EAS.
name	(Optional) The name of the connected app. If the name attribute is not specified, the connected app name defaults to "External Authorization Server." This attribute is available starting from API version 3.22 (February 2024).

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

201

Response Body

The request returns details about the EAS, including the following:

• <name>: The name of the connected app.

• <id>: The ID of the EAS.

• <issuerUrl>: The issuer URL of the EAS.

• <jwksUri>: The JSON web key set (JWKS) of the EAS.

You can use the returned EAS ID (<id>) in Update EAS and Delete EAS requests.

Example response:

<tsResponse>
   <externalAuthorizationServer>
	<name>EAS_1</name>
	<id>50bdc8cd-1aa4-48fe-a0e7-68982d85daa8</id>
	<issuerUrl>https://dev-57741098.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
	<jwksUri>https://dev-57741098.okta.com/jwks.json</jwksUri>
	<createdAt>2022-04-07T03:50:34Z</createdAt>
   </externalAuthorizationServer>
</tsResponse>

Version

Errors

HTTP status	error Code	Condition	Details
400	400008	Issuer URL missing	The required issuer URL is missing from the request body.
400	400157	Unexpected EAS error	There was a unexpected error when creating the connected app.
400	400161	EAS limit exceeded	The site has reached its limit of EAS that can be registered or the external authorization server (EAS) ID is not in the correct format.
400	400194	Issuer URL already configured	Another connected app on the site is using the same issuer URL.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.
column-id	The unique ID of the column asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404032	Table not found	The requested table asset could not be found.
409	409059	Column error	An unknown column asset error occurred.
409	409061	Unknown column delete error	An unknown error occurred and the column could not be deleted.
409	409066	Column not found	The requested column asset could not be found.

Remove current analytics extension connection for workbook

Remove the currently used analytics extension connection to an external service from the specified workbook. The connection remains configured, and is available for further usage by the workbook.

DELETE {server}/api/-/settings/site/extensions/analytics/workbooks/{workbook_luid}/selected_connection

view details

Remove Data Source Revision

Removes a specific version of a data source from the specified site.

The content is removed, and the specified revision can no longer be downloaded using Download Data Source Revision. If you call Get Data Source Revisions, the revision that's been removed is listed with the attribute IsDeleted="true".

Note: Calling this method permanently removes the specified data source revision.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
database-id	The unique ID of the database asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404031	Database not found	The requested database could not be found.
409	409045	Database error	An unknown database asset error occurred.
409	409047	Database delete error	An unknown error occurred and the database asset could not be deleted.

Remove Group from Group Set

Removes a group from the specified group set.

Remove OpenID Connect Configuration

Disable and clear the Tableau Cloud site's OpenID Connect (OIDC) configuration.

Important: Before removing the OIDC configuration, make sure that users who are set to authenticate with OIDC are set to use a different authentication type. Users who are not set with a different authentication type before removing the OIDC configuration will not be able to sign in to Tableau Cloud.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404032	Table not found	The requested table asset could not be found.
409	409052	Table error	An unknown table asset error occurred.
409	409054	Unknown table delete error	An unknown error occurred and the table could not be deleted.

Remove User from Group

Removes a user from the specified group.

Beginning in API 3.21, you can bulk remove users from a group by specifying multiple user IDs.

Remove User from Identity Pool

Remove a user from a specified identity pool.

This method is not available for Tableau Cloud.

Remove User from Site

Removes a user from the specified site. The user will be deleted if they do not own any other assets other than subscriptions. If a user still owns content (assets) on Tableau Server, the user cannot be deleted unless the ownership is reassigned first.

You can’t remove a user from the server if they own content on any site on that server. You can remove a user from a site if they no longer own content on the site.

If a user is removed from all sites that the user is a member of, the user is deleted.

Remove Workbook Revision

Removes a specific version of a workbook from the specified site.

The content is removed, and the specified revision can no longer be downloaded using Download Workbook Revision. If you call Get Workbook Revisions, the revision that's been removed is listed with the attribute IsDeleted="true".

Note: Calling this method permanently removes the specified workbook revision.

Replace Content Permissions

Replaces existing permissions in the specified content. You can specify multiple sets of permissions using one call.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400009	Invalid capability	The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.
403	403004	Permissions setting forbidden	A non-administrator user called this method but doesn't have permission to set permissions on the workbook.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404002	User not found	A user ID in the request body doesn't correspond to an existing user.
404	404004	Data source not found	The data source ID in the URI doesn't correspond to an existing data source.
404	404005	Project not found	The project ID in the URI doesn't correspond to an existing project.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
404	404011	View not found	The view ID in the ID doesn't correspond to an existing view.
404	404012	Group not found	A group ID in the request body doesn't correspond to an existing group.
404	404013	Capability not found	The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value.
404	404027	Flow not found	The flow ID in the URI doesn't correspond to an existing flow.
405	405000	Invalid request method	The request type was not POST.

For more information, see Handling Errors.

Replace Project's Default Permissions

Replaces default permissions in the specified content. If Tableau Catalog is enabled, it also adds default permission rules for database or table resources in a project. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project. For more information, see Permissions(Link opens in a new window).

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400009	Invalid capability	The capability in the URI is invalid for a data source. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write. For detailed information about capabilities for each content type, see Capabilities.
400	400042	Malformed permissions qualifier	The request body includes a <workbook> or <datasource> element.
403	403004	Permissions setting forbidden	A non-administrator user called this method but doesn't have permission to add permissions on the project.
404	404000	Site not found	The site LUID in the URI doesn't correspond to an existing site.
404	404002	User not found	A user LUID in the request body as the grantee doesn't correspond to an existing user.
404	404005	Project not found	The project LUID in the URI doesn't correspond to an existing project.
404	404009	Project ID mismatch	A project LUID specified in the URI doesn’t match the project ID specified in the request body. (You don’t have to specify a project ID in the request body.)
404	404012	Group not found	A group LUID in the request body doesn't correspond to an existing group.
404	404013	Capability not found	The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405	405000	Invalid request method	The request type wasn’t POST.

For more information, see Handling Errors.

Revoke Administrator Personal Access Tokens

Revokes all personal access tokens(Link opens in a new window) (PATs) created by server administrators. This method is not available for Tableau Cloud.

Revoke Personal Access Token

Revoke a personal access token (PAT). If you're a site admin, you can revoke a users PAT owhen you are the site admin on all sites that the PAT owner is a member of.

This method is not available for Tableau Server.

Errors

HTTP status	error Code	Condition	Details
401	401002	Unauthorized Access	The credentials token provided in the request header was invalid or has expired.
403	403004	Forbidden	You can only revoke PATs that are yours.
403	403010	Cross-site access is forbidden	You're a site admin and can't revoke a PAT when you're not the site admin for all sites the PAT owner is a member of.
404	404051	Personal access token not found	The PAT couldn't be revoked because it does not exist.
405	405000	Not supported	This error can occur for the following reasons: The URI contains an incorrect PAT name or the PAT name is missing The request type is not DELETE

For more information, see Handling Errors.

Run Extract Refresh Task

Runs the specified extract refresh task.

Note: This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

This method runs the scheduled task for the data source extract or the published workbook that connects to the data extract. You must first schedule the task for the extract refresh. You can do this using the Create Schedule method to create the task. To get information about the extract refresh task, use the Get Extract Refresh Tasks method, which returns the extractRefresh ID that you use as the task-id.

Note: This method doesn't work for scheduled tasks associated with virtual connection extracts.

The method adds the refresh task to the backgrounder queue. Depending upon the backgrounder load, the task might not run immediately. The method returns information about the backgrounder job responsible for running the extract refresh task, including a job id that can be used with the Query Job method to query the status of the extract refresh.

An extract refresh task can be initiated by a REST API call, a tabcmd command, or a job calling the task on a schedule. A REST request to start a refresh task will fail if the task has been put in the task queue in any of these ways, or is already in progress.

Run Flow Now

Runs the specified flow.

This method runs the specified flow with all the output steps if none are specified. If you want to run only a subset of output steps, you can specify one or more output steps using the output-ids by using the List Metrics for Site - Retired in API 3.22. The Run Flow Now method is the equivalent of selecting a flow using the Tableau Server UI, and then selecting Run Now from the menu.

A flow task can be initiated by a REST API call, a tabcmd command, or a job calling the task on a schedule. A REST request to start a flow task will often fail if the task has been put in the task queue in any of these ways, or is already in progress. Running the flow for a suspended task using Run Flow Now will resume the task job.

Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

 

Run Flow Task

Runs the specified flow run task.

Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

This method runs the scheduled task for the flow. You must first schedule the task for the flow. You can do this using the Create Schedule(Link opens in a new window) method to create the task. The Run Flow task requires you to provide a task id. To get the task-id, use the Get Flow Run Tasks method, which returns the flowRun ID. The value of the flowRun ID is what you use as the task-id.

The method adds the flow run task to the backgrounder queue. Depending upon the backgrounder load, the task might not run immediately. The method returns information about the backgrounder job responsible for running the flow run task, including a job id that can be used with the Query Job method to query the status of the flow run.

A flow task can be initiated by a REST API call, a tabcmd command, or a job calling the task on a schedule. A REST request to start a flow task will often fail if the task has been put in the task queue in any of these ways, or is already in progress. If your request results in an error code 403102, it means that there is already a scheduled task for this within a very close time period (seconds). In this case, if the task is currently in a suspended state, it will resume.

Run Linked Task Now

Runs the specified linked task.

This method runs the specified linked task with all the steps. Depending on the setting that the task was created with, the linked task will stop at a step on failure or continue to the next step. For more information, see schedule linked tasks.

Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

Server Info

Returns the version of Tableau Server and the supported version of the REST API.

Set Custom View as Default for Users - Preview release

Sets the specified custom for as the default view for up to 100 specified users. Success or failure for each user is reported in the response body.

Note: This method is currently available as a preview release in some regions. We will update this page when the method is generally available.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions.
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Sign In

Signs you in as a user on the specified site on Tableau Server or Tableau Cloud.

This call returns a credentials token that you use in subsequent calls to Tableau Server or Tableau Cloud. Typically, a credentials token is valid for 240 minutes on Tableau Server, and 120 minutes on Tableau Cloud. With administrator permissions on Tableau Server, you can change this timeout by using the tsm configuration set(Link opens in a new window) command and setting the wgserver.session.idle_limit option.

In addition, if you are a Tableau Server administrator, you can use your username and password to sign in and impersonate a specific user. You might use impersonation in order to double check or troubleshoot the impact of permissions settings for that user.

For more information about authentication, see Signing In and Signing Out (Authentication).

Sign Out

Signs you out of the current session. This call invalidates the authentication token that is created by a call to Sign In.

Note: Beginning in API 3.20 (June 2023) for Tableau Cloud and API 3.21 (Tableau 2023.3) for Tableau Server, the Sign Out (and Sign In) method is supported by JWT authorization but does not require a scope to use. For more information, see JWT.

Switch Site

Switches you onto another site without having to provide a user name and password again.

This method allows an authenticated user to switch sites that they have access to. When you call this method, you must provide the current authorization token as the value of the X-Tableau-Auth header. Using the current authentication token, the method signs you in as a user on the site specified in the request payload. The method returns a new authentication token and invalidates the old one. You have the permissions of the user associated with the authorization token. By default, the token is good for 240 minutes. (You can specify a different timeout value for the token by calling the tsm configuration set command to change the wgserver.session.idle_limit setting.)

Note This method is not available on Tableau Cloud.

Test a Webhook

Tests the specified webhook. Sends an empty payload to the configured destination URL of the webhook and returns the response from the server. This is useful for testing, to ensure that things are being sent from Tableau and received back as expected.

Unblock dashboard extension on server - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

DELETE {server}/api/-/settings/server/extensions/dashboard/blockListItems/{block_list_item_luid}

view details

Unhide a Recommendation for a View

Unhides a view from being recommended by the server by removing it from the list of views that are dimissed for a user. If the unhidden view meets the criteria for being recommended, then it will be displayed on the server Home or Recommendation pages.

Update a Webhook

Modify the properties of an existing webhook.

Update analytics extension connection of site

Updates the details of specified analytics extension connection for an external service to a site.

PUT {server}/api/-/settings/site/extensions/analytics/connections/{connection_luid}

view details

Update analytics extension for workbook

Updates the analytics extension connection to external service currently used by a workbook.

PUT {server}/api/-/settings/site/extensions/analytics/workbooks/{workbook_luid}/selected_connection

view details

Update Authentication Configuration

Update an authentication instance.

PUT {server}/api/-/authn-service/auth-configurations/{id}

view details

Update Cloud Extract Refresh Task

Updates a custom schedule for an extract refresh task on Tableau Cloud.
For Tableau Server, see Update server schedule.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403004	Unauthorized Access	The user is not authorized to make this request.
404	404026	Task not found	The task for the extract refresh could not be found.
409	409004	invalid parameter value	The request is malformed or contains an invalid or missing schedule or interval parameter value. When the difference between start and end times are not increments of one hour, this error will result.

For more information, see Handling 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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.
column-id	The unique ID of the column asset.

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.

new-description-value

(Optional) Custom text to describe the column.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404032	Table not found	The requested table asset could not be found.
409	409052	Column error	An unknown table asset error occurred.
409	409057	Column update error	An unknown error occurred and the table asset could not be updated.
409	409058	Column update forbidden	A user without "write" permissions to the table asset attempted an update.
409	409066	Column not found	The requested column asset could not be found.

Update Connected App

Update a connected app.

URI

PUT api/api-version/sites/site-id/connected-apps/direct-trust/client-id

Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
client-id	The unique ID of the connected app.

Request Body

For Tableau Cloud and Tableau Server using API 3.23 or later

<tsRequest>
  <connectedApplication
		name="name"
		enabled="enabled"
		domainSafelist="domainSafelist"
		unrestrictedEmbedding="unrestrictedEmbedding">
				<projectIds>
					<projectId>project_id</projectId>
					<projectId>project_id</projectId>
					<projectId>project_id</projectId>
				</projectIds>
  <connectedApplication />
</tsRequest>

For Tableau Server (or Tableau Cloud) using API 3.21 or earlier

<tsRequest>
  <connectedApplication
		name="name"
		enabled="enabled"
		projectId="project_id" domainSafelist="domainSafelist"
		unrestrictedEmbedding="unrestricedEmbedding" />
</tsRequest>

Attribute Values

Any combination of attributes inside the <connectedApplication> element is valid.

name	(Optional) The new name of the connected app.
enabled	(Optional) Controls whether the connected app is enabled or not. Value can be "true" or "false". If the state is not specified, the connected app is set to "false" and not enabled by default.
project_id	(Optional, embedding workflows only) The ID of the project that the connected app's access level is scoped to. To get the project ID, see Query Projects. You can specify one project, multiple projects, and all projects on a site. Single project: For Tableau Cloud (using API 3.22 or later) and Tableau Server (using API 3.23 or later), to scope the connected app's access to one project, the recommended workflow is to specify the projectIds and projectId attributes and projectId value. For Tableau Server (or Tableau Cloud) using API 3.21 or earlier, specify the projectId attribute and its value. Multiple projects: Beginning with API 3.22 (February 2024) for Tableau Cloud and API 3.23 for Tableau Server, you can specify the projectIds and projectId attributes and projectId values to scope the connected app's access to multiple projects. All projects: For Tableau Cloud (using API 3.22 or later) and Tableau Server (using API 3.23 or later), specify the projectIds attribute and do not specify values. For example, <projectIds></projectIds>. For Tableau Server (or Tableau Cloud) using API 3.21 or earlier, specify the projectId attribute and leave its value empty. For example projectId="". Note: If the projectIds or projectId is not included in the request, the connected apps' access level is not updated. Note: The stand-alone projectId attribute will be retired in a future release so we recommend using projectIds attribute instead.
domainsafelist	(Optional, embedding workflows only ) A list of domains the connected app is allowed to be hosted. Specify one or more URLs, separated by spaces, using a format described in Domain allowlist rules(Link opens in a new window) in the Tableau Server Help or Domain allowlist rules(Link opens in a new window) in the Tableau Cloud Help. Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. For example: https://tableau.com https://myco.com:552 marketing.example.com
unrestrictedEmbedding	(Optional, embedding workflows only) Controls whether the connected app can be hosted on all domains. If "true" value is specified, the connected app can trust and connect to all domains. If "false" value is specified, the connected app can only be hosted on the domains specified in the <domainSafelist> attribute.

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

200

Response Body

Example response:

<tsResponse>
  <connectedApplication>
	<secret>
	  <id>d8a51b6c-bf70-4aaf-959b-93d2ba4897e6</id>
	  <createdAt>2021-08-18T17:59:11Z</createdAt>
	</secret>
	<name>ConnectedApp_MyCo</name>
	<enabled>true</enabled>
	<clientId>9486dee1-ca98-4144-b6e0-f5c555e64796</clientId>
	<projectIds>
		<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
		<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
	</projectIds>
	<createdAt>2021-08-18T17:48:03Z</createdAt>
	<unrestrictedEmbedding>true</unrestrictedEmbedding>
  </connectedApplication>
</tsResponse>

Notes:

• The request will return the secret associated with the connected app only if it has been previously generated. To get the secret value, see Query Connected App Secret.
• When the scope of the connected app's access is set to all projects, the request does not return the projectId attribute.

Version

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

The resource, PUT api/api-version/sites/site-id/connected-apps/direct-trust/client-id, was added in version 3.17. The original resource, PUT api/api-version/sites/site-id/connected-applications/client-id, was deprecated in API 3.17 and will be retired in a future release.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400109	Bad request	The request body can't be empty.
400	400143	Generic connected app error	The connected app could not be deleted for some other reason than those specified in this table.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404041	Connected app not found	The requested connected app could not be found.

Update Custom View

Changes the owner or name of an existing custom view.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Update dashboard extension settings of site - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

PUT {server}/api/-/settings/site/extensions/dashboard

view details

Update dashboard extensions settings of server - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

PUT {server}/api/-/settings/server/extensions/dashboard

view details

Update Data in Hyper Connection

Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from a live-to-Hyper connection, where the data source has multiple connections.

A live-to-Hyper connection has a Hyper or Parquet formatted file/database as the origin of its data.

For all connections to Parquet files, and for any data sources with a single connection generally, you can use the Update Data in Hyper Data Source method without specifying the connection-id.

A request for this method must include an upload-session-id for a Hyper file payload containing an upload of the most current data from the data source for your published live-to-Hyper data. Use Initiate File Upload(Link opens in a new window) and Append to File Upload(Link opens in a new window) methods to form the payload and acquire upload-session-id.

For details and examples, see Update Data in Published Live-to-Hyper Data Sources.

Note: While Hyper Update REST API methods make incremental changes much more efficient, multiple simultaneous update requests and large changes in large datasets can overwhelm Tableau server background processes. To mitigate this issue, Hyper Update requests are limited by the server configuration setting api.server.update_uploaded_file.max_size_in_mb. Starting in Tableau Server 2022.1 / Tableau Cloud March 2022, the default for this setting is 100MB. In previous versions, the limit was set to 10MB. Where heavy incremental update traffic is expected, we recommend you use a chunking strategy to limit the size of each update, and fine tune max_size_in_mb value to optimize performance for your exact conditions.

URI

PATCH /api/api-version/sites/site-id/datasources/datasource-id/connections/connection-iddata?uploadSessionId=upload-session-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the data source.
datasource-id	The ID of the data source to update.
connection-id	The ID of the connection. To determine what connections are available for a data source, call Query Data Source Connections.
upload-session-id	The upload session ID. A user-generated identifier that is unique to a request. If the server receives more than one request with the same ID within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests.

Request Body

This method supports only JSON content-type for the request body.

{"actions": [
	{"action": action-type",
		"source-schema": "source-schema-name",
		"source-table": "source-table-name",
		"target-schema": "target-schema-name",
		"target-table": "target-table-name",
		"condition": {conditional-declaration"}
		. . . more action definition . . .}
	}
	{. . . more actions . . .}
]} 

Attribute Values

actions-type	(Required) The definition of the operation(s) to perform on the data in the target hyper file.
source-schema-name	(Optional) The name of the source database schema for the data to be updated. A value is not required unless there are multiple schemas in the database.
source-table-name	(Required) The name of the source database table containing the data to be updated.
target-schema-name	(Optional) The name of the target hyper file schema of the data to be updated from the source database. A value is not required unless there are multiple schemas in the database.
target-table-name	(Required) The name of the table containing the data to be updated in the target hyper file.
condition	(Required for insert, upsert, and delete)A declaration that defines a comparison operation between source and target data or between source or target data and a user provided constant. For details and examples, see Update Data in Published Live-to-Hyper Data Sources.

An action is an operation to be performed on specified target data. Multiple different actions can be defined as a batch in a request. The supported actions are:

• insert - Inserts rows from a named source-table in your data source into a named target-table in your published Hyper. A simplified example is:

  {"action": "insert", "source-table": "added_users", "target-table": "current_users"}

• update – Updates existing tuples from a named source-table in your data source into a named target-table in your published Hyper. The tuples to be updated are defined in a condition declaration. A simplified example is:

  {"action": "update",
  	"target-table": "my_data",
  	"source-table": "uploaded_table",
  	"condition": {"op": "eq", "target-col": "row_id",
  	"source-col": "update_row_id"}
  }

• upsert - Updates a tuple inside the target-table, if such a tuple exists. If no such tuple exists, a new tuple will be inserted. The tuples to be updated are defined in a condition declaration. A simplified example is:

  {"action": "upsert",
  	"target-table": "my_data",
  	"source-table": "uploaded_table",
  	"condition": {"op": "gt", "target-col": "row_id",
  	"source-col": "update_row_id"}
  }

• replace – Deletes all tuples from a target-table and inserts all data from a source-table with a matching schema. A simplified example is:

  {"action": "replace", "source-table": "added_users",
  "target-table": "current_users"}

• delete – Deletes tuples from a target-table. The tuples to be deleted are defined in a condition declaration. A simplified example is:

  {"action": "delete",
  	"target-table": "my_extract_table",
  	"source-table": "deleted_row_id_table",
  	"condition": {"op": "gt", "target-col": "id",
  	"source-col": "deleted_id"}
  }

For more information, see Update Data in Published Live-to-Hyper Data Sources.

Permissions

The user calling this method must be the data source owner and must have the overwrite permission on it.

Request Header

In addition to the typical authentication token, the following fields must be specified as part of the request header:

• content-type: application/json - This endpoint accepts JSON only.

• RequestID - A user-generated identifier that uniquely identifies a request. If the server receives more than one request with the same id within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests, which prevents executing the same job more than once could be caused by network anomalies or client crashes.

Response Code

200

Response Body

The response body returns the job-id, which specifies the ID of the async job that will carry out the data operations described in the action batch. This returned "job-id" can be used to query the status of the update job(Link opens in a new window) or to cancel a scheduled job(Link opens in a new window).

(job-id: "scheduled-job-luid"}

Version

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

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed JSON.
400	400008	Invalid parameter value	A parameter in the request body is missing or invalid.
403	403062	Update data source multiple connections forbidden	A connection ID is required because the data source has multiple connections. Consider using Update Data in Hyper Connection to specify the connection. (This error does not apply to that Connection method)
403	403032	Update forbidden	A non-administrator user tried to update a data source, but the caller doesn't have Write permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404004	Data source not found	The data source LUID in the request body doesn't correspond to an existing data source.
404	404004	Data source not found	The data source ID in the URI doesn't correspond to an existing data source.
404	404008	Operation not supported	The operation requested is not supported, the source data for the connection must be a Hyper file/database.
404	404020	Connection not found	No resource was found for the specified connection and data source. (This error does not apply to Update Data in Hyper Data Source)
405	405000	Invalid request method	Request type was not PATCH.
409	409015	Data source name conflict	The data source name in the request already belongs to the specified site. For the purpose of uniqueness checks, data source names are case-insensitive.
409	409094	Data update job already exists	A data update job for the datasource is already queued or in progress.

For more information, see Handling Errors.

Update Data in Hyper Data Source

Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from a live-to-Hyper connection, where the data source has a single connection.

A live-to-Hyper connection has a Hyper or Parquet formatted file/database as the origin of its data.

For data sources with multiple connections, you can specify which to update using the Update Data in Hyper Data Source method.

A request for this method must include an upload-session-id for a Hyper file payload containing an upload of the most current data from the data source for your published live-to-Hyper data. Use Initiate File Upload(Link opens in a new window) and Append to File Upload(Link opens in a new window) methods to form the payload and acquire upload-session-id.

For details and examples, see Update Data in Published Live-to-Hyper Data Sources.

Note: While Hyper Update REST API methods make incremental changes much more efficient, multiple simultaneous update requests and large changes in large datasets can overwhelm Tableau server background processes. To mitigate this issue, Hyper Update requests are limited by the server configuration setting api.server.update_uploaded_file.max_size_in_mb. Starting in Tableau Server 2022.1 / Tableau Cloud March 2022, the default for this setting is 100MB. In previous versions, the limit was set to 10MB. Where heavy incremental update traffic is expected, we recommend you use a chunking strategy to limit the size of each update, and fine tune max_size_in_mb value to optimize performance for your exact conditions.

Working with Parquet files
- When publishing a Parquet file to a data source through a live-to-Hyper connection, the files are converted to Hyper files. You may want to publish a copy of your original Parquet file to retain that data in its native format.
- A data source with a live-to-Hyper connection to data in a Hyper file converted from Parquet can only have a single connection.
- When incrementally updating that data from that connection, using the Update Hyper in Data Source method, the Parquet file is not converted to Hyper.

URI

PATCH /api/api-version/sites/site-id/datasources/datasource-id/data?uploadSessionId=upload-session-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the data source.
datasource-id	The ID of the data source to update.
upload-session-id	The upload session ID. A user-generated identifier that is unique to a request. If the server receives more than one request with the same ID within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests.

Request Body

This method supports only JSON content-type for the request body.

{"actions": [
	{"action": action-type",
		"source-schema": "source-schema-name",
		"source-table": "source-table-name",
		"target-schema": "target-schema-name",
		"target-table": "target-table-name",
		"condition": {conditional-declaration"}
		. . . more action definition . . .}
	}
	{. . . more actions . . .}
]} 

Attribute Values

actions-type	(Required) The definition of the operation(s) to perform on the data in the target hyper file.
source-schema-name	(Optional) The name of the source database schema for the data to be updated. A value is not required unless there are multiple schemas in the database.
source-table-name	(Required) The name of the source database table containing the data to be updated.
target-schema-name	(Optional) The name of the target hyper file schema of the data to be updated from the source database. A value is not required unless there are multiple schemas in the database.
target-table-name	(Required) The name of the table containing the data to be updated in the target hyper file.
condition	(Required for insert, upsert, and delete)A declaration that defines a comparison operation between source and target data or between source or target data and a user provided constant. For details and examples, see Update Data in Published Live-to-Hyper Data Sources.

An action is an operation to be performed on specified target data. Multiple different actions can be defined as a batch in a request. The supported actions are:

• insert - Inserts rows from a named source-table in your data source into a named target-table in your published Hyper. A simplified example is:

  {"action": "insert", "source-table": "added_users", "target-table": "current_users"}

• update – Updates existing tuples from a named source-table in your data source into a named target-table in your published Hyper. The tuples to be updated are defined in a condition declaration. A simplified example is:

  {"action": "update",
  	"target-table": "my_data",
  	"source-table": "uploaded_table",
  	"condition": {"op": "eq", "target-col": "row_id",
  	"source-col": "update_row_id"}
  }

• upsert - Updates a tuple inside the target-table, if such a tuple exists. If no such tuple exists, a new tuple will be inserted. The tuples to be updated are defined in a condition declaration. A simplified example is:

  {"action": "upsert",
  	"target-table": "my_data",
  	"source-table": "uploaded_table",
  	"condition": {"op": "gt", "target-col": "row_id",
  	"source-col": "update_row_id"}
  }

• replace – Deletes all tuples from a target-table and inserts all data from a source-table with a matching schema. A simplified example is:

  {"action": "replace", "source-table": "added_users",
  "target-table": "current_users"}

• delete – Deletes tuples from a target-table. The tuples to be deleted are defined in a condition declaration. A simplified example is:

  {"action": "delete",
  	"target-table": "my_extract_table",
  	"source-table": "deleted_row_id_table",
  	"condition": {"op": "gt", "target-col": "id",
  	"source-col": "deleted_id"}
  }

For more information, see Update Data in Published Live-to-Hyper Data Sources.

Permissions

The user calling this method must be the data source owner and must have the overwrite permission on it.

Request Header

In addition to the typical authentication token, the following fields must be specified as part of the request header:

• content-type: application/json - This endpoint accepts JSON only.

• RequestID - A user-generated identifier that uniquely identifies a request. If the server receives more than one request with the same id within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be used to guarantee idempotency of requests, which prevents executing the same job more than once could be caused by network anomalies or client crashes.

Response Code

200

Response Body

The response body returns the job-id, which specifies the ID of the async job that will carry out the data operations described in the action batch. This returned "job-id" can be used to query the status of the update job(Link opens in a new window) or to cancel a scheduled job(Link opens in a new window).

(job-id: "scheduled-job-luid"}

Version

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

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed JSON.
400	400008	Invalid parameter value	A parameter in the request body is missing or invalid.
403	403062	Update data source multiple connections forbidden	A connection ID is required because the data source has multiple connections. Consider using Update Data in Hyper Connection to specify the connection. (This error does not apply to that Connection method)
403	403032	Update forbidden	A non-administrator user tried to update a data source, but the caller doesn't have Write permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404004	Data source not found	The data source LUID in the request body doesn't correspond to an existing data source.
404	404004	Data source not found	The data source ID in the URI doesn't correspond to an existing data source.
404	404008	Operation not supported	The operation requested is not supported, the source data for the connection must be a Hyper file/database.
404	404020	Connection not found	No resource was found for the specified connection and data source. (This error does not apply to Update Data in Hyper Data Source)
405	405000	Invalid request method	Request type was not PATCH.
409	409015	Data source name conflict	The data source name in the request already belongs to the specified site. For the purpose of uniqueness checks, data source names are case-insensitive.
409	409094	Data update job already exists	A data update job for the datasource is already queued or in progress.

For more information, see Handling 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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
dataqualitywarning-id	The unique ID of the data quality warning.

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.

type	Type of data quality warning to apply to the asset. To specify the type, use one of the following values: DEPRECATED WARNING STALE MAINTENANCE Note: In Tableau Server 2023.1 and earlier, SENSITIVE_DATA is another type of data quality warning. Starting in Tableau Cloud June 2023 and Tableau Server 2023.3, it's a sensitivity label instead. These values are not case sensitive.
status	(Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default.
message	(Optional. Was required in Tableau Server 2023.3 and earlier.) A custom message to accompany the data quality warning.
severity	(Optional) Enables high visibility for the data quality warning when set to "true". Values can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400109	Bad request	The request body can't be empty.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The requested asset could not be found.
404	404030	Data quality warning not found	The data quality warning for the requested asset could not be found.

Update Data Source

Updates the owner, project or certification status of the specified data source.

Update Data Source Connection

Updates the server address, port, username, or password for the specified data source connection.

Update Data Source Now

Runs an extract refresh on the specified data source.

Note: This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

This method runs an extract refresh for the specified data source, with no need to associate that extract refresh with a scheduled task. This method is the equivalent of selecting a data source using the Tableau Server UI, and then selecting Refresh Extracts from the menu (also known as a "manual refresh"), however, the REST method always runs a full refresh even if the refresh type is set to incremental. Similar to a manual refresh, if the extract is a .tde file, it will be converted to a .hyper file as a result of the refresh. To learn more about extract upgrades to the .hyper file format, see Extract Upgrade to .hyper Format.

Update Data-Driven Alert

Update one or more settings for the specified data-driven alert; including the alert subject, frequency, and owner.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site asset.
database-luid	The LUID of the database asset.

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.

certification-status	(Optional) Certify or remove certification by using the following: True False
certification-note	(Optional) Custom text to accompany the certification status.
new-description-value	(Optional) Custom text to describe the database asset.
new-content-permissions	(Optional) The new permissions setting for the database. You can specify one of the following: LockedToDatabase to lock permissions so that users cannot overwrite the default permissions set for the database asset. ManagedByOwner to allow users to manage permissions for the database asset used by the content that they own. The default permissions setting is ManagedByOwner. These values are case sensitive.
new-contact-luid	(Optional) The LUID of the Tableau Server or Tableau Cloud user to associate with the database asset.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site LUID in the URI doesn't correspond to an existing site.
404	404031	Database not found	The requested database could not be found.
409	409045	Database error	An unknown database asset error occurred.
409	409050	Database update error	An unknown error occurred and the database asset could not be updated.
409	409051	Database update forbidden	A user without "write" permissions to the database asset attempted an update.

Update EAS

Update a connected app with OAuth 2.0 trust.

URI

PUT api/api-version/sites/site-id/connected-apps/external-authorization-servers/eas-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
eas-id	The unique ID of the registered EAS.

Request Body

<tsRequest>
   <externalAuthorizationServer
	issuerUrl="URL"
	jwksUri="URI"
	name="name" />
</tsRequest>

Attribute Values

A combination of attributes inside the <externalAuthorizationServer> element is valid.

URL	(Optional) The entity id of your identity provider (IdP) or URL that uniquely identifies your IdP.
URI	(Optional) The JSON Web Key (JKWS) of the EAS.
name	(Optional) The name of the connected app. If the name attribute is not specified, the connected app name defaults to "External Authorization Server." This attribute is available starting from API version 3.22 (February 2024).

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

200

Response Body

The request returns details about the EAS, including the following:

• <name>: The name of the connected app.

• <id>: The ID of the EAS.

• <issuerUrl>: The issuer URL of the EAS.

• <jwksUri>: The JSON web key set (JWKS) of the EAS.

Example response:

<tsResponse>
   <externalAuthorizationServer>
	<name>EAS_2</name>
	<id>50bdc8cd-1aa4-48fe-a0e7-68982d85daa8</id>
	<issuerUrl>https://dev-57741098.okta.com/oauth2/aus3gd9kw7ixSfBKC5d7</issuerUrl>
	<jwksUri>https://dev-57741098.okta.com/jwks.json</jwksUri>
	<createdAt>2022-04-07T03:50:34Z</createdAt>
   </externalAuthorizationServer>
</tsResponse>

Version

Errors

HTTP status	error Code	Condition	Details
400	400008	Issuer URL missing	The request body contains an empty issuer URL attribute.
400	400157	Unexpected EAS error	There was an unexpected error when updating the connected app.
400	400194	Issuer URL already configured	Another connected app on the site is using the same issuer URL.
403	403000	Admin permissions required	A non-admin user called this method and doesn't have adequate permissions to perform the action.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404047	EAS not found	The requested EAS could not be found.

Update Embedding Settings for Site

Updates the embedding settings for a site. Embedding settings can be used to restrict embedding Tableau views to only certain domains.

This setting impacts all embedding scenarios including Tableau Javascript API v2, Embedding API v3, and the embed code from the share dialog. For more information, see Tableau Site Settings for Embedding(Link opens in a new window) in the Tableau Embedding API v3 Help.

Beginning in version 2023.2 (June 2023) for Tableau Cloud and in version 2023.3 for Tableau Server, this setting might impact embedding scenarios that use Tableau connected apps. For more information, see the "Control where content can be embedded" section in the connected apps topics in the Tableau Cloud Help(Link opens in a new window) or Tableau Server Help(Link opens in a new window).

URI

PUT /api/api-version/sites/site-id/settings/embedding

Path Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The ID of the site to update.

Request Body

<tsRequest>
  <site>
    <settings unrestrictedEmbedding="true/false"
     allowList="domain-list"/>
  </site>
</tsRequest>

Example request:

<tsRequest>
   <site>
     <settings unrestrictedEmbedding="false"
      allowList="mydomain.com"/>
    </site>
</tsRequest>

Request Attribute Values

unrestricted-embedding

(Optional) Specifies whether or not embedding is restricted. When the setting is set to true, Tableau views on this site can be embedded in any domain. When set to false, embedding is blocked for all domains, but you can allow embedding in certain domains using the allowList attribute.

allow-list

(Optional) Specifies the domains where Tableau views on this site can be embedded. Use this setting with unrestrictedEmbedding setting to restrict embedding functionality to only certain domains. Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. You can use wildcards in domain names and you can also list multiple domain names separated by spaces.

Permissions

Any Tableau Cloud or Tableau Server user can call this method.

Response Code

200

Response Body

<tsResponse>
  <site id="site-id"
	settings unrestrictedEmbedding="true-or-false"
	allowList="domain-allow-list/>
  </site>
</tsResponse>
        

Example response:

<tsResponse>
      <settings unrestrictedEmbedding="false"/>
	allowList="mydomain.com"
    </site>
</tsResponse>

Version

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

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403500	The user does not have permission	Tableau Cloud: Only site administrators can run this method.

Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d/settings/embedding" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-sembedding-settings.xml

Content of update-embedding-settings.xml:

<tsRequest>
   <site>
     <settings unrestrictedEmbedding="false"
      allowList="mydomain.com"/>
    </site>
</tsRequest>

For more information, see Handling Errors.

Update enabled state of analytics extensions on site

Enables or disables analytics extensions on a site.

PUT {server}/api/-/settings/site/extensions/analytics

view details

Update Flow

Updates the owner, project, of the specified flow.

Update Flow Connection

Updates the server address, port, username, or password for the specified flow connection. The connection can be an input or an output connection.

Update Group

Updates a group on a Tableau Server or Tableau Cloud site.

If Tableau Server or Tableau Cloud site is configured to use local authentication, the method lets you update the group name. If Tableau Server is configured to use Active Directory authentication, the method synchronizes the group with Active Directory.

During synchronization, the method updates the group and modifies the set of users in the group to be the same as those in Active Directory. Users in Active Directory that are not in the group on Tableau Server are added to the group, and users that are not in the Active Directory group are removed from the group. Users that are no longer in Active Directory at all are unlicensed.

If the update synchronizes with Active Directory, Tableau Server can perform the update either immediately (synchronously) or by using a background job (asynchronously). If Active Directory contains a large number of users, you should perform the synchronization process as a background job so that the process doesn't time out. By default, synchronizing with Active Directory is performed immediately (synchronously).

Update Group Set

Updates a group set name on a Tableau Server or Tableau Cloud site.

Update Identity Pool

Update information about an identity pool.

PUT {server}/api/-/authn-service/identity-pools/{uuid}

view details

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
label-luid	The unique LUID of the label asset.

Request Body

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

Attribute Values

label-value-name	(Optional) The label value name. You cannot change the category when updating a label. Choosing a label value name that's associated with a different category causes an error. See Data Labels in the REST API for a list of built-in label values and categories. Choosing a monitoring quality warning value (extract_refresh_failure or flow_run_failure) causes an error.
label-message	(Optional) The message text for the label. In the web interface, this is reflected as a certification note or a data quality warning message.
active-flag	(Optional) Boolean. If set to true, the label becomes active. If set to false, the label becomes inactive.  If omitted, the default is true.
elevated-flag	(Optional) Boolean. If set to true, the label becomes elevated. If set to false, the label becomes not elevated.  If omitted, the default is false.

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400103	Generic query label error	An unknown error occurred.
400	400109	Missing payload	The request body is missing a label element.
403	403004	Invalid parameter	Operation on resource unauthorized
404	404030	Label not found	The label LUID doesn't correspond to an existing project.
409	409004	Invalid parameter	One or more values in the request body are invalid, or you are trying to change the label value to one from a different category. This error can also occur if you try to create or change a monitoring quality warning (label values extract_refresh_failure and flow_run_failure).

Update Label Category

Updates 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

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

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
label-category-name	The label category name. URL encode the label category name (as it appears in the Tableau web interface) if it has spaces or non-alphanumeric characters in it.

Request Body

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

Attribute Values

label-category-name	The label category name. Required, but not does not have to be different from the existing name. Must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.)
label-category-description	The label category description. Required, but not does not have to be different from the existing description. Must be 1-500 characters in length.

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"
    description="label-category-description"/>
</tsResponse>

Errors

HTTP status	error Code	Condition	Details
400	400190	Generic update label categories error	An unknown error occurred.
403	403004	Operation on resource unauthorized	You must be an administrator to create, update, or delete label values.
409	409004	Invalid parameter	The label value name in the URI must exist. URL encode the label category name (as it appears in the Tableau web interface) if it has spaces or non-alphanumeric characters in it. The category name must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, the category name must be 1-24 characters long.) The category name, when stripped of spaces, dashes, and underscores, must not case insensitively match one of Tableau's built-in label categories names. The category description must be 1-500 characters in length.

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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.

Request Body

<tsRequest>
  <contentList>
    <content contentType="asset-type" id="asset-luid" />
    <!-- ... additional content elements ... -->
  </contentList>
  <label
      value="label-value-name"
      message="label-message"
      active="active-flag"
      elevated="elevated-flag" />
</tsRequest>

Attribute Values

asset-type	The type of asset. Valid asset types are: database table column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3) datasource flow virtualconnection virtualconnectiontable
asset-luid	The asset LUID.
label-value-name	The label value name. The built-in label value names are: certification warning deprecated stale maintenance sensitive _data You can also use custom label value names that an administrator creates. (Custom label values were released with Tableau Cloud June 2023 and Tableau Server 2023.3.) 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. See Data Labels in the REST API for a list of built-in label values and categories. Choosing a monitoring quality warning value (extract_refresh_failure or flow_run_failure) causes an error.
label-message	(Optional. Was required in Tableau Server 2023.3 and earlier.) The message text for the label. In the web interface, this is reflected as a certification note or a data quality warning message.
active-flag	(Optional) Boolean. If set to true, the label becomes active. If set to false, the label becomes inactive.  If omitted, the default is true.
elevated-flag	(Optional) Boolean. If set to true, the label becomes elevated. If set to false, the label becomes not elevated.  If omitted, the default is false.

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

Version

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

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>

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

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400108	Missing payload	The request body is missing all content and/or all label elements.
400	400109	Generic add labels to content error	An unknown error occurred.
403	403004	Operation on resource unauthorized	Insufficient permissions to perform the operation.
404	404029	Resource not found	The contentType and contentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrect contentType, an incorrect contentID, or both.
409	409004	Invalid parameter	One or more values in the request body are invalid, or one of the required attributes (active or elevated) is missing. This error can also occur if you try to create or change a monitoring quality warning (label values extract_refresh_failure and flow_run_failure).

Update labelValue

Updates a label value.

Note: You can update an existing label value using either this method or the Create or Update labelValue method. If you want to change the name of an existing label value, use this 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/label-value-name

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-luid	The unique LUID of the site asset.
label-value-name	The label value name. URL encode the label value name if it has spaces or non-alphanumeric characters in it.

Request Body

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

Attribute Values

label-value-name	The label value name. If the label value name is different than the one in the URI parameter, the label value name is changed to match the one in the request body. Required. Must be 1-128 characters long. (Must be 1-24 characters long in Tableau Server 2023.3 and earlier.)
label-value-category	The label value category. Required. You can't change the label value category, so this will always match the label value's existing category.
label-value-description	The label value description. Must be 1-500 characters in length.

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

HTTP status	error Code	Condition	Details
401	4000173	Generic create label values error	An unknown error occurred.
403	403004	Operation on resource unauthorized	You must be a site or server administrator to create or update label values.
404	403157	Bad request	You may see this error if you try to create or update a label in the certification category.
409	409004	Invalid parameter	The label value name in the URI must exist. The updated label value name must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, the updated label value name must be 1-24 characters long.) The updated name, when stripped of spaces, dashes, and underscores, must not case insensitively match one of Tableau's built-in label value names. The category must match an existing category. You can't change the category on an existing label value. The description can't be empty or over 500 characters.

Update metric

Updates the specification of a metric.

PATCH {server}/api/-/pulse/metrics/{metric_id}

view details

Update Metric - Retired in API 3.22

Retired in API 3.22 (Cloud February 2024 / Server 2024.2)

In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).

Updates the owner, project, suspended status, or name of the specified metric.

Update metric definition

Updates a metric definition.

PATCH {server}/api/-/pulse/definitions/{definition_id}

view details

Update Mobile Security Settings for Site

Updates the mobile security sections for a specified site.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing, incomplete, or is malformed XML. Invalid values for enabled, iosConfig, androidConfig, severity, or enabled attributes are possible causes.
400	400174	Mobile security settings error	An uknown mobile security settings error has occured.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403004	Unauthorized Access	The user does not have the required administrtor permissions.
403	403157	Forbidden	Mobile security settings are not enabled on the server.
409	409004	Invalid setting	A mobile security setting enabled, name or other value is missing or malformed.

For more information, see Handling 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

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
trigger-id	The unique ID of the monitoring quality warning.

Request Body

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

Attribute Values

type	Type of monitoring quality warning. To specify the type, use one of the following values: EXTRACT_REFRESH FLOW_RUN These values are not case sensitive.
status	Monitoring status. Values can be "true" or "false". If set to "true", the data source is monitored for extract refresh failures or the flow is monitored for flow run failures). If an extract refresh or flow run failure occurs, the specified data quality warning is attached to the data source or flow (depending on type). The data quality warning is removed when the extract refresh or flow run is successful. For more information about monitoring quality warnings, see the monitoring quality warning section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.
message	(Optional) A custom message for the data quality warning.
severity	High visibility status of the data quality warning. Values can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

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

HTTP status	error Code	Condition	Details
400	400137	Generic quality warning trigger error	The monitoring quality warning could not be updated for some other reason than those specified below.
403	403004	Unauthorized operation.	Insufficient permissions to perform the operation.
409	409004	Invalid parameter	One or more values in the request body are invalid.

Update OpenID Connect Configuration

Update the Tableau Cloud site's OpenID Connect (OIDC) configuration.

Update Project

Updates the name, description, or project hierarchy of the specified project. You can create or update project hierarchies by specifying a parent project for the project that you are updating using this method.

Update Server Active Directory Domain

Changes the nickname or full domain name of an Active Directory domain on the server. This method is not available on Tableau Cloud.

A domain nickname, also called short name, is the Windows NetBIOS domain name. You can modify the nickname for any domain the server is using.

In general, you can modify the full domain name for any domain except the one that you used to sign in. However, if the user name that you are currently signed in with exists in both the current domain and the new domain, you can modify the full name for the current domain. For information about how to enable access for users from multiple domains, see Support for multiple domains(Link opens in a new window).

If the domain is local, it's names cannot be changed.

URI

PUT /api/api-version/domains/domain-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
domain-id	The integer ID of the of the Active Directory domain being updated. Find a domain's ID using List Server Active Directory Domains.

Request Body

<tsRequest>
  <domain name="new-domain-name"
  shortName="new-domain-nickname" />
</tsRequest>
      

Attribute Values

Any combination of attributes is valid. If no attributes or nested elements are included, no update is made.

new-domain-name	A new full domain name you are using to replace the existing one.
new-domain-nickname	A new domain nickname you are using to replace the existing one.

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

Example response:

<tsRequest>
  <domain id="domain-id-int"
    name="domain-name"
    shortName="domain-nickname" />
</tsRequest>
      

Version

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

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404032	Resource not found	The requested domain ID in the URI doesn't correspond to an existing domain.

For more information, see Handling Errors.

Example

For an Active Directory with the ID of 1045, name of myOldDomainName, and a nickname of myOldDomainNickname:

curl "http://MY-SERVER/api/3.24/domains/f34ab56cd12ab34cd56ef78ab90cd12ef" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-domain.xml

Content of update-domain.xml:

<tsRequest>
  <domain name="myNewDomainName.com"
  shortName="myNewDomainNickName" />
</tsRequest>
      

Example response body:

<tsRequest>
  <domain id="1045" name="myNewDomainName.com" shortName="myDomainNickName" />
</tsRequest>
      

Update Server Schedule

Modifies settings for the specified server schedule, including the name, priority, and frequency details on Tableau Server.
For Tableau Cloud, see Update cloud extract refresh task and Update subscription .

Update settings for allowed dashboard extension on site - Retired in API 3.21

---

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

---

PUT {server}/api/-/settings/site/extensions/dashboard/safeListItems/{safe_list_item_luid}

view details

Update Site

Modifies settings for the specified site, including the content URL, administration mode, user quota, state (active or suspended), storage quota, whether flows are enabled, whether subscriptions are enabled, and whether revisions are enabled.

This method is not available for Tableau Cloud.

Note: You must be signed in to a site to update it.

URI

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

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The ID of the site to update.

Request Body

Updating individual settings

<tsRequest>
  <site name="new-site-name"
	contentUrl="new-content-url"
	adminMode="new-admin-mode"
	storageQuota="limit-in-megabytes"
	disableSubscriptions="new-disable-subscriptions"
	state="new-state"
	revisionHistoryEnabled="revision-history-enabled"
	revisionLimit="revision-limit"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	subscribeOthersEnabled="subscribe-others-enabled-flag"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	commentingEnabled="commenting-enabled-flag"
	editingFlowsEnabled="editing-flows-enabled-flag"
	schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	extractEncryptionMode="extractEncryptionMode"
	dataAccelerationMode="dataAccelerationMode"
	requestAccessEnabled="request-access-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	dataAlertsEnabled="data-alerts-enabled-flag"
	commentingMentionsEnabled="commenting-mentions-enabled-flag"
	catalogObfuscationEnabled="catalog-obfuscation-enabled-flag"
	flowAutoSaveEnabled="flow-auto-save-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	metricsContentTypeEnabled="metrics-content-type-enabled-flag"
	notifySiteAdminsOnThrottle="notify-site-admins-on-throttle-flag"
	authoringEnabled="authoring-enabled-flag"
	customSubscriptionEmailEnabled="custom-subscription-email-enabled-flag"
	customSubscriptionEmail="custom-subscription-email"
	customSubscriptionFooterEnabled="custom-subscription-footer-enabled-flag"
	customSubscriptionFooter="custom-subscription-footer"
	askDataMode="ask-data-mode"
	namedSharingEnabled="named-sharing-enabled-flag"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	userVisibilityMode="user-visibility-mode"
	useDefaultTimeZone="default-time-zone-flag"
	timeZone="time-zone"
	autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
	autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window"
	explainDataEnabled="explaindataenabled"
	dqwSubscriptionsEnabled="dqwsubscriptionsenabled"
	attributeCaptureEnabled="attribute-capture-enabled"
	groupAssertionsEnabled="group-assertions-enabled-flag"
	groupAssertionsSAMLEnabled="group-assertions-saml-enabled-flag"
	groupAssertionsOIDCEnabled="group-assertions-oidc-enabled-flag"
	groupAssertionsConnectedAppsEnabled="group-assertions-connected-apps-enabled-flag"
	groupSetsEnabled="group-sets-enabled-flag" />
</tsRequest>
          

Updating the site logo

To set a new site logo, you pass a multi-part payload to the site. In addition to setting the X-Tableau-Auth header to the sign-in token, you must set the Content-Type header to multipart/mixed and include a boundary string. For example, the header might look like the following example:

Content-Type: multipart/mixed; boundary=az1by2cx34dw

The request body starts with the string you specify as the boundary. This is followed by two headers. You set Content-Disposition header to form-data, and then a name value set to site_logo and a filename value. You must also include a Content-Type header set to application/octet-stream. After the headers, you include a blank line then the binary data (not encoded). The binary data is followed by a line that includes the boundary string and the two required termination hyphens (--).

The following example shows the request body using the boundary string that was specified in the example header earlier.

--az1by2cx34dw Content-Disposition: form-data; name="site_logo"; filename="new-site-logo.png" Content-Type: application/octet-stream  <binary data here> --az1by2cx34dw--

Restoring the default site logo

To restore the default site logo, you pass a multi-part payload to the site, as you do to set the logo. However, instead of passing binary data for the image, you pass an empty image. And instead of setting the Content-Type header in the body to application/octet-stream, you set the content type to text/plain.

The following example shows the request body using the boundary string that was specified in the example header earlier.

--az1by2cx34dw Content-Disposition: form-data; name="site_logo"; filename="empty.txt" Content-Type: text/plain   --az1by2cx34dw--

Attribute Values

new-site-name	(Optional) The new name of the site.
new-content-url	(Optional) The new site URL. This value can contain only characters that are valid in a URL. These characters include letters (A-Z, a-z), digits (0-9), hyphens ("-"), and underscores ("_") If you provide invalid characters, those characters are stripped from the URL and the site is created anyway. For example, if you try to set the site URL as test.site, it's converted to testsite and returned in the response. The response's site URL namespace is the authoritative source of truth for the new site URL.
new-admin-mode	(Optional) Specify ContentAndUsers to allow site administrators to use the server interface and tabcmd commands to add and remove users. (Specifying this option doesn’t give site administrators permissions to manage users using the REST API.) Specify ContentOnly to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.) Note: You cannot set adminMode to ContentOnly and also set a userQuota value. The default value is ContentAndUsers.
new-state	(Optional) Active to set the site to active mode, or Suspended to suspend the site. Default is Active.
new-storage-quota	(Optional) The new maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again.
new-disable-subscriptions	(Optional) true to prevent users from being able to subscribe to workbooks on the specified site. Default is false.
revision-history-enabled	(Optional) true if the site maintains revisions for changes to workbooks and data sources; otherwise, false. The default is false.
revision-limit	(Optional) An integer between 2 and 10000 to indicate a limited number of revisions for content. Setting this value to -1 removes any value that was set previously, and effectively removes any limit to the number of revisions that are maintained.
allow-subscription-attachments-flag	(Optional) If true, and subscription to attachments is enabled on the server, then users can create subscriptions that send an email with images of a workbook or view in a PDF attachment. The default value is true. If subscription to attachments is disabled in the server settings, then making this value true will have no effect. Default is true.
subscribe-others-enabled-flag	(Optional) Specify true to enable and false to disable the ability for view owners to subscribe other users to a view. Default is true.
editing-flows-enabled-flag	(Optional) Specify true to enable and false to disable editing flows for a site. For more information on flows, see Enable and Configure Tableau Prep Conductor(Link opens in a new window). The default is set to true, which means editing flows is enabled by default. For more information, see Implication of disabling Tableau Prep Conductor.
scheduling-flows-enabled-flag	(Optional) Specify true to enable and false to disable scheduling flows for a site. For more information on flows, see Enable and Configure Tableau Prep Conductor(Link opens in a new window). The default is set to true, which means scheduling flows is enabled by default. For more information, see Implication of disabling Tableau Prep Conductor.
flows-enabled-flag	The flowsEnabled attribute is deprecated as of API 3.10.
guest-access-enabled-flag	(Optional) Specify true to enable and false to disable the ability for guests, users without specific site access permission, to access the site. Default is false.
cache-warmup-enabled-flag	This attribute was removed in API 3.19 and later. For current methods to improve Tableau performance see, View Acceleration(Link opens in a new window). (Optional) Set this value to true to enable cache warm up to improve workbook load times. Set the value to false to disable cache warmup. Default is true.
commenting-enabled-flag	(Optional) Specify true to enable and false to disable the ability for user comments on views in the site. Default is true.
extractEncryptionMode	(Optional) Specify enforced, enabled, or disabled. Default is disabled. For more information, see Extract and Encryption Methods.
dataAccelerationMode	(Optional) Specify enable_selective or disabled. The default is enable_selective, which lets you update particular workbooks to turn on data acceleration using the accelerationEnabled attribute. For more information, see Data Acceleration. (Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)
requestAccessEnabled	(Optional) Specify true to allow users send access request emails to content or project owners. Specify false if you don’t want users to be able to request access. The default is false.
runNowEnabled	(Optional) Specify true to allow users to run flows, extract refreshes, and schedules manually. Specify false if you don’t want users to be able to run flows, extract refreshes, and subscriptions manually. The default is true. If this attribute is set to false, the following methods will fail and will return an error message. Run Flow Now Run Flow Task(Link opens in a new window) Update Data Source Now(Link opens in a new window) Run Extract Refresh Task(Link opens in a new window)
Licensing attributes For user-based license types, the maximum number of users is set by the licenses activated on that server. For core-based licensing, there’s no limit to the number of users; if you specify a maximum value, only licensed users are counted, and server administrators are excluded. The REST API enables administrators to set licensing limits below the purchased maximum with two types of license-related attributes: - User Quota - The total maximum number of licenses currently configured for a site. - Tiered Capacities - If set, the configured maximum license count for each license type (role). . An on-premises server administrator can both get and set them but if license maximums are set using one attribute kind then the value(s) of the other kind must be null. Setting values for both kinds of attributes will result in an error. For more information, see Licensing Overview(Link opens in a new window).
User quota all-license-limit-total	(Optional) The maximum total number of users with Creator, Explorer, or Viewer licenses currently allowed on a site. On-premises server administrators can set userQuota with the following rules: The number can't exceed the number of licenses activated for the site; and if tiered capacity attributes are set, then userQuota will equal the sum of the tiered capacity values, and attempting to set userQuota will cause an error. An administrator can revert the license limit to number of activated licenses on the site, or shift control of license limits to tiered capacities values, by omitting userQuota from a Create Site or Update Site request, or making its value -1.
Tiered capacity attributes creator-license-limit explorer-license-limit viewer-license-limit	(Optional) The maximum number of licenses for users with the Creator, Explorer, or Viewer role, respectively, allowed on a site. On-premises server administrators can set tiered capacity attributes with the following rules: the number can't exceed the number of licenses of a given type that are activated for the site; a value must be supplied for every tiered capacity license type every time any one or more of them is set. A value of -1 removes the administrator-applied limit for a license type, and reverts the limit to the number of activated licenses configured for the role. Setting the value of a tiered capacity to -1 will not automatically increase the limit if more licenses are purchased and activated for the role in the future. To use role-specific license limits, the userQuota must be set to null by omitting the attribute from Create Site or Update Site request, or setting its value to -1. Attempting to set values for both tiered capacities and userQuota will result in an error.
data-alerts-enabled-flag	(Optional, boolean) If true, data alerts are enabled on the site. Default value is true.
commenting-mentions-enabled-flag	(Optional, boolean) If true, mentions for commenting are enabled. Default value is true.
catalog-obfuscation-enabled-flag	(Optional, boolean) If true, catalog obfuscation is enabled on the site. Default value is true.
flow-auto-save-enabled-flag	(Optional, boolean) If true, flow auto save is enabled on the site. Default value is true.
run-now-enabled-flag	(Optional, boolean) If true, run now for schedules is enabled which allows non-administrators to run schedules manually. Default value is true.
metrics-content-type-enabled-flag	(Optional, boolean) If true, the metrics content type is enabled on the server. Default value is false.
notify-site-admins-on-throttle-flag	(Optional, boolean) If true, site admins will be notified if their background jobs are being throttled. Default value is false.
authoring-enabled-flag	(Optional, boolean) If true, web authoring is enabled. Default value is false.
custom-subscription-email-enabled-flag	(Optional, boolean) If true, sending custom subscription email is enabled. If set to false after being set true, the current custom subscription email is voided. Default value is false.
custom-subscription-email	A valid custom email that will be sent if customSubscriptionEmailEnabled is set to true. Default value is false.
custom-subscription-footer-enabled-flag	(Optional, boolean) If true, a custom footer will be included on subscription and data alert emails. If set to false after being set true, the current custom subscription footer is voided. Default value is false.
custom-subscription-footer	A custom subscription footer that will be added to subscription and data alerts if customSubscriptionFooterEnabled is set to true. Default value is false.
ask-data-mode	The mode of the ask data feature on the site. Can be set to one of two values: DisabledByDefault - Enables creation of Ask Data lenses for all published data sources. Data sources do not have lenses created automatically. DisabledAlways - Disables Ask Data lenses and related content throughout the site. Preserves information about lenses and data source indexes, which are restored if Ask Data is re-enabled. Default value is DisabledByDefault. For more information, see Disable or Enable Ask Data for a Site(Link opens in a new window).
named-sharing-enabled-flag	(Optional, boolean) If true, named sharing is enabled. Default value is true.
cataloging-enabled-flag	(Optional, boolean) If true, data catalog is enabled for the site. Default value is true.
derived-permissions-enabled-flag	(Optional, boolean) If true, derived permissions are enabled for the site. Default value is false.
user-visibility-mode	(Optional, string) When the value is FULL users can see the user of other site users. If the value is LIMITED User information on the site is not visible to other users. Default value is FULL. For more information, see User Visibility(Link opens in a new window).
use-default-time-zone	(Optional, boolean) Set this to true, if you want the time-zone attribute use the Server time Zone at run time. This attribute is set to official IANA name.  If this is set to false, the time-zone value must be specified.
time-zone	(Optional, string) Use this attribute to specify a time zone other than the Server time zone at run time. Only canonical names in the official IANA database are supported. You can find the list of the canonical time zone names on Wikipedia.
autoSuspendRefreshEnabled	(Optional) Tableau can automatically suspend extract refresh tasks for inactive workbooks to save resources. Specify true to enable or false to disable. Default is true.
autoSuspendRefreshInactivityWindow	(Optional) An integer between 7 and 100 to indicate the number of days to wait before automatically suspending extract refresh tasks for inactive workbooks. The default is 30.
explainDataEnabled	(Optional, boolean) Set this attribute to false to disable Explain Data capabilities for a site. By default, this attribute is set to true. For more information about this site setting, see Disable or Enable Explain Data for a Site(Link opens in a new window) in the Tableau Server Help.
dqwSubscriptionsEnabled	(Optional, boolean) Set this attribute to false to exclude data quality warnings (DQWs) from subscription emails. By default, this attribute is set to true. For more information about this site setting, see Disable or Enable Explain Data for a Site(Link opens in a new window) in the Tableau Server Help.
groupAssertionsEnabled	(Optional) Set to true to allow assertions into group membership using session info. Set to false if you don’t want users to be able to be asserted in to groups. The default is false. If this attribute is set to false, it will disable group assertions for the entire site, including the following settings: groupAssertionsSAMLEnabled groupAssertionsOIDCEnabled groupAssertionsConnectedAppsEnabled
groupAssertionsSAMLEnabled	(Optional, boolean) Set to true to allow assertions into group membership using SAML session info. Set to false if you don’t want users to be able to be asserted in to groups. The default is false. If this attribute is set to false, it will disable group assertions for SAML sessions.
groupAssertionsOIDCEnabled	(Optional, boolean) Set to true to allow assertions into group membership using OIDC session info. Set to false if you don’t want users to be able to be asserted in to groups. The default is false. If this attribute is set to false, it will disable group assertions for OIDC sessions.
groupAssertionsConnectedAppsEnabled	(Optional, boolean) Set to true to allow assertions into group membership using Connected App JWT tokens. Set to false if you don’t want users to be able to be asserted into groups via connected apps. The default is false. If this attribute is set to false, it will disable group assertions for JWT connected app connections.
groupSetsEnabled	(Optiona, booleanl) Set to true to allow groups sets. Set to false if you don’t want group sets support for the site. The default is false. If this attribute is set to false, it will disable group sets for the site.

Any combination of the attributes inside the <site> element is valid. Only the attributes that are included are updated for the site. If no attributes are present, no update occurs. To update only the logo, include an empty <site> element (<site />) and the logo in the multipart message.

Starting in API version 2.3, you can call Update Site to upload a custom logo image for the site. (For information about custom logos, see Custom the Name or Logo(Link opens in a new window) in the Tableau Server Help.)

To upload a logo image, you include the image in a multipart message; this is similar to how you publish a workbook or data source. You must include the following headers in the request:

• MIME-Version: 1.0

• Content-Type: multipart/mixed; boundary=boundary-string

• X-Tableau-auth: authentication-token

The following example shows the request body for an Update Site request that updates the site with a new logo. For this example, the boundary string has been set in the header to 6691a87289ac461bab2c945741f136e6. The <site> element can be empty if you’re calling Update Site only to update the logo image.

--6691a87289ac461bab2c945741f136e6 Content-Disposition: name="request_payload" Content-Type: text/xml  <tsRequest>   <site site attributes >   </site> </tsRequest> --6691a87289ac461bab2c945741f136e6 Content-Disposition: name="site_logo"; filename="MySiteLogo.png" Content-Type: application/octet-stream logo stream here --6691a87289ac461bab2c945741f136e6--
        

To clear a custom logo image and revert to using the default logo for the site, call Update Site with a multipart message, but leave the portion of the request body blank where you would normally include the logo stream.

For more information about creating multipart messages, see Publishing Resources.

Permissions

Tableau Server: This method can only be called by server administrators.

Required scope for JWT authorization

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

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:sites:update

Response Code

200

Response Body

<tsResponse>
  <site id="site-id"
	name="site-name"
	contentUrl="content-url"
	adminMode="admin-mode"
	storageQuota="limit-in-megabytes"
	disableSubscriptions="true-or-false"
	state="active-or-suspended"
	revisionHistoryEnabled="true-or-false"
	revisionLimit="revision-limit"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	commentingEnabled="commenting-enabled-flag"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	requestAccessEnabled= "request-access-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	askDataMode="ask-data-mode"
	useDefaultTimeZone="default-time-zone-flag"
	timeZone="time-zone"
	autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
	autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window"
	explainDataEnabled="explain-data-enabled"
	dqwSubscriptionsEnabled="dqw-subscriptions-enabled"
	attributeCaptureEnabled="attribute-capture-enabled"
	groupAssertionsEnabled="group-assertions-enabled-flag"
	groupAssertionsSAMLEnabled="group-assertions-saml-enabled-flag"
	groupAssertionsOIDCEnabled="group-assertions-oidc-enabled-flag"
	groupAssertionsConnectedAppsEnabled="group-assertions-connected-apps-enabled-flag"
	groupSetsEnabled="group-sets-enabled-flag" />
  </site>
</tsResponse>
        

Response Body Details:

• userQuota, storageQuota, and tiered capacity (tierCreatorCapacity, tierExplorerCapacity, tierViewerCapacity) attributes are only present in the response body if those quotas have been set for the site being queried.

Version

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

Errors

HTTP status	error Code	Condition	Details
400	400008	Invalid revision history limit	The value for the revision history limit isn’t an integer.
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400004	Invalid administrator mode	An administrator mode parameter was provided in the request with an invalid value. The valid values are ContentOnly and ContentAndUsers.
400	400004	Invalid state	A state parameter was provided in the request with an invalid value
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type wasn’t PUT.
409	409001	Site name conflict	The new site name in the request already belongs to an existing site.
409	409002	Site URL conflict	The new content URL in the request already belongs to an existing site.
409	409004	User quota and tiered capacity conflict	The request can’t set both tiered capacity attributes and userQuota. One or the other must be null.
409	409004	License limit exceeded	The request can’t set tiered capacity attributes or userQuota values that are larger than the number of active licenses configured for the site.
409	409004	Administrator mode or user quota conflict	The request can’t set adminMode to ContentOnly and also specify a userQuota value.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-site.xml

Content of update-site.xml:

<tsRequest>
  <site
	adminMode="ContentOnly"
	storageQuota="1000"
	tierCreatorCapacity="2"
	tierExplorerCapacity="1"
	tierViewerCapacity="1"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles" />
</tsRequest>
      

Example response:

<tsResponse<
  <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
	name="Default"
	contentUrl="svc_licensingtest"
	adminMode="ContentAndUsers"
	disableSubscriptions="false"
	state="Active"
	revisionHistoryEnabled="true"
	revisionLimit="25"
	subscribeOthersEnabled="true"
	allowSubscriptionAttachments="true"
	guestAccessEnabled="false"
	cacheWarmupEnabled="true" [REMOVED IN API 3.19]
	commentingEnabled="true"
    editingFlowsEnabled="false"
    schedulingFlowsEnabled="false"
	extractEncryptionMode="disabled"
	catalogingEnabled="true"
	derivedPermissionsEnabled="true"
	askDataMode="DisabledByDefault"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles"
	explainDataEnabled="true"
	dqwSubscriptionsEnabled="false"
</tsResponse>
      

Update Subscription

Modifies an existing subscription on Tableau Server. You can change the subject, server schedule, and suspension state for the subscription.

Update Table

Update the table description, certify a table, or a assign a user contact to the 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-id/tables/table-id

Parameter Values

api-version	The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site asset.
table-id	The unique ID of the table asset.

Request Body

<tsRequest>
  <table isCertified="certification-status"
      certificationNote="certification-note"
      description="new-description-value">
    <contact id="new-contact-id" />
  </table>
</tsRequest>

Attribute Values

Any combination of attributes inside the <table> 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.

certification-status	(Optional) Use one of the following values: true false These values are case sensitive.
certification-note	(Optional) Custom text to accompany the certification status.
new-description-value	(Optional) Custom text to describe the table asset.
new-contact-id	(Optional) The ID (not name) of the certification owner.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update 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

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="b86632d7-b82e-4d4c-88e5-11957cdadd95" name="Zoning.shp" description="Contact Susan Nguyen (database admin) for changes." isEmbedded="true" isCertified="false">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
  </table>
</tsResponse>

Version

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

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized access	No authorization credentials were provided.
401	401002	Unauthorized access	Invalid authorization credentials were provided.
404	404000	Resource not found	The site ID in the URI doesn't correspond to an existing site.
404	404032	Table not found	The requested table asset could not be found.
409	409052	Table error	An unknown table asset error occurred.
409	409057	Table update error	An unknown error occurred and the table asset could not be updated.
409	409058	Table update forbidden	A user without "write" permissions to the table asset attempted an update.

Update Tableau extensions server settings

Updates the settings for extensions of a server.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403000	Non-admin access forbidden	The client attempted to access an API method while signed in as a non-administrator user.
404	404000	Bad Request	The requested resource could not be found.
500	500000	Internal Server Error	The request could not be completed.

For more information, see Handling Errors.

Update Tableau extensions site settings

Updates the settings for extensions of a site.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403000	Non-admin access forbidden	The client attempted to access an API method while signed in as a non-administrator user.
404	404000	Site Not Found	The site ID in the URI doesn't correspond to an existing site.
500	500000	Internal Server Error	The request could not be completed.

For more information, see Handling Errors.

Update User

Modifies information about the specified user.

Tableau Server

If Tableau Server is configured to use local authentication, you can update the user's name, email address, password, or site role.

If Tableau Server is configured to use Active Directory for authentication, you can change the user's display name (full name), email address, and site role. However, if you synchronize the user with Active Directory, the display name and email address will be overwritten with the information that's in Active Directory.

Tableau Cloud

For Tableau Cloud, you can update the site role for a user, but you cannot update or change a user's password, user name (email address), or full name.

Update User Notification Preferences

Updates user notifications preferences to enabled or disabled on the specified site. For more information about notifications, see Manage Your Account Settings.

Update Virtual Connection

Updates a virtual connection's name, owner, project, or certification status.

Errors

HTTP status	error Code	Condition	Details
400	400203	Generic error	An unknown error occurred.
403	403004	User not authorized to change virtual connection	Check to make sure the user has the required permissions.
403	403176	User not authorized to change virtual connection's owner	Check to make sure the user has the required permissions.
403	403177	User not authorized to move assets into the target project.	Check to make sure the user has the required permissions.
403	403178	User not authorized to move the virtual connection	Check to make sure the user has the required permissions.
404	404049	Virtual connection not found	Check the virtual connection LUID.
409	409124	A virtual connection with the chosen name already exists in the project.	Try a different virtual connection name.

For more information, see Handling Errors.

Update Virtual Connection Database Connections

Updates the server address, port, username, or password for the specified database connection in a virtual connection.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized	The authentication token provided in the request header was invalid or has expired.
403	403004	Operation unauthorized	The user isn’t authorized to perform the task.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Update Workbook

Modifies an existing workbook, allowing you to change the owner or project that the workbook belongs to and whether the workbook shows views in tabs. Updated workbooks can optionally be marked to appear in the recently viewed list.
You can manage Data Freshness Policy(Link opens in a new window) for a workbook, and enable View Acceleration(Link opens in a new window) for views in a workbook.

Update Workbook Connection

Updates the server address, port, username, or password for the specified workbook connection.

If the workbook contains multiple connections to the same data source type, all the connections are updated. For example, if the workbook contains three connections to the same PostgreSQL database, and you attempt to update the user name of one of the connections, the user name is updated for all three connections.

Any combination of the attributes inside the <connection> element is valid. If no attributes are included, no update is made.

Update Workbook Now

Refreshes the specified workbook.

This method refreshes the specified workbook, with no need to associate the workbook refresh with a scheduled task. This method is the equivalent of selecting a workbook using the Tableau Server UI, and then selecting Refresh Extracts from the menu (also known as a "manual refresh").

Note: This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

Upload Data Source Encrypted Keychain

Uploads the encrypted version of the embedded credentials. This method will only work if the credentials are encrypted with the latest public key used to link the source Tableau Server with the destination Tableau Cloud or Tableau Server site.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

associatedUserLuidMapping	(Required) The user IDs from the source site mapped to destination site user IDs.
encryptedKeychainList	(Required) List of encrypted keychains from the source Tableau Server.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404004	Data source not found	The data source ID in the URI doesn't correspond to an existing data source.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Upload User Credentials

Uploads user credentials to a site on a destination Tableau Cloud or Tableau Server.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404002	User not found	The user ID in the URI doesn't correspond to an existing user.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Upload Workbook Encrypted Keychain

Uploads the encrypted version of the embedded credentials. This method will only work if the credentials are encrypted with the latest public key used to link the source Tableau Server with the destination Tableau Cloud or Tableau Server site.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

Errors

HTTP status	error Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.