API Reference—All Methods

Using the Tableau Server REST API, you can manage and change Tableau Server resources programmatically, via HTTP. The API gives you simple access to the functionality behind the data sources, projects, workbooks, site users, and sites on a Tableau server. You can use this access to create your own custom applications or to script interactions with Tableau Server resources.

Note: For help with your code that uses the Tableau REST API, submit questions and ask for help on the Tableau developer community forums(Link opens in a new window). For potential bugs in the Tableau REST API code itself, and for any issue with unmodified sample code we provide, use the feedback widget at the bottom of API reference pages.

API Method Categories

The following table lists the Tableau Server REST API methods by category. The table also indicates which methods can be used with Tableau Cloud.

Analytics Extensions Settings Methods
Add analytics extension connection to site Adds an analytics extensions connection for an external service to a site.
Delete analytics extension connection from site Deletes a specific analytics extension connection for an external service from a site.
Enable or disable analytics extensions on server
- Not available for Tableau Cloud
Enables or disables analytics extensions on a server.
Get analytics extension details Get the details of a specified analytics extension connection to an external service.
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 enabled state of analytics extensions on server
- Not available for Tableau Cloud
Gets the enabled/disabled state of analytics extensions on a server.
Get enabled state of analytics extensions on site Gets the enabled/disabled state of analytics extensions on a site.
List analytics extension connections of workbook Lists basic details of each analytics extension connection available for a specified workbook, including connection type and name.
List analytics extension connections on site Lists a site's analytics extension connections for external services.
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.
Update analytics extension connection of site Updates the details of specified analytics extension connection for an external service to a site.
Update analytics extension for workbook Updates the analytics extension connection to external service currently used by a workbook.
Update enabled state of analytics extensions on site Enables or disables analytics extensions on a site.
Ask Data Lens Methods - Retired in API 3.22
Create ask data lens - Retired in API 3.22 Create an ask data lens.
Delete ask data lens - Retired in API 3.22 Delete an ask data lens.
Get ask data lens - Retired in API 3.22 Get the details of the specified ask data lens.
Import ask data lens - Retired in API 3.22 Import an existing ask data lens on a server to a site, and optionally transform the metadata of the lens in the process.
List ask data lenses in site - Retired in API 3.22 Returns a list of ask data lenses in a site.
Authentication Methods
List Personal Access Tokens
- Not available for Tableau Server.
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.
Revoke Administrator Personal Access Tokens
- Not available for Tableau Cloud.
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
- Not available for Tableau Server.
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.
Sign In Signs you in as a user on the specified site on Tableau Server or Tableau Cloud.
Sign Out Signs you out of the current session. This call invalidates the authentication token that is created by a call to Sign In.
Switch Site
- Not available for Tableau Cloud.
Switches you onto another site without having to provide a user name and password again.
Connected App Methods
Create Connected App Create a connected app.
Create Connected App Secret Generate a secret for a connected app.
Delete Connected App Permanently remove a connected app.
Delete Connected App Secret Permanently remove a secret associated with a connected app.
Delete EAS
- Not available for Tableau Server.
Delete a registered external authorization server (EAS).
Get Connected App Query a connected app by its ID.
Get Connected App Secret Query a connected app secret and the token value using the connected app's ID.
List All Registered EAS
- Not available for Tableau Server.
Get all external authorization servers (EASs) registered to a site.
List Connected Apps Query all connected apps configured on a site.
List Registered EAS
- Not available for Tableau Server.
Get an external authorization server (EAS) registered to a site.
Register EAS
- Not available for Tableau Server.
Create a connected app with OAuth 2.0 trust by registering an external authorization server (EAS) to a site.
Update Connected App Update a connected app.
Update EAS
- Not available for Tableau Server.
Update a connected app with OAuth 2.0 trust.
Content Exploration Methods
Get batch content usage statistics
- Not available for Tableau Server
Gets usage statistics for multiple content items. The batch of can include multiple content types.
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 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 usage statistics for content item
- Not available for Tableau Server
Gets the usage statistics for a Tableau content item, specified by LUID and content type, such as workbook, datasource, or flow.
Dashboard Extensions Settings Methods - Retired in API 3.21
Allow dashboard extension on site - Retired in API 3.21 Adds a dashboard extension to the safe list of the site you are signed into.
Block dashboard extension on server - Retired in API 3.21
- Not available for Tableau Cloud
Adds a dashboard extension to the block list of a server.
Disallow dashboard extension on site - Retired in API 3.21 Deletes a specific dashboard extension from the safe list of the site you are signed into.
Get allowed dashboard extension on site - Retired in API 3.21 Gets the details of a specific dashboard extension on the safe list of the site you are signed into.
Get blocked dashboard extension on server - Retired in API 3.21
- Not available for Tableau Cloud
Gets the details of a specific dashboard extension on the blocked list of a server.
List allowed dashboard extensions on site - Retired in API 3.21 Lists the dashboard extensions on the safe list of the site you are signed into.
List blocked dashboard extensions on server - Retired in API 3.21
- Not available for Tableau Cloud
Lists the dashboard extensions on the blocked list of a server.
List dashboard extension settings of site - Retired in API 3.21 Lists the dashboard extension settings of the site you are signed into.
List settings for dashboard extensions on server - Retired in API 3.21
- Not available for Tableau Cloud
Lists the dashboard extension settings of a server.
Unblock dashboard extension on server - Retired in API 3.21
- Not available for Tableau Cloud
Deletes a specific extension from the block list of a server.
Update dashboard extension settings of site - Retired in API 3.21 Updates the settings for dashboard extensions for the site you are signed into.
Update dashboard extensions settings of server - Retired in API 3.21
- Not available for Tableau Cloud
Updates the settings for dashboard extensions of a server.
Update settings for allowed dashboard extension on site - Retired in API 3.21 Updates the settings of a specific dashboard extension in the safe list of the site you are signed into.
Data Sources Methods
Add Tags to Data Source Adds one or more tags to the specified data source.
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 Tag from Data Source Deletes a tag from the specified data source.
Download Data Source Downloads a data source in .tdsx format.
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.
Get Data Source Revisions Returns a list of revision information (history) for the specified data source.
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.
Query Data Source Returns information about the specified data source.
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.
Remove Data Source Revision Removes a specific version of a data source from the specified site.
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.
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.
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.
Extract and Encryption Methods
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 Cloud Extract Refresh Task
- Not available for Tableau Server.
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.
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.
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).
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.
Delete the Extract from a Data Source Delete the extract of a data source in a site.
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).
Get Extract Refresh Task Returns information about the specified extract refresh task.
List Extract Refresh Tasks in Server Schedule
- Not available for Tableau Cloud.
Returns a list of the extract refresh tasks for a specified server schedule on the specified site on Tableau Server.
List Extract Refresh Tasks in Site Returns a list of extract refresh tasks for the site.
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).
Run Extract Refresh Task Runs the specified extract refresh task.
Update Cloud extract refresh task
- Not available for Tableau Server.
Updates a custom schedule for an extract refresh task on Tableau Cloud.
For Tableau Server, see Update server schedule.
Favorites Methods
Add Data Source to Favorites Adds the specified data source to the user's favorites.
Add Flow to Favorites Adds the specified flow to the user's favorites.
Add Metric to Favorites - Retired in API 3.22 Adds the specified metric to the user's favorites.
Add Project to Favorites Adds the specified project to a user's favorites.
Add View to Favorites Adds the specified view to a user's favorites.
Add Workbook to Favorites Adds the specified workbook to a user's favorites.
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 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 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 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 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.
Get Favorites for User Returns a list of favorite projects, data sources, views, workbooks, and flows for a user.
Organize Favorites Move an item to organize a user's favorites.
Flow Methods
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 Flow Task with Custom Schedule method. Create Cloud Flow Task method.
Cancel Flow Run Cancels a flow run that is in progress.
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 Permission Deletes the specified permission from the specified flow for a group or user.
Download Flow Downloads a flow in .tfl or .tflx format.
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 Linked Task
- Available only with a Data Management license.
Returns information about a specific linked task. This method shows you information about the scheduled linked task.
Get Linked Tasks
- Available only with a Data Management license.
Returns a list of scheduled linked tasks for a site.
Publish Flow Publishes a flow on the specified site. To make other changes to a published flow, call Update Flow or Update Flow Connection.
Query Flow Returns information about the specified flow, including information about the project, owner, and output steps.
Query Flow Connections Returns a list of data connections for the specific flow.
Query Flow Permissions Returns a list of permissions 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.
Run Flow Now Runs the specified flow.
Run Flow Task Runs the specified flow run task.
Run Linked Task Now
- Available only with a Data Management license.
Runs the specified linked task.
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.
Identity Pools Methods
Add User to Identity Pool
- Not available for Tableau Cloud.
Add a user to a specified identity pool.
Configure Identity Store
- Not available for Tableau Cloud
Configure a new local identity store to provision users.
Create Authentication Configuration
- Not available for Tableau Cloud
Create an instance of OpenID Connect (OIDC) authentication.
Create Identity Pool
- Not available for Tableau Cloud
Create an identity pool.
Delete Authentication Configuration
- Not available for Tableau Cloud
Delete an authentication instance.
Delete Identity Pool
- Not available for Tableau Cloud
Delete an identity pool.
Delete Identity Store
- Not available for Tableau Cloud
Delete an identity store.
Get Identity Pool
- Not available for Tableau Cloud
Get information about an identity pool.
List Authentication Configurations
- Not available for Tableau Cloud
List information about all authentication instances.
List Identity Pools
- Not available for Tableau Cloud
List all identity pools.
List Identity Stores
- Not available for Tableau Cloud
List information about all identity store instances used to provision users.
Remove User from Identity Pool
- Not available for Tableau Cloud.
Remove a user from a specified identity pool.
Update Authentication Configuration
- Not available for Tableau Cloud
Update an authentication instance.
Update Identity Pool
- Not available for Tableau Cloud
Update information about an identity pool.
Jobs, Tasks, and Schedules Methods
Add Data Source to Server Schedule
- Not available for Tableau Cloud.
Adds a task to refresh a data source to an existing server schedule on Tableau Server.
For Tableau Cloud, see Create custom extract refresh schedule.
Add Workbook to Server Schedule
- Not available for Tableau Cloud.
Adds a task to refresh or accelerate a workbook to an existing schedule on Tableau Server.
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.
Create Server Schedule
- Not available for Tableau Cloud.
Creates a new server schedule on Tableau Server.
For Tableau Cloud, see Create Cloud Extract Refresh Task and Create subscription.
Delete Data Acceleration Task Deletes a data acceleration task.
Delete Server Schedule
- Not available for Tableau Cloud.
Deletes the specified schedule on Tableau Server.
For Tableau Cloud, see Delete Extract Refresh Task and Delete Subscription.
Get Data Acceleration Tasks in a Site Returns a list of data acceleration tasks for the site.
Get Server Schedule
- Not available for Tableau Cloud.
Returns detailed information about the specified server schedule on Tableau Server.
List Server Schedules
- Not available for Tableau Cloud.
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.
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:.
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.
Update Server Schedule
- Not available for Tableau Cloud.
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 .
Metadata Methods
Add (or Update) Quality Warning Trigger
- Available only with a Data Management license.
Create or update one or more quality warning triggers to monitor and display alerts for the following events: refresh failures on extract data sources and flow run failures on flows.
Add Data Quality Warning
- Available only with a Data Management license.
Add a data quality warning to a database, table, column, published data source, flow, virtual connection, or virtual connection table.
Add Database Permissions
- Available only with a Data Management license.
Add permissions to a database asset. To add permissions, the database asset must be associated with a published data source.
Add Default Database Permissions
- Available only with a Data Management license.
Adds default permission capabilities to a user or group for table resources in that database. These default permissions function as a permissions template for the database's table assets.
Add Table Permissions
- Available only with a Data Management license.
Add permissions to a table asset.
Add Tags to Column Add one or more tags to a column.
Add Tags to Database Add one or more tags to a database.
Add Tags to Table Add one or more tags to a table.
Batch Add or Update Data Quality Certifications
- Available only with a Data Management license.
Create or update one or more data quality certifications for different content and asset items.
Batch Add or Update Data Quality Warnings
- Available only with a Data Management license.
Add or update multiple data quality warnings on assets.
Batch Add Tags
- Available only with a Data Management license.
Add multiple tags to items that are different content and asset types.
Batch Delete Data Quality Warnings
- Available only with a Data Management license.
Delete multiple data quality warnings from assets.
Batch Delete Tags
- Available only with a Data Management license.
Delete multiple tags from items that are different content and asset types.
Create Label Category
- Available only with a Data Management license.
Creates a data label category.
Create or Update labelValue
- Available only with a Data Management license.
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.
Delete Data Quality Certification by ID
- Available only with a Data Management license.
Delete a data quality certification from an asset using the data quality certification ID.
Delete Data Quality Certifications by Content
- Available only with a Data Management license.
Delete multiple data quality certifications from assets.
Delete Data Quality Warning by Content
- Available only with a Data Management license.
Delete the data quality warnings from an asset.
Delete Data Quality Warning by ID
- Available only with a Data Management license.
Delete a data quality warning from an asset using the data quality warning ID.
Delete Database Permissions
- Available only with a Data Management license.
Permanently remove the permissions applied to a database asset.
Delete Default Database Permissions
- Available only with a Data Management license.
Permanently remove the default permissions on a database asset.
Delete Label
- Available only with a Data Management license.
Deletes a data label by its LUID.
Delete Label Category
- Available only with a Data Management license.
Deletes a label category.
Delete Labels
- Available only with a Data Management license.
Deletes the data labels on one or more assets.
Delete labelValue
- Available only with a Data Management license.
Deletes a label value.
Delete Quality Warning Trigger by ID
- Available only with a Data Management license.
Permanently remove a quality warning trigger using the quality warning trigger ID.
Delete Quality Warning Triggers by Content
- Available only with a Data Management license.
Permanently remove all quality warning triggers for one or more data sources or flows, or both.
Delete Table Permissions
- Available only with a Data Management license.
Permanently remove the permissions applied to a table asset.
Delete Tag from Column Delete a tag from a column.
Delete Tag from Database Delete a tag from a database.
Delete Tag from Table Delete a tag from a table.
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.
Get Label
- Available only with a Data Management license.
Gets a data label by its LUID.
Get Labels
- Available only with a Data Management license.
Displays information about the data labels on one or more assets.
Get labelValue
- Available only with a Data Management license.
Displays label value properties for a single label value.
List Label Categories on Site
- Available only with a Data Management license.
Lists all data label categories on the site.
List labelValues on Site
- Available only with a Data Management license.
Lists all label values on the site.
Move Database
- Available only with a Data Management license.
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.
Move Table
- Available only with a Data Management license.
Moves one or more tables to a project.
Query All Quality Warning Triggers by Content Get information about all quality warning triggers for a content item.
Query Column in a Table Get information about a column in a table asset.
Query Columns in a Table Get information about the columns in a table asset.
Query Data Quality Certification by ID Get information about a data quality certification.
Query Data Quality Certifications by Content Get all data quality certifications for content or asset items.
Query Data Quality Warning by Content
- Available only with a Data Management license.
Get information about the data quality warning for the database, table, column, published data source, flow, virtual connection, or virtual connection table.
Query Data Quality Warning by ID Get information about a specific data quality warning.
Query Database Get information about a database asset.
Query Database Permissions Get information about the permissions on a database asset.
Query Databases Get information about all database assets for a site.
Query Default Database Permissions Get the default permissions applied to the database asset and its children tables.
Query Quality Warning Trigger Get information about a quality warning trigger.
Query Table Get information about a table asset.
Query Table Permissions Get information about the permissions on a table asset.
Query Tables Get information about all table assets for a site.
Remove Column
- Available only with a Data Management license.
Permanently remove the column from a table asset.
Remove Database
- Available only with a Data Management license.
Permanently remove the database asset.
Remove Table
- Available only with a Data Management license.
Permanently remove the table asset.
Update Column
- Available only with a Data Management license.
Update the description of the column.
Update Data Quality Warning
- Available only with a Data Management license.
Update the warning type, status, and message of a data quality warning.
Update Database
- Available only with a Data Management license.
Update the database description, certify a database, set content permissions, or assign a contact (must be a Tableau Server or Tableau Cloud user) to the database asset.
Update Label
- Available only with a Data Management license.
Updates a label by its LUID. This method can update the label value, message, active flag, and elevated flag.
Update Label Category
- Available only with a Data Management license.
Updates a data label category.
Update Labels
- Available only with a Data Management license.
Creates or updates labels on one or more assets. (An asset can be Tableau content or an external asset.) Each asset listed in the request body is updated to have a label with the specified value, message, active flag, and elevated flag.
Update labelValue
- Available only with a Data Management license.
Updates a label value.
Update Quality Warning Trigger
- Available only with a Data Management license.
Update a quality warning trigger.
Update Table
- Available only with a Data Management license.
Update the table description, certify a table, or a assign a user contact to the table asset.
Metrics Methods - Retired in API 3.22
Delete Metric - Retired in API 3.22 Deletes a specified metric from a site.
Get Metric - Retired in API 3.22 Returns the details of the specified metric.
Get Metric Data - Retired in API 3.22 Returns the data for the specified metric as comma separated (CSV) format. The maximum number of rows returned is 10,000.
List Metrics for Site - Retired in API 3.22 Returns the metrics configured for a site.
Update Metric - Retired in API 3.22 Updates the owner, project, suspended status, or name of the specified metric.
Mobile Settings Methods
Get Mobile Security Settings for Server Gets the mobile security settings for the server.
Get Mobile Security Settings for Site Gets the mobile security settings for the specified site.
Update Mobile Security Settings for Site Updates the mobile security sections for a specified site.
Notifications Methods
Add User to Data-Driven Alert Adds a specified user to the recipients list for a data-driven alert.
Create a Webhook Creates a new webhook for a site.
Create Data Driven Alert
- Not available for Tableau Server.
Create a data driven alert (DDA) for a view with a single data axis.
Delete a Webhook Deletes the specified webhook.
Delete Data-Driven Alert Deletes the specified data-driven alert from the specified site.
Delete User from Data-Driven Alert Removes a specified user from the recipients list for a data-driven alert.
Get a Webhook Returns information about the specified webhook.
Get Data-Driven Alert Returns details on a specified data-driven alert, including the recipients of the alert.
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.
List Data-Driven Alerts on Site Returns a list of data-driven alerts in use on the specified site.
List Webhooks Returns a list of all the webhooks on the specified site.
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.
Update a Webhook Modify the properties of an existing webhook.
Update Data-Driven Alert Update one or more settings for the specified data-driven alert; including the alert subject, frequency, and owner.
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.
OpenID Connect Methods
Create OpenID Connect Configuration
- Not available for Tableau Server.
Create the Tableau Cloud site's OpenID Connect (OIDC) configuration.
Get OpenID Connect Configuration
- Not available for Tableau Server.
Get details about the Tableau Cloud site's OpenID Connect (OIDC) configuration.
Remove OpenID Connect Configuration
- Not available for Tableau Server.
Disable and clear the Tableau Cloud site's OpenID Connect (OIDC) configuration.
Update OpenID Connect Configuration
- Not available for Tableau Server.
Update the Tableau Cloud site's OpenID Connect (OIDC) configuration.
Permissions Methods
Add Ask Data Lens Permissions - Retired in API 3.22 Adds permissions to the specified ask data lens for a user or group. You can specify multiple sets of permissions using one request.
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.
Add Default Permissions Adds default permission rules for workbook, data source, data role, lens, flow, and metric 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).
Add Project Permissions Adds permissions to the specified project for a user or group. You can specify multiple sets of permissions using one call.
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 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 Server Schedule
- Not available for Tableau Cloud.
Adds a task to refresh or accelerate a workbook to an existing schedule on Tableau Server.
Delete Ask Data Lens Permission - Retired in API 3.22 Deletes the specified permissions to the specified ask data lens for a user or group.
Delete Data Source Permission Removes the specified data source permission for the specified group or user.
Delete Default Permission Removes default permission rules for workbook, data source, data role, lens, flow, and metric 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 Project Permission Removes the specified project permission for the specified group or user.
Delete View Permission Deletes permission to the specified view (also known as a sheet) for a Tableau Server user or group.
Delete Workbook Permission Deletes the specified permission from the specified workbook for a group or user.
List Ask Data Lens Permissions List all permissions configured for the specified ask data lens that the user has read capability for.
Query Data Source Permissions Returns a list of permissions for a specific data source.
Query Default Permissions Returns details of default permission rules granted to users and groups for workbook, data source, data role, lens, flow, or metric 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.
Query Project Permissions Returns information about the set of permissions allowed or denied for groups and users in a project.
Query View Permissions Returns a list of permissions for the specific view.
Query Workbook Permissions Returns a list of permissions for the specific workbook.
Projects Methods
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.
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.
Query Projects Returns a list of projects on the specified site, with optional parameters for specifying the paging of large results.
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.
Publishing Methods
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.
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.
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.
Publish Flow Publishes a flow on the specified site. To make other changes to a published flow, call Update Flow or Update Flow Connection.
Publish Workbook Publishes a workbook on the specified site. To make changes to a published workbook, call Update Workbook or Update Workbook Connection.
Pulse Methods
Batch create subscriptions
- Not available for Tableau Server
Creates multiple subscriptions to a metric for specified users and/or groups.
Batch get subscriber counts
- Not available for Tableau Server
Gets the number of unique users subscribed to a set of metrics specified in a comma separated list of metric LUIDs.
Batch get subscriptions
- Not available for Tableau Server
Gets a batch of subscriptions, specified in a comma delimited list of subscriptions LUIDs.
Batch list metric definitions
- Not available for Tableau Server
Gets a batch of metric definitions and metrics available on a site.
Batch list metrics
- Not available for Tableau Server
Gets a batch of metrics from a definition, specified in a comma delimited list.
Create metric
- Not available for Tableau Server
Creates a metric.
Create metric definition
- Not available for Tableau Server
Creates a metric definition.
Create subscription
- Not available for Tableau Server
Creates a subscription to a specified metric for a specified user or group.
Delete metric
- Not available for Tableau Server
Deletes a metric.
Delete metric definition
- Not available for Tableau Server
Deletes a metric definition.
Delete subscription
- Not available for Tableau Server
Deletes a specified subscription to a metric.
Generate current metric value insight bundle
- Not available for Tableau Server
Generates a bundle the current aggregated value for each metric.
Generate detail insight bundle
- Not available for Tableau Server
Generates a detail insight bundle.
Generate springboard insight bundle
- Not available for Tableau Server
Generates a springboard insight bundle.
Get metric
- Not available for Tableau Server
Gets the details of the specified metric.
Get metric definition
- Not available for Tableau Server
Gets a metric definition and optionally metrics it contains.
Get or create metric
- Not available for Tableau Server
Returns the details of a metric in a definition if it exists, or creates a new metric if it does not. Also returns.
Get subscription
- Not available for Tableau Server
Gets a specified subscription to a metric.
List metric definitions
- Not available for Tableau Server
Lists the metric definitions configured for a site or, optionally, the details and definition for a specific metric.
List metrics in definition
- Not available for Tableau Server
Lists the metrics contained in a metric definition.
List subscriptions
- Not available for Tableau Server
Lists the subscriptions to a specified metric and/or for a specified user.
Update metric
- Not available for Tableau Server
Updates the specification of a metric.
Update metric definition
- Not available for Tableau Server
Updates a metric definition.
Revisions Methods
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.
Download Workbook Revision
- Available only if version history is enabled for the specified site.
Downloads a specific version of a workbook in .twb or .twbx format.
Get Data Source Revisions Returns a list of revision information (history) for the specified data source.
Get Workbook Revisions Returns a list of revision information (history) for the specified workbook.
Remove Data Source Revision Removes a specific version of a data source from the specified site.
Remove Workbook Revision Removes a specific version of a workbook from the specified site.
Server Methods
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.
Get Current Server Session Returns details of the current session of Tableau Server.
List Server Active Directory Domains
- Not available for Tableau Cloud.
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.
Server Info Returns the version of Tableau Server and the supported version of the REST API.
Update Server Active Directory Domain
- Not available for Tableau Cloud.
Changes the nickname or full domain name of an Active Directory domain on the server. This method is not available on Tableau Cloud.
Site Methods
Create Site
- Not available for Tableau Cloud.
Creates a site on Tableau Server. To make changes to an existing site, call Update Site. This method is not available for Tableau Cloud.
Delete Site
- Not available for Tableau Cloud.
Deletes the specified site.
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.
Get Embedding Settings for a Site Returns the current embedding settings for a specific site.
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.
Query Site Returns information about the specified site, with the option to return information about the storage space and user count for the site.
Query Sites
- Not available for Tableau Cloud.
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.
Query Views for Site Returns all the views for the specified site, optionally including usage statistics.
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.
Update Site
- Not available for Tableau Cloud.
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.
Subscriptions Methods
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.
Delete Subscription Deletes the specified subscription on Tableau Server or Tableau Cloud.
Get Subscription Returns information about the specified subscription.
List Subscriptions Returns a list of all the subscriptions on the specified site.
Update Subscription Modifies an existing subscription on Tableau Server. You can change the subject, server schedule, and suspension state for the subscription.
Tableau Extensions Settings Methods
List Tableau extensions server settings
- Not available for Tableau Cloud.
Lists the settings for extensions of a server.
List Tableau extensions site settings Lists the settings for extensions of a site.
Update Tableau extensions server settings
- Not available for Tableau Cloud.
Updates the settings for extensions of a server.
Update Tableau extensions site settings Updates the settings for extensions of a site.
Users and Groups Methods
Add Group to Group Set Adds group to a group set.
Add User to Group Adds a user to the specified group.
Add User to Site Adds a user to Tableau Server or Tableau and assigns the user to the specified site.
Create Group Creates a group on Tableau Server or Tableau Cloud site.
Create Group Set Creates a group set with a specified name.
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.
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 Users from Site with CSV Creates a job to remove a list of users, specified in a .csv file, from a site.
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 Users in Group Gets a list of users in the specified group.
Get Users on Site Returns the users associated with the specified site.
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.
Query Group Sets Lists all group sets matching optional filter and ordered by optional sort expression.
Query Groups Returns a list of groups on the specified site, with optional parameters for specifying the paging of large results.
Query User On Site Returns information about the specified user.
Remove Group from Group Set Removes a group from the specified group set.
Remove User from Group Removes a user from the specified group.
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.
Update Group Updates a group on a Tableau Server or Tableau Cloud site.
Update Group Set Updates a group set name on a Tableau Server or Tableau Cloud site.
Update User Modifies information about the specified user.
Virtual Connections Methods
List Virtual Connection Database Connections
- Available only with a Data Management license.
Returns a list of database connections found in the specified virtual connection and information about them.
List Virtual Connections
- Available only with a Data Management license.
Returns a list of available virtual connection names and IDs.
Update Virtual Connection Database Connections
- Available only with a Data Management license.
Updates the server address, port, username, or password for the specified database connection in a virtual connection.
Workbooks and Views Methods
Add Tags to View Adds one or more tags to the specified view.
Add Tags to Workbook Adds one or more tags to the specified workbook.
Delete Custom View Deletes the specified custom view.
Delete Tag from View Deletes a tag from the specified view.
Delete Tag from Workbook Deletes a tag from the specified workbook.
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.
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.
Download Workbook Downloads a workbook in .twb or .twbx format.
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.
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.
Download Workbook Revision
- Available only if version history is enabled for the specified site.
Downloads a specific version of a workbook in .twb or .twbx format.
Get Custom View Gets the details of a specified custom view.
Get Custom View Image Downloads a .png format image file of a specified custom view.
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 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.
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.
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.
List Custom Views Gets a list of custom views on a site. The list includes details of each custom view.
List Users with Custom View as Default - Preview Release
- Preview release only in some regions
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.
Publish Workbook Publishes a workbook on the specified site. To make changes to a published workbook, call Update Workbook or Update Workbook Connection.
Query View Data Returns a specified view rendered as data in comma-separated-value (CSV) format.
Query View Image Returns an image of the specified view.
Query View PDF Returns a specified view rendered as a .pdf file.
Query View Preview Image Returns the thumbnail image for the specified view.
Query Views for Site Returns all the views for the specified site, optionally including usage statistics.
Query Views for Workbook Returns all the views for the specified workbook, optionally including usage statistics.
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.
Query Workbooks for Site Returns the workbooks on a site.
Query Workbooks for User Returns the workbooks that the specified user owns in addition to those that the user has Read (view) permissions for.
Set Custom View as Default for Users - Preview release
- Preview release only in some regions
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.
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 Custom View Changes the owner or name of an existing custom view.
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.
Update Workbook Now Refreshes the specified workbook.

API Method Details

The following content describes each endpoint in the Tableau REST API surface. Use the alphabetically sorted list of methods on the right, or ctrl/cmd-f to go directly to keywords you have in mind.

Add (or Update) Quality Warning Trigger

Create or update one or more quality warning triggers to monitor and display alerts for the following events: refresh failures on extract data sources and flow run failures on flows.

An asset can only have one trigger. Adding a trigger to an asset that already has one will update the trigger with the latest specified values.

Note: An asset can have one trigger and one DQW applied to it at the same time.

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

URI

Add or update a quality warning trigger

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

Add or update a quality warning trigger for multiple assets

POST 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.22. 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 is being applied to. 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

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

Attribute Values

Any combination of attributes inside the <dataQualityTrigger> element is valid, however type is required.

content

Type of content item to apply the trigger. To specify the type, use one of the following values:

  • EXTRACT_REFRESH
  • FLOW_RUN

These values are not case sensitive.

status

(Optional) Status of the trigger. Values can be "true" or "false". If set to "true", either the extract data source is monitored for refresh failures or the flow is monitored for flow run failures. If a failure occurs, an alert is applied (or replaces an existing one) to either the extract data source or flow. The alert remains there until the next successful refresh or flow run. 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 to accompany the trigger.
severity (Optional) Enables high visibility for the trigger. 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 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

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 quality warning trigger 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 analytics extension connection to site

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

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: This method can only be called by users with server or Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

PUT /api/api-version/sites/site-luid/lenses/lens-luid/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the data source.
lens-luid The LUID of the data source to set permissions for.

Request Body

                    <tsRequest>
  <permissions>
    <lens id="lens-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

lens-luid Required. The LUID of the ask data lens permissions are being configured for.
user-luid Optional (at least one user or group must be specified). The LUID of the user to add permissions for.
group-luid Optional. The LUID of the group to add permissions for.
capability-name The capability to assign. For valid capabilities for a data source project are ChangePermissions, Delete, Move, Read, Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Users with server or site administrator permissions, and non-administrators that have ChangePermissions permission for the lens (either explicitly or implicitly), can add ask data lens permissions.

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <lens id="lens-luid"  name ="lens-name" />
    <granteeCapabilities>
      <user id="user-luid" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        <!--    ... additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-luid" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        <!--   ... additional capabilities ...  -->
      </capabilities>
    </granteeCapabilities>
    <!--   ... additional grantee capability sets ...   -->
  </permissions>
</tsResponse>

Version

Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. 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 400009 Invalid capability The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Delete, Move, Read, and Write.
403 403004 No permissions to set permissions. A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404002 User not found The user specified in the request body doesn't correspond to an existing user.
404 404006 Lens not found The specified lens doesn't correspond to an existing data source.
404 404012 Group not found The group specified in the request body doesn't correspond to an existing group.
404 404013 Capability not found A capability specified 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.

For more information, see Handling Errors.

Add Data Quality Warning

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

This method adds a single data quality warning to an asset. (An automatically-generated monitoring warning does not count towards this limit.) Adding a data quality warning to the 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.22. 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

A custom message to accompany the data quality warning. The message is optional in Tableau Cloud, but required in Tableau Server.

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.

URI

PUT /api/api-version/sites/site-id/datasources/datasource-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. 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 set permissions for.

Request Body

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

Attribute Values

datasource-id The <datasource> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <datasource> element is included, the datasource-id value must match the data source ID in the URI. Any other attributes in the <datasource> element are ignored.
user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name The capability to assign. For valid capabilities for a data source project are ChangePermissions, Connect, Delete, ExportXml, Read (view), Write, and SaveAs.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Users who are not server administrators or site administrators can add permissions only to a data source for which they have ChangePermissions permission (either explicitly or implicitly).

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:permissions:update

Response Code

200

Response Body

<tsResponse version-and-namespace-settings>
  <permissions>
    <datasource id="datasource-id" />
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>
        

Version

Version 2.0 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 400009 Invalid capability The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write.
403 403004 No permissions to set permissions. A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404002 User not found The user specified in the request body doesn't correspond to an existing user.
404 404004 Data source not found The specified data source doesn't correspond to an existing data source.
404 404012 Group not found The group specified in the request body doesn't correspond to an existing group.
404 404013 Capability not found A capability specified 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.

For more information, see Handling Errors.

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.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <datasource id="datasource-id" />
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
datasource-id The ID of the data source to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite-label">
     <datasource id="datasource-id" />
    </favorite>
    <favorite label="favorite-label">
     <datasource id="datasource-id" />
    </favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>
        

Version

Version 2.3 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 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden favorites access A non-administrator user called this method but doesn't have permission to add a data source to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
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.
404 404011 Data source not found The data source ID in the request body doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different data source in the specified user's favorites.

For more information, see Handling Errors.

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 custom extract refresh schedule.

URI

PUT /api/api-version/sites/site-id/schedules/schedule-id/datasources

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
schedule-id The ID of the schedule that you are associating with the data source.

Request Body

<tsRequest>
  <task>
    <extractRefresh>
      <datasource id="datasource-id" />
    </extractRefresh>
  </task>
</tsRequest>
        

Attribute Values

datasource-id The ID of the data source to add to the schedule.

Permissions

Tableau Server users who are not server administrators or site administrators can only add a data source to a schedule if they own the data source, or are the project leader for the project that contains the data source.

Response Code

200

Response Body

<tsResponse>
  <task>
    <extractRefresh>
      <schedule id="schedule-id" />
      <datasource id="datasource-id" />
    </extractRefresh>
  </task>
</tsResponse>
        

Version

Version 2.8 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 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404004 Resource not found The data source ID in the request body is unknown.
405 405000 Invalid request method Request type was not PUT.
500 500000 Internal Server Error The schedule ID in the URI is unknown.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/datasources" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml

Content of add-to-schedule.xml:

<tsRequest>
  <task>
    <extractRefresh>
      <datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" />
    </extractRefresh>
  </task>
</tsRequest>
						

Example response:

<tsResponse>
  <task>
    <extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
      <schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
      <datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" />
    </extractRefresh>
  </task>
</tsResponse>
							

Add Database Permissions

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

Version: Available in API 3.5 (Tableau Cloud and Tableau Server) and later.  Version Overview

License: Available with Tableau Data Management(Link opens in a new window).

Permissions: Users that are granted ChangePermissions capabilities for the asset metadata and all administrators can add database permissions.  Permissions Overview

JWT Access Scope: Not available.      

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

Attribute Values

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

Request Attributes

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

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

Errors

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. These 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.22. 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, and metric 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).

URI

PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks

PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources

PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles

PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses

PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows

PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics

PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases

PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the project.
project-luid The LUID of the project 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. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, 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, SaveAs, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Users who are not server administrators can add permissions defaults for a project only if they have the ProjectLeader permission for that project (either explicitly or implicitly).

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:permissions:update

Response Code

200

Response Body

<tsResponse>
  <permissions>
	<database id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" name="oracle.test.example.com:1521"/>
	<granteeCapabilities>
	  <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
		</capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
        

Version

Version 2.1 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 400009 Invalid capability The capability in the URI is invalid for a data source.

Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, 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.

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 does not match the project ID specified in the request body. (You do not 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 Request type was not PUT.

For more information, see Handling Errors.

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.

URI

PUT /api/api-version/sites/site-id/flows/flow-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
datasource-id The ID of the flow.

Request Body

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

Attribute Values

flow-id The flow-id value for the flow you want to add permissions to.
user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.

For more information, see Permissions.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to set permissions on the flow (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
    <permissions>
        <flow id="8359f0c5-4b98-4ca4-a7e5-38e4261e88a2" name="Flow1">
            <owner id="8f735728-7484-40d1-89d1-41f09824536b"/>
        </flow>
        <granteeCapabilities>
            <group id="9de5cc1a-5bb8-4c8e-b2cd-b54e736a7b9f"/>
            <capabilities>
                <capability name="Read" mode="Allow"/>
                <capability name="Write" mode="Allow"/>
                <capability name="Delete" mode="Deny"/>
            </capabilities>
        </granteeCapabilities>
        <granteeCapabilities>
            <user id="1f2345678-1234-12d1-12d1-11f234567b"/>
            <capabilities>
                <capability name="Delete" mode="Allow"/>
            </capabilities>
        </granteeCapabilities>
    </permissions>
</tsResponse>
        

Version

Version 3.3 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 400009 Invalid capability The capability in the URI is invalid for a flow. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the flow.
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 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
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.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

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 Flow Task with Custom Schedule 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.

URI

PUT /api/api-version/sites/site-id/schedules/schedule-id/flows

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
schedule-id The ID of the schedule that you are associating with the flow. The schedule that you are adding to must have Flow as the schedule type.

Request Body

<tsRequest>
  <task>
    <flowRun>
      <flow id="flow-id"/>
	  <flowRunSpec>
	    <flowParameterSpecs>
	      <flowParameterSpec
	        parameterId="parameter-id"
	        overrideValue= "overrideValue"/>
	    <flowParameterSpecs>
	  <flowRunSpec>
     </flowRun>
   </task>
</tsRequest>
        

Attribute Values

flow-id

The ID of the flow to add to the schedule. This will include all the output steps in the flow and any output steps created in the future.

parameter-id

The ID of the flow parameter. Use the List Metrics for Site - Retired in API 3.22 method to get the flow parameter ID. A parameter is a global placeholder value such as a number, text value, or boolean value that can replace a constant value in a flow.

Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled.

For more information, see Run flows with parameters.

overrideValue

The run-time value for the flow parameter. You must specify this if the parameter is required. Use the List Metrics for Site - Retired in API 3.22 method to see if the parameter is required and to get a list of allowed values if the parameter is expecting a value from an enumerated list.

Note: Parameters are options and only relevant for flows that contains parameters and the parameter setting is enabled.

For more information, see Run flows with parameters.

Permissions

Tableau Server users who are not server administrators or site administrators can only add a flow to a schedule if they own the flow, or are the project leader for the project that contains the workbook.

Response Code

200

Version

Version 3.3 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 400148 Invalid parameter override value The run-time value provided for the flow parameter is invalid.
400 400149 Missing run-time parameter value. The run-time value for a required flow parameters was not provided.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403098 Update Forbidden A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404043 Flow parameter not found The flow parameter information was not provided.
404 404002 User not found A user ID in the request body doesn't correspond to an existing user.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/flows" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"

Content of add-to-schedule.xml:

The <flowRunSpec> in the request body is optional and only required in the following scenarios:

  • The flow has parameters and the parameter is marked as required to run the flow.
  • The flow has parameters but not marked as required. However, you want to specify a different value than the configured default.
<tsRequest>
   <task>
     <flowRun>
       <flow id="5ab9cd53-e17f-45gh-804i-4914jk39r29z"/>
	  <flowRunSpec>
	    <flowParameterSpecs>
	      <flowParameterSpec>
	        parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89"
	        overrideValue= "2"/>
	    <flowParameterSpecs>
	  <flowRunSpec>
     </flowRun>
   </task>
</tsRequest

Example response:

<tsResponse version-and-namespace-settings>
    <task>
      <flowRun id="8a78c68e-37ad-4b21-80fc-e67e2ab55279" priority="50" consecutiveFailedCount="0" type="RunFlowTask">
        <schedule id="99e8841e-8527-4d09-89b8-71d9872634df" name="demo" state="Active" priority="50" createdAt="2021-12-09T19:21:09Z" updatedAt="2022-01-19T23:06:56Z" type="Flow" frequency="Hourly" nextRunAt="2022-01-20T00:00:00Z"/>
        <flow id="09942c88-99d5-4669-aa62-07560fc4b201" name="CoffeeChain"/>
          <flowParametersRuns>
            <parameterRuns parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89" name="param 2 required" description=testparameter2" overrideValue = "2"/>
	   <flowParametersRuns>
      </flowRun>
    </task>
</tsResponse>

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.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <flow id="flow-id" />
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
flow-id The ID of the flow to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite-label">
     <flow id="flow-id" />
    </favorite>
    <favorite label="favorite-label">
     <flow id="flow-id" />
    </favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>
        

Version

Version 3.3 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 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden favorites access A non-administrator user called this method but doesn't have permission to add a data source to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
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.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different data source in the specified user's favorites.

For more information, see Handling Errors.

Add Group to Group Set

Adds group to a group set.

Version: Available in API 3.22 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

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

201

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.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the metric.
user-id The ID of the user to add the favorite for.

Request Body

                    <tsRequest>
  <favorite label="favorite-label">
    <metric id="metric-id" />
  </favorite>
</tsRequest>
				

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
metric-id The ID of the metric to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the metric (either explicitly or implicitly).

Response Code

200

Response Body

                    <tsResponse>
  <favorites>
    <favorite label="favorite-label">
      <metric id="metric-id" />
    </favorite>
    <favorite label="favorite-label">
      <metric id="metric-id" />
    </favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>
				

Version

Version 3.15 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 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden favorites access A non-administrator user called this method but doesn't have permission to add a metric to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
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.
404 404028 Metric not found The metric ID in the URI doesn't correspond to an existing metric.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different metric in the specified user's favorites.

For more information, see Handling Errors.

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.

URI

PUT /api/api-version/sites/site-id/projects/project-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
project-id The ID of the project to set permissions for.

Request Body

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

Attribute Values

user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name The capability to assign permissions to. In Tableau Server 10.0, the valid capabilities for a project are ProjectLeader, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Users who are not server administrators or site administrators can add permissions for a project only if they have ChangePermissions (version 2.0) or ProjectLeader (version 2.1) permission for that project (either explicitly or implicitly).

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:permissions:update

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <project id="project-id" name="project-name" />
      <owner id="project-owner-id" />
    </project>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>
        

Version

Version 2.0 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 400009 Invalid capability

The capability specified in the request is not in the list of valid capability names for this method.

The mode of the capability for ProjectLeader cannot be set to Deny.

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 ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the request body as the grantee doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
404 404009 Project ID mismatch A project ID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.)
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 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.

For more information, see Handling Errors.

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.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <project id="project-id"/>
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
project-id The ID (not name) of the project to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to add a project to a favorite list (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite1-label">
     <project id="project-id" />
    </favorite>
    <favorite label="favorite2-label">
     <project id="project-id" />
    </favorite>
  </favorites>
</tsResponse>

        

Version

Version 3.1 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 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Access to favorites denied A non-administrator user called this method but doesn't have permission to add a project to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
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.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/favorites/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -d @add-project-to-favorites.xml -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Content of add-project-to-favorites.xml:

<tsRequest>
  <favorite label="Economic Indicators">
    <project id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" />
  </favorite>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="Economic Indicators">
      <project id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
    </favorite>
  </favorites>
</tsResponse>

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

URI

PUT /api/api-version/sites/site-id/datasources/datasource-id/tags

Parameter Values

api-version The version of the API to use, such as 3.22. 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 add tags to.

Request Body

<tsRequest>
  <tags>
    <tag label="tag" />
    ... additional tags ...
  </tags>
</tsRequest>
        

Attribute Values

datasource-id The data source to add the tag to. If the data source is already tagged with a tag that's included in the request body, those tags are ignored and the data source retains them. If the <tags> element is empty, no new tags are added to the data source.
tag The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <tags>
    <tag label="tag"/>
        ... additional new tags ...
        ... existing tags ...
  </tags>
</tsResponse>

Version

Version 1.0 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 400075 Error adding tags There was a problem adding tags to the specified data source.
403 403004 Adding tags forbidden

A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty.

404 404000 Site not found

The site ID in the URI is not for an existing site.

404 404004 Data source not found The data source ID in URI doesn't correspond to an existing data source.
404 404009 Data source ID mismatch The request body contains a data source ID (which is optional) and it doesn't match the ID in the URI.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-datasource.xml

Content of add-tags-to-datasource.xml:

<tsRequest>
    <tags>
      <tag label="GDP" />
      <tag label="Health" />
    </tags>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <tags>
    <tag label="GDP"/>
    <tag label="Health"/>
    <tag label="Spending"/>
  </tags>
</tsResponse>

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

URI

PUT /api/api-version/sites/site-id/views/view-id/tags

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
view-id The ID of the views to add tags to.

Request Body

<tsRequest>
  <tags>
    <tag label="tag" />
    ... additional tags ...
  </tags>
</tsRequest>
        

Attribute Values

view-id The view to add the tag to. If the view is already tagged with a tag that's included in the request body, those tags are ignored and the view retains them. If the <tags> element is empty, no new tags are added to the view.
tag The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the view (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <tags>
    <tag label="tag"/>
        ... additional new tags ...
        ... existing tags ...
  </tags>
</tsResponse>

Version

Version 1.0 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 400076 Error adding tags There was a problem adding tags to the specified view.
403 403004 Adding tags forbidden

A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty.

404 404000 Site not found

The site ID in the URI is not for an existing site.

404 404011 View not found The view ID in URI doesn't correspond to an existing view.
404 404009 Workbook ID mismatch The request body contains a view ID (which is optional) and it doesn't match the ID in the URI.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-view.xml

Content of add-tags-to-workbook.xml:

<tsRequest>
    <tags>
      <tag label="GDP" />
      <tag label="Health" />
    </tags>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <tags>
    <tag label="GDP"/>
    <tag label="Health"/>
    <tag label="Spending"/>
  </tags>
</tsResponse>

Add Tags to Workbook

Adds one or more tags to the specified workbook.

URI

PUT /api/api-version/sites/site-id/workbooks/workbook-id/tags

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to add tags to.

Request Body

<tsRequest>
  <tags>
    <tag label="tag" />
    ... additional tags ...
  </tags>
</tsRequest>
        

Attribute Values

workbook-id The workbook to add the tag to. If the workbook is already tagged with a tag that's included in the request body, those tags are ignored and the workbook retains them. If the <tags> element is empty, no new tags are added to the workbook.
tag The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the workbook (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <tags>
    <tag label="tag"/>
        ... additional new tags ...
        ... existing tags ...
  </tags>
</tsResponse>

Version

Version 1.0 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 400049 Error adding tags There was a problem adding tags to the specified workbook.
403 403004 Adding tags forbidden

A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty.

404 404000 Site not found

The site ID in the URI is not for an existing site.

404 404006 Workbook not found The workbook ID in URI doesn't correspond to an existing workbook.
404 404009 Workbook ID mismatch The request body contains a workbook ID (which is optional) and it doesn't match the ID in the URI.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-workbook.xml

Content of add-tags-to-workbook.xml:

<tsRequest>
    <tags>
      <tag label="GDP" />
      <tag label="Health" />
    </tags>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <tags>
    <tag label="GDP"/>
    <tag label="Health"/>
    <tag label="Spending"/>
  </tags>
</tsResponse>

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

Version: Available in API 3.2 (Tableau Cloud / Tableau Server 2018.3) and later. Version Overview(Link opens in a new window)

License: No additional license required.>

Permissions: This method can only be called by server administrators and site administrators, and by users who are owners of the specified alert.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:data_driven_alerts:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

<tsRequest>
  <user id="user-id"/>
</tsRequest>
        

Response Code

200

Response Body

<tsResponse>
  <user id="user-id"
    name="user-name"
    siteRole="site-role"
    externalAuthUserId="external-user-id"/>
</tsResponse>
        

Errors

HTTP status error Code Condition Details
403 403004 Write forbidden A user called this method who does not have the required permissions.
403 409028 Adding recipient to data-driven alert forbidden The user is not authorized to add the recipient to the data-driven alert.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 Resource Not Found The user ID specified in the request body is invalid.
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-alert.xml

Content of add-user-to-alert.xml:

<tsRequest>
  <user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
</tsRequest>

Example response:


<tsResponse>
  <user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"
        name="admin"
        siteRole="ServerAdministrator"
        externalAuthUserId=""/>
</tsresponse>

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.

URI

POST /api/api-version/sites/site-id/groups/group-id/users

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to add the user to.

Request Body

Add a single user to a group

<tsRequest>
  <user id="user-id" />
</tsRequest>

Bulk add users to a group (beginning in API 3.21)

<tsRequest>
  <users>
	<user id="user-id1" />
	<user id="user-id2" />
	<user id="user-id2" />
  </users>
</tsRequest>

Attribute Values

user-id

The ID (not name) of the user to add. You can get the user ID by calling Get Users on Site.

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

Permissions

This method can only be called by server administrators and site 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:groups:update

Response Code

200

Response Body

Add a single user to a group

<tsResponse>
  <user id="user-id" name="user-name" siteRole="site-role" />
</tsResponse>

Bulk add users to group (beginning in API 3.21)

<tsResponse>
  <users>
	<user id="user-id"
     name="user-name"
     siteRole="site-role" />
	<user id="user-id"
	 name="user-name"
	 siteRole="site-role" />
  </users>
</tsResponse>

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

Version

Version 2.0 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.
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 name in the request body doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not POST.
409 409011 User conflict The specified user is already a member of the group.

For more information, see Handling Errors.

Example

Add a single user to a group

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-group.xml

Content of add-user-to-group.xml:

<tsRequest>
  <users id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
</tsRequest>

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
  <user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Adam"
        siteRole="Explorer" />
</tsResponse>
Bulk add users to a group (beginning in API 3.21)

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @bulk-add-user-to-group.xml

Content of bulk-add-user-to-group.xml:

<tsRequest>
  <users>
	<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
	<user id="1z4e8n7q-6t8t-8f8e-7d7c-1b1a2f2d2e2d" />
  </users>
</tsRequest>

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
 <users>
  <user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Adam"
        siteRole="Explorer" />
  <user id="11a1a1b1-be3a-4d2d-1e9e-08a7b6b5b5ba" name="Sadako"
		siteRole="Explorer" />
 <users>
</tsResponse>

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that is associated with the user you want to add to the identity pool.

Request Body

<tsRequest>
   <user
	name="user-name"
	siteRole="site-role"
	id="user-id"
	authSetting="authentication-configuration"
	identityPoolUuid="idpool-uuid"
	identityUuid="identity-uuid" />
</tsRequest>

Attribute Values

user-name

The name of the user to add.

site-role

Site role of the user. You can use one of the following values:

  • Creator
  • Explorer
  • ExplorerCanPublish
  • ServerAdministrator
  • SiteAdministratorExplorer
  • SiteAdministratorCreator
  • Unlicensed
  • ReadOnly
  • Viewer
user-id Required. The ID (not name) of the user to add. You can get the user ID by calling Get Users on Site.
authentication-configuration The authentication configuration instance configured for the identity pool you want to add the user to. You can get the authentication configuration instance by calling List Authentication Configurations(Link opens in a new window) endpoint in Tableau REST OpenAPI.
idpool-uuid The ID of the identity pool that you wan to add the user to. You can get the identity pool ID by calling the List Identity Pools(Link opens in a new window) endpoint in the Tableau REST OpenAPI.
identity-uuid The identifier for the user you want to add. Identifiers are only used for identity matching purposes. For more information about identifiers, see Usernames and Identifiers in Tableau(Link opens in a new window) in the Tableau Server Help.

Permissions

This method can only be called by Tableau Server administrators.

Response Code

200

Response Body

Example response:

<tsResponse>
  <user
	identityPoolUuid="df47cf24-5ed3-11ed-9b6a-0242ac12000"
	id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a"
	name="Michele Kim" />
</tsResponse> 

Version

Version 3.19 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.
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 POST.
429 429001 User conflict The specified user is already a member of the identity pool.
429 429002 Can't add user There was a problem and the user couldn't be added to the identity pool.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/identityPool" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-idpool.xml

  • MY-SERVER is the name or IP address of your server.
  • 9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d is the ID of the site, as returned by a previous call to Sign In.
  • 12ab34cd56ef78ab90cd12ef34ab56cd is the credentials token returned by a previous call to Sign In.

Content of add-user-to-idpool.xml:

<tsRequest>
  <user id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a" />
</tsRequest>

Example response:

<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
  <user identityPoolUuid="7b54b6a8-6095-11ed-9b6a-0242ac120002"
     id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a" name="Michele Kim" />
</tsResponse>

Add User to Site

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

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.

When you add 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.

URI

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

Parameter Values

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

Request Body

<tsRequest>
  <user name="user-name"
        siteRole="site-role"
        authSetting="auth-setting" />
</tsRequest>
        

Attribute Values

user-name

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.

site-role

The site role to assign to the user. You can assign the following roles: Creator, Explorer, ExplorerCanPublish, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role).

auth-setting

(Optional) The authentication type for the user.

(For Tableau Server: This attribute only applies when adding users to sites with site-specific SAML enabled in settings.)

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).
  • OpenID - Tableau Cloud only the user signs in using Google, Salesforce, or their OpenID 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 TableauID credentials and a registered verification method. For more information, see About multi-factor authentication and Tableau Cloud(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, if Tableau hasn't updated your site to require Tableau with MFA yet, you can continue to use this authentication type on a temporary basis. The ServerDefault value corresponds to TableauID in authentication settings. For Tableau Server, the SAML(Link opens in a new window) Server help page describes default authentication options.

Permissions

This method can only be called by server administrators and site 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:users:create

Response Code

201

Response Body

<tsResponse>
  <user id="user-id"
   name="user-name"
   siteRole="site-role"
   authSetting="auth-setting" />
</tsResponse>
        

Response Headers

Location: /api/3.22/sites/site-id/users/new-user-id

Version

Version 1.0 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 400003 Bad request The user authentication setting ServerDefault is not supported for you site. Try again using TableauIDWithMFA instead.
400 400013 Invalid site role

The value of the siteRole attribute must be Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The server is configured to use Active Directory for authentication, and the username specified in the request body doesn't match an existing user in Active Directory.
405 405000 Invalid request method Request type was not POST.
409 409000 User conflict The specified user already exists on the site.
409 409005 Guest user conflict The Tableau Server API doesn't allow adding a user with the guest role to a site.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-site.xml

  • MY-SERVER is the name or IP address of your server.
  • 9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d is the ID of the site to add the user to, as returned by a previous call to Sign In.
  • 12ab34cd56ef78ab90cd12ef34ab56cd is the authentication returned by a previous call to Sign In.

Content of add-user-to-site.xml:

<tsRequest>
  <user name="Adam"
    siteRole="Explorer" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"
    name="Adam"
    siteRole="Explorer"
    authSetting="ServerDefault"  />
</tsResponse>

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.

URI

PUT /api/api-version/sites/site-id/views/view-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook view.
view-id The ID of the view to set permissions for. You can obtain this ID by calling Query Views for Site.

Request Body

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

Attribute Values

view-id The view-id value must match the view ID in the URI.
user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. For valid capabilities for a view are AddComment, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

This method can only be called by server and site administrators, and user who have permission to set permissions on the workbook (either explicitly or implicitly). To use this method, the parent workbook that contains the specified view must have its showTabs attribute set to Hide. You can configure this setting by using the Update Workbook method.

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:permissions:update

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <view id="view-id" />
      <owner id="owner-id"/>
    </view>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <capability name="capability-name" mode="capability-mode" />
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <capability name="capability-name" mode="capability-mode" />
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
          </capabilities>
          </granteeCapabilities>
  </permissions>
</tsResponse>
        

The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.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 XML.
400 400009 Invalid capability The capability in the URI is invalid for a view.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the view.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404011 View not found The view ID in the URI 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 an invalid capability value (other than Allow or Deny).
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/13020592-762f-4de4-a25e-f4beb005836e/views/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-view-permissions.xml

Example of add-view-permissions.xml:

<tsRequest>
  <permissions>
    <view id="34acb0d7-fa37-43d7-bdde-d6635eb724b5" />
    <granteeCapabilities>
      <user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" />
      <capabilities>
        <capability name="ExportImage" mode="Allow" />
        <capability name="ChangePermissions" mode="Deny" />
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsRequest>

Example response:

<tsResponse>
  <permissions>
    <view id="34acb0d7-fa37-43d7-bdde-d6635eb724b5" name="What If Forecast">
      <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
    </view>
    <granteeCapabilities>
      <group id="2aa47cfa-9f2b-11e8-a260-af4a26124661"/>
      <capabilities>
        <capability name="ShareView" mode="Allow"/>
        <capability name="ViewComments" mode="Allow"/>
        <capability name="Filter" mode="Allow"/>
        <capability name="ExportData" mode="Allow"/>
        <capability name="Read" mode="Allow"/>
        <capability name="AddComment" mode="Allow"/>
        <capability name="ViewUnderlyingData" mode="Allow"/>
        <capability name="ExportImage" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
      <capabilities>
        <capability name="ExportImage" mode="Allow"/>
        <capability name="ChangePermissions" mode="Deny"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

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.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <view id="view-id" />
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
view-id The ID (not name) of the view to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to add a view to a favorite list (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite-labe1">
	  <view id="view-id"
	    name="view-name"
    	contentUrl="content-url"
	    createdAt="created-at"
		updatedAt="updated-at"
  		viewUrlName="view-url-name">
		  <workbook id="workbook-luid"/>
		  <project id"project-luid"/>
		  <tags />
	  </view>
	</favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>
        

The value of view-url-name is the name of the view in its URL. For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1 in your browser address bar, then the view-url-name would be VIEW_1. Modifying the name (display name) of a view will not impact the view-url-name (path element of the view's URL).

Version

Version 1.0 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 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden Favorites access A non-administrator user called this method but doesn't have permission to add a view to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
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.
404 404011 View not found The view ID in the request body doesn't correspond to an existing view.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different view of the same workbook in the specified user's favorites.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/favorites/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X PUT -d @add-view-to-favorites.xml -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Content of add-view-to-favorite.xml:

<tsRequest>
  <favorite label="Economic Indicators">
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" />
  </favorite>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="DC Crimespotting">
	  <view id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="Crimes_DC"
		contentUrl="content-url"
		createdAt="created-at"
		updatedAt="updated-at"
		viewUrlName="view-url-name">
		  <workbook id="abb3e4c1-e650-4704-870a-03fb7615136f"/>
		  <project id"3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"/>
		  <tags />
	  </view>
    </favorite>
    <favorite label="Economic Indicators">
      <view id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
    </favorite>
  </favorites>
</tsResponse>

Add Workbook Permissions

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

URI

PUT /api/api-version/sites/site-id/workbooks/workbook-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to set permissions for.

Request Body

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

Attribute Values

workbook-id The <workbook> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <workbook> element is included, the workbook-id value must match the workbook ID in the URI. Any other attributes in the <workbook> element are ignored.
user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name

The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

For more information, see Permissions.

capability-mode Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

Users who are not server administrators or site administrators can call this method only if the have permission to set permissions on the workbook (either explicitly or implicitly).

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:permissions:update

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <workbook id="workbook-id" />
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>
        

Version

Version 2.0 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 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 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
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.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

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.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <workbook id="workbook-id" />
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server. If the label is already in use for another workbook, an error is returned.
workbook-id The ID (not name) of the workbook to add as a favorite.

Permissions

Tableau Server users who are not administrators or site administrators can call this method only if they have permission to add a workbook to a favorites list.

Response Code

200

Response Body

<tsResponse>
  <favorites>
      <favorite label="favorite-label">
        <workbook id="workbook-id" />
      </favorite>
      <favorite label="favorite">
        <view id="view-id" />
      </favorite>
      ... additional favorites ...
  </favorites>
</tsResponse>
        

Version

Version 1.0 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 400005 Invalid label

The favorite label is empty or consists of only white space characters.

403 403004 Access to Favorites forbidden

A non-administrator user called this method but doesn't have permission to add a workbook to the specified user's favorites. This will always be the case when the user references in the URI identifies a user other than the user who is calling the method.

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.
404 404006 Workbook not found The workbook ID in the request body doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different workbook in the specified user's favorites.

For more information, see Handling Errors.

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.

URI

PUT /api/api-version/sites/site-id/schedules/schedule-id/workbooks

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
schedule-id The ID of the schedule that you are associating with the workbook.

Request Body

<tsRequest>
  <task>
    <extractRefresh>
      <workbook id="workbook-id" />
    </extractRefresh>
  </task>
  <task>
    <dataAcceleration>
      <workbook id="workbook-id" />
    </dataAcceleration>
  </task>
</tsRequest>

Attribute Values

workbook-id The ID of the workbook to add to the schedule.

Permissions

Only Tableau Server users who are server administrators or site administrators can add a workbook to a data acceleration schedule. Tableau Server users who are not server administrators or site administrators can only add a workbook to other types of schedules if they own the workbook, or are the project leader for the project that contains the workbook.

Response Code

200

Response Body

<tsResponse>
  <task>
    <extractRefresh id="extractRefresh-id" type="extractRefresh-type">
      <schedule id="schedule-id" />
      <workbook id="workbook-id" />
    </extractRefresh>
  </task>
</tsResponse>
        

Version

Starting in Tableau Server 10.5 (API 2.8) you can add a task to refresh a workbook extract. In Tableau Server 2020.2 (API 3.8) through 2021.4 (API 3.15), you can add a task to add data acceleration to a workbook.

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.

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 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404006 Resource not found The workbook ID in the request body is unknown.
405 405000 Invalid request method Request type was not PUT.
500 500000 Internal Server Error The schedule ID in the URI is unknown.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/ 1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/workbooks" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"

Content of add-to-schedule.xml:

<tsRequest>
  <task>
    <extractRefresh>
      <workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
    </extractRefresh>
  </task>
</tsRequest>

Example response:

<tsResponse>
  <task>
    <extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
      <schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
      <workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
    </extractRefresh>
  </task>
</tsResponse>

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.


Adds a dashboard extension to the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: This method can only be called by users with server or Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

PUT /api/api-version/sites/site-id/fileUploads/upload-session-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to upload the file to.
upload-session-id The ID of the upload session. You get this value when you start an upload session using Initiate File Upload.

Request Body

The content of the file to be uploaded is included in a MIME multipart message. For more information, see Publishing Resources.

Permissions

Users who are not server administrators or site administrators can call this method only if they have publishing rights on the site.

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:file_uploads:create

Response Code

200

Response Body

<tsResponse>
  <fileUpload uploadSessionId=upload-session-id
              fileSize=size-of-file-in-megabytes-after-append />
</tsResponse>
        

Version

Version 2.0 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 400016 File size too large The attached file exceeds the configured maximum attachment size for a single append call. The maximum allowable size will be reported in the error response.
400 400019 Malformed request body The XML content in the MIME multipart request is not empty.
400 400020 Missing file data There is no attachment in the request with the file data to be appended to the upload.
403 403007 Not a publisher A non-administrator user attempted to initiate a file upload, but the caller doesn't have publishing rights on the site.
403 403016 Upload failure The file could not be uploaded for some other reason than those specified earlier.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404015 File upload not found The file upload ID in the URI doesn't correspond to an existing file upload.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Batch Add or Update Data Quality Certifications

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

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

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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.22. 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.22. 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.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user that has read or connect permission to Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:create
Access Scopes Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user that has read or connect permission to Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:read
Access Scopes Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user that has read or connect permission to Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:read
Access Scopes Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Batch list metric definitions

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

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions_metrics:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can get a batch of metrics as long as the user Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:read
Access Scopes Overview: Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.


Adds a dashboard extension to the block list of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Cancel Flow Run

Cancels a flow run that is in progress.

URI

PUT /api/api-version/sites/site-id/flows/runs/flow-run-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-run-id The ID of the flow run.

Request Body

None

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
403 403135 Flow run already complete The flow run is already complete so it could not be canceled.
403 403137 User does not have permissions to cancel flow run In addition to server administrators and site administrators, users can cancel a flow run if they initiated the flow run or created the flow run scheduled task and have "Run Flow Now" permissions for the flow.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404036 Flow run not found The flow run ID in the URI doesn't correspond to an existing flow run.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

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

URI

PUT /api/api-version/sites/site-id/jobs/job-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site where the job is running.
job-id The ID of the job to cancel.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403032 Update forbidden A non-administrator user tried to cancel a job.
403 403091 Can not cancel job, because it's already complete. The job ID provided is for a job that has already succeeded or failed.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/jobs/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Configure Identity Store

Configure a new local identity store to provision users.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Create a Webhook

Creates a new webhook for a site.

URI

POST /api/3.6/sites/<site-id>/webhooks

Parameter Values

site-id The ID of the site in which you want to create the webhook.  

Request Body

<tsRequest>
  <webhook
    name="webhook-name"
    isEnabled="webhook-enabled-flag"
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url"/>
     </webhook-destination>
  </webhook>
</tsRequest>

Attribute Values

webhook-name This is required. A name for the webhook.
api-event-name | webhook-source-api-event-name

You must specify one of these attribute values. The name of the Tableau event that triggers your webhook. The event name must be one of the supported events listed in the Trigger Events table. The event and webhook-source use different name values for the same event. 

Recommended: Use the event attribute of the webhook to specify the triggering API event for the webhook. The webhook-source element serves the same purpose but is being deprecated in future versions of Tableau webhooks. If both events and webhook-source are specified, their events specified must match. If either are specified, with the other being NULL, then the specified event becomes the webhook trigger, whether the element containing the event name is event or webhook-source.

url Required. The destination URL for the webhook. The webhook destination URL must be https and have a valid certificate.
webhook-enabled-flag (Optional) Boolean. If true (default), the newly created webhook is enabled. If false then the webhook will be disabled.  

Permissions

This method can only be called by server and site administrators.

Response Code

200

Response Body

<tsResponse>
  <webhook
    id="webhook-id"
    name="webhook-name"
    isEnabled="true-or-false"
    statusChangeReason="status-change-reason"
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url"/>
      </webhook-destination>
        <owner id="webhook_owner_luid" name="webhook_owner_name"/>
  </webhook>
</tsResponse>

Response Headers

Location: /api/3.22/sites/site-id/webhooks/<new-webhook-id>

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.

URI

POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract

POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract?encrypt=encryption-flag

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The LUID of the site.
datasource-id The LUID of the datasource.
encryption-flag If true, then Tableau will attempt to encrypt the created extracts. If false, or no encrypt parameter is appended to the URI, then the extract won't be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when encrypt equals true and encryption is disabled in the site or workbook.

Request Body

None

Permissions

Extracts for data sources can be created by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

Response Code

200

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
    <extractCreationJob>
	  <datasource id="datasource-id" name="datasource-name" />
  </extractCreationJob>
</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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"

Response body:

<tsResponse>
  <job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
    <extractCreationJob>
        <datasource id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_DATASOURCE_NAME"/>
      <jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
    </extractCreationJob>
  </job>
</tsResponse> 

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.


Create an ask data lens.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can be called by users who have Create permissions for lenses on the site. Permissions Overview

License: No additional license required.

Access Scope: `tableau:lenses:create` Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Create Authentication Configuration

Create an instance of OpenID Connect (OIDC) authentication.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Administrators and any user with the creator role can create a custom schedule for an extract refresh.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:tasks:create (this scope is included in the scope: tableau:tasks)
    Access Scopes Overview: Cloud(Link opens in a new window)

URI

POST /api/api-version/sites/site-luid/tasks/extractRefreshes

URI Parameter Values

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

Request Body

Copy
<tsRequest>
  <extractRefresh type="FullRefresh">
    <workbook id="54321fd-6365-44d5-925b-644e5281b605" />
  </extractRefresh>
  <schedule frequency="Daily">
    <frequencyDetails start="18:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Sunday"/>
        <interval weekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Copy
{
  "extractRefresh": {
    "type": "FullRefresh",
    "workbook": {
      "id": "54321fd-6365-44d5-925b-644e5281b605"
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }

Request Attributes

All request attributes are required to create a custom schedule for an extract refresh.

extractRefresh type enumeration: The type of extract refresh being scheduled. Valid values include:
  • FullRefresh
  • IncrementalRefresh
workbook id
or datasource id
LUID: The LUID of the workbook or datasource that is the target of the custom schedule.
schedule frequency enumeration: The scheduled frequency for triggering the extract refresh. Valid values include:
  • Hourly
  • Daily
  • Weekly
  • Monthly
frequencyDetails start time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.
frequencyDetails end

time: If the schedule frequency is Hourly, or Daily with an interval of hours less than 24, then end is the time of day on which scheduled jobs should stop being run. The valid format is HH:MM:SS. Time should be specified in 5 minute increments and the difference between start and end times should be increments of 60 minutes. For example, a valid frequencyDetail would be:

<frequencyDetail start="20:45:00" end="21:45:00">
    . . . 
</frequencyDetail>
interval {interval type} string: Defines when and how often a scheduled job executes within the time parameters set in the start and end values of the frequencyDetails of the schedule. The type and valid values for an interval expression depend on the declared frequency of the schedule as follows:

FrequencyValid interval values
Hourly The value of an interval for an Hourly schedule can be only one of either:
  • hours=“1" The number of hours between jobs. 1 is the only valid value.
  • minutes=“60" The number of minutes between jobs. 60 is the only valid value.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday.

    For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="1"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
     <intervals>
Daily The value of Daily can have multiple weekday elements, but only one hours declaration. An hours interval is required.
  • hours=“interval" The interval between execution of jobs on the weekday(s) specified. Valid values are 2, 4, 6, 8, 12, or 24. Note that if the interval value of a daily schedule is less than 24, a frequencyDetail end time must be supplied.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

    For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="4"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
    <intervals>
WeeklyweekDay=“weekday" The day of the week the schedule should run on. Multiple days can be specified for a Weekly schedule. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.
Monthly

The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval:

Specify the day(s) using the number of the day in the month;

  • monthDay=“day" The number of the day of the month. Valid values are the whole numbers 1 to 31 or LastDay. If you specify monthDay by day number then you can use multiple interval instances to choose for the job to run on multiple days in the month. If you use LastDay then only one instance of interval can be used in the schedule to specify the last day of the month. For example, to make a schedule that that would run a job on the first and fifteenth of each month, you would use:
    Copy
    <intervals/>
      <interval monthDay="1"/>
      <interval monthDay="15"/>
    </intervals/>

Specify the day by describing which occurrence of a weekday within the month.

  • monthDay=“occurrence_of_weekday" Weekday=“weekday" The occurrence of the specified weekday within the month when a job should be run. Valid values for occurrencee_of_weekday are First, Second, Third, Fourth, Fifth, or LastDay. Valid values for weekday are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday. If the value is lastDay then the job will run on the last occurrence of the specified weekday in the month.

    For example, to make a schedule that that would run a job on the third Thursday of each month, you would use:
    Copy
    <interval monthDay="Third" weekDay="Thursday"/>

cURL Request Example

curl --location --request POST "qa-near.tsi.lan/api/3.22/sites/a946d998-2ead-4894-bb50-1054a91dcab3/tasks/extractRefreshes" --header "Content-Type: application/xml" --data "<tsRequest> <extractRefresh type='FullRefresh'> <workbook id='0057ccac-872a-11e5-bb51-f763326b1350' /> </extractRefresh> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> </intervals> <intervals> <interval weekDay='Sunday'/> </intervals> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"

Response Code

200

Response Body

Copy
<tsResponse>
  <extractRefresh 
    id="13237fd-6365-44d5-925b-644e5281b605"
    consecutiveFailedCount="0"
    type="IncrementalRefresh" >
      <datasource id="0057ccac-872a-11e5-bb51-f763326b1350" />
  </extractRefresh>
  <schedule id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
    createdAt="2023-04-06T23:43:12-0700"
    updatedAt="2023-04-06T23:43:12-0700"
    frequency="Daily"
    nextRunAt="2023-04-06T23:43:12-0700">
        <frequencyDetails start="18:30:00" end="23:30:00">
        <intervals>
          <interval hours="4"/>
          <interval weekDay="Sunday"/>
          <interval weekDay="Wednesday"/>
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
Copy
{
  "extractRefresh": {
    "id": "13237fd-6365-44d5-925b-644e5281b605",
    "consecutiveFailedCount": "0",
    "type": "IncrementalRefresh",
    "datasource": {
      "id": "0057ccac-872a-11e5-bb51-f763326b1350"
    }
  },
  "schedule": {
    "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
    "createdAt": "2023-04-06T23:43:12-0700",
    "updatedAt": "2023-04-06T23:43:12-0700",
    "frequency": "Daily",
    "nextRunAt": "2023-04-06T23:43:12-0700",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}

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

URI

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

Note: Deprecated in API 3.17 - the following resource is no longer supported and will be retired in future releases: 

URI POST api/api-version/sites/site-id/connected-applications

Parameter Values

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

Request Body

Tableau Cloud

<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 REST 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, 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 REST API 3.21 (or earlier)), specify the projectId parameter and its value.

  • Multiple projects: For Tableau Cloud only, beginning with REST API version 3.22 (February 2024), you can specify the projectIds attribute and projectId values to scope the connected app's access to multiple projects.

  • All projects:

    • For Tableau Cloud, 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 REST 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: For Tableau Cloud, 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.

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 version 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: Deprecated in API 3.17 - the following resource is no longer supported and will be retired in future releases: 

URI POST api/api-version/sites/site-id/connected-applications/client-id/secrets

Parameter Values

api-version The version of the API to use, such as 3.22. 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.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Users with the Administrator, Creator, or Explorer role can add DDAs to views they have permissions to.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:data_driven_alerts:create     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.20 and later Tableau Cloud June 2023). Not available for Tableau Server.

URI

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

URI Parameter Values

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

Request Body

Copy
<tsRequest>
  <dataAlertCreateAlert
    alertCondition="above"
    alertThreshold="14000"
    subject="Data Driven Alert for Forecast"
    frequency="daily"    
    visibility="public"
    device="desktop"
    worksheetName="one_measure_no_dimension"
    viewId="my-view-id"
    <!-- OR customViewId="my-custom-view-id"> -->
  /> 
</tsRequest>

Copy
{
  "dataAlertCreateAlert": {
    "alertCondition": "above",
    "alertThreshold": "14000",
    "subject": "Data Driven Alert for Forecast",
    "frequency": "daily",
    "visibility": "public",
    "device": "desktop",
    "worksheetName": "one_measure_no_dimension",
    "viewId": "my-view-id"
    // can be "customViewId" instead
  }
}

Request Attributes

dataAlertCreateAlert alertCondition

(Required) Enumeration: The condition that triggers the DDA. Used in conjunction with the threshold to determine when to trigger an alert. For example, an alert can be triggered if on the condition that data is above or equal to a threshold of 1000 orders. The value can be:

  • above
  • above-equal
  • below
  • below-equal
  • equal
dataAlertCreateAlert alertThreshold (Required) Int: The data value where an alert should be triggered when that value drops below or rises above the alert threshold value.
dataAlertCreateAlert subject (Required) String: The name of the data driven alert.
dataAlertCreateAlert frequency

(Required) Enumeration: The time period between attempts by Tableau to assess whether the alert threshold has been crossed. The value can be one of:

  • once Sends the alert only the first time the alert threshold is crossed.
  • freguently As frequently as possible given server conditions.
  • hourly
  • daily
  • weekly
dataAlertCreateAlert visibility (Required) Enumeration: Determines whether the alert can be seen by only its creator (private), or by any user with permissions to the worksheet where the alert resides (public) . The value can be one of:
  • private
  • public
dataAlertCreateAlert device

(Optional) Enumeration: The type of device the alert is formatted for. If no device is provided then the default device setting of the underlying view is used. Values can be one of:

  • desktop
  • phone
  • tablet
dataAlertCreateAlert worksheetName

(Required) String: The name of the worksheet that the DDA will be created on.

For dashboards, this is the name of the underlying sheet that contains the data whose value can trigger the alert, not the name of the dashboard that presents that sheet.

For custom views, the name of the original view that was used to form the custom view.

dataAlertCreateAlert viewId

OR

dataAlertCreateAlert customViewId

(Required) LUID: The LUID of either the viewId or customViewId that contains the data that can trigger an alert.

cURL Request Example

curl http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy
<tsRequest>
  <dataAlertCreateAlert
    alertCondition="above"
    alertThreshold="14000"
    subject="Data Driven Alert for Forecast"
    frequency="daily"    
    visibility="public"
    device="desktop"
    worksheetName="one_measure_no_dimension"
    viewId="my-view-id"
    <!-- OR customViewId="my-custom-view-id"> -->
  /> 
</tsRequest>
Copy
{
  "dataAlertCreateAlert": {
    "alertCondition": "above",
    "alertThreshold": "14000",
    "subject": "Data Driven Alert for Forecast",
    "frequency": "daily",
    "visibility": "public",
    "device": "desktop",
    "worksheetName": "one_measure_no_dimension",
    "viewId": "my-view-id"
    // can be "customViewId" instead
  }
}

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

URI

POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract

POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract?encrypt=encryption-flag

Path Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The LUID of the site.
workbook-id The LUID of the workbook.
encryption-flag If true, then Tableau will attempt to encrypt the created extracts. If false, or no encrypt parameter is appended to the URI, then the extract won't be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when encrypt equals true and encryption is disabled in the site or workbook.

Request Body

<tsRequest>
  <datasources includeAll="extract-all-datasources-flag">
	<datasource id="datasource-id" />
  </datasources>
</tsRequest>
        

Request Parameter Values

datasource-id LUID of the embedded data source to be extracted.
extract-all-datasources-flag Boolean. If true, then all data sources in the workbook will have an extract created for them. If false, then a data source must be supplied in the request.

Permissions

Extracts for data sources embedded in a workbook can be created by Tableau server or site administrators, and users who own the workbook, or are an owner or leader of the project where the workbook resides.

Response Code

200

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
    <extractCreationJob>
      <workbook id="workbook-id" name="workbook-name" />
	</extractCreationJob>
  </job>
</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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@create-extracts-for-workbook.xml"

Content of create-extracts-for-workbook.xml

<tsResponse>
  <datasources includeAll="false" />
    <datasource id="6b4cf715-c90b-49d6-be85-920a47bae433" />
  </datasources>
</tsRequest>

Response body:

<tsResponse>
  <job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
	<extractCreationJob>
	  <workbook id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_WORKBOOK_NAME"/>
	  <jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
    </extractCreationJob>
  </job>
</tsResponse>

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.

URI

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

POST /api/api-version/sites/site-id/groups?asJob=asJob-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to create the group in.
asJob-value A Boolean value that is used if you are importing from Active Directory. If you set this to false (the default), the import process runs as a synchronous process. If the Active Directory group contains many users, the process might time out before it finishes.

If you set this to true, the process runs asynchronously. In that case, Tableau Server starts a job to perform the import and returns the job ID in the Location header. You can check the status of the import job by calling Query Job.

Note: This parameter has no effect if the server is configured to use local authentication.

This attribute is available for Tableau Server only.

Request Body

Creating a local group

<tsRequest>
  <group name="new-tableau-server-group-name"
   minimumSiteRole="minimum-site-role"
   ephemeralUsersEnabled="on-demand-access"/>
</tsRequest>

        

When the request is to create a local group and minimumSiteRole is specified, users are granted a license using the grant license on-login mode by default.

Importing a group from Active Directory (Tableau Server only)

<tsRequest>
  <group name="active-directory-group-name" >
    <import source="ActiveDirectory"
      domainName="active-directory-domain-name"
      grantLicenseMode="license-mode"
      siteRole="minimum-site-role"/>
  </group>
</tsRequest>
        

When the request is to create a group with grantLicenseMode, a siteRole value should also be supplied.

When the request body contains an <import> element, a Tableau Server configured to authenticate via Active Directory will create the group and modify the set of users in the group to be the same as those in Active Directory. The source attribute of the <import> element must be set to ActiveDirectory. If Tableau Server or Tableau Cloud site is configured to use local authentication, including an <import> element has no effect.

Note: When a group is created by importing from Active Directory, Tableau Server uses the value of the Active Directory sAMAccountName attribute as the user name.

Attribute Values

new-tableau-server-group-name The name for the new group.
active-directory-group-name

The name of the Active Directory group to import.

This attribute is available for Tableau Server only.

active-directory-domain-name

The domain of the Active Directory group to import.

This attribute is available for Tableau Server only.

minimum-site-role

Required if an import element or grantLicenseMode attribute are present in the request. For Tableau Server, the site role assigned to users who are imported from Active Directory or granted a license automatically using the grant license on-sync or on-login mode.

If the requested user name matches an existing user in the group, the user either retains their existing role or are granted the one specified in the request, based on the role that enables the most capabilities. This is true whether the group the user belongs to is imported from Active Directory (Tableau Server only) or local.

Site roles that can be assigned, listed from the one enabling the least capabilities to the most, are as follows.

  1. Unlicensed
  2. Viewer
  3. Explorer
  4. ExplorerCanPublish
  5. Creator
  6. SiteAdministratorExplorer
  7. SiteAdministratorCreator

Note: You cannot use the REST API to set a user to be a Tableau Server administrator (ServerAdministrator site role).

license-mode

The mode for automatically applying licenses for group members. When the mode is onLogin, a license is granted for each group member when they log in to a site.

For local groups, the mode can be either onLogin or unset. If the attribute is omitted, the default mode is unset, which results in no licenses being granted automatically to group members.

For groups that import an Active Directory domain, the mode can be either onSync or onLogin.

The minimum role granted to users through grantLicenseMode is specified in the siteRole attribute. If that role has less permissions than an existing role assigned to the user, then the user's permissions remain unchanged.

on-demand-access

Optional. A boolean value that is used to enable on-demand access for embedded Tableau content when the Tableau Cloud site is licensed with Embedded Analytics(Link opens in a new window) usage-based model. Set to true to enable the capability for the group or set to false to disable the capability for the group. For more information about on-demand access, see one of the following topics in the Tableau Cloud Help: On-demand access using connected apps with direct trust(Link opens in a new window) or On-demand access using connected apps with OAuth 2.0 trust(Link opens in a new window).

This attribute is available for Tableau Cloud only starting from API version 3.21 (October 2023).

Permissions

This method can only be called by Tableau Server administrators or Tableau Cloud site admins.

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:groups:create

Response Code

201, for creating a local group and for importing immediately

202, for importing using a background process

Response Headers

Location: /api/3.22/sites/site-id/groups/new-group-id

Response Body

Creating a local group:

<tsResponse>
  <group id="new-group-id"
	name="group-name"
	minimumSiteRole="minimum-site-role"
	ephemeralUsersEnabled="true" />
	<import domainName="local" siteRole="default-site-role" grantLicenseMode="license-mode" />
  </group>
</tsResponse>
        

Creating a group and importing from Active Directory immediately (Tableau Server only):

<tsResponse>
  <group id="new-group-id"
    name="group-name">
	  <import domainName="active-directory-domain-name”
        siteRole="default-site-role"
	 grantLicenseMode="onLogin" />
  </group>
</tsResponse>
        

Importing as a background process:

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="GroupImport"
    progress="0" createdAt="time-job-created" />
</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.
400 400013 Invalid site role

The value of the minimumSiteRole or siteRole attribute must be Creator, Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

400 400019 Malformed import element When the <import> element is present in the request body, the following attributes must be specified: source with the value ActiveDirectory; domainName; and siteRole If any of these is missing, the element is malformed.
403 403011 Active Directory is not configured The <import> element is present, but Tableau Server is configured for local authentication.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404016 Domain not found The request body includes an <import> element, but the specified domain name doesn't exist in Active Directory.
404 404017 Active Directory group not found The request body includes an <import> element, but no group exists in Active Directory that matches the specified group name.
405 405000 Invalid request method Request type was not POST.
409 409009 Group name conflict The group name in the request already belongs to the specified site. For the purpose of uniqueness checks, group names are case-insensitive.

For more information, see Handling Errors.

Example: Local Group

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-local-group.xml

Content of create-local-group.xml:

<tsRequest>
  <group name="marketing-group" ephemeralUsersEnabled="true" />
</tsRequest>

Response header:

Location: /api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d

Response body:

<tsResponse version-and-namespace-settings>
  <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group" ephemeralUsersEnabled="true"/>
</tsResponse>

Example: Active Directory Group

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-ad-group.xml

Content of create-ad-group.xml:

<tsRequest>
  <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group">
    <import domainName="MY-DOMAIN" siteRole="Viewer" grantLicenseMode="onLogin" />
  </group>
</tsRequest>

Response header:

Location: /api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d

Response body:

<tsResponse version-and-namespace-settings>
  <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group">
	  <import domainName="MY-DOMAIN" siteRole="Viewer" grantLicenseMode="onLogin" />
  </group>
</tsResponse>

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.

Version: Available in API 3.22 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:create     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

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

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to create the group in.

Request Body

XML

Copy
<tsRequest>
  <groupSet name="newGroupSet" />
</tsRequest

JSON

Copy
{
  "groupSet": {
    "@name": "marketing-group"
  }
}

Request Attributes

name

(Required) Name of the new group set.

cURL Request Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/" --header "Content-Type: application/xml" --header "X-Tableau-Auth: YqB9_MHoTHO26HGsFBFEBg|bQDOIH4MsqFGvUDYTrRYh633vrZHBt6d|a946d998-2ead-4894-bb50-1054a91dcab3" --data "<tsRequest> <groupSet name='marketing-group' /> </tsRequest>"

Response Code

201, for creating a group set.

Response Body

Copy
<tsRequest>
  <groupSet id="4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234" 
    name="marketing-group" 
    groupCount="0" />
</tsRequest>
Copy
{
  "groupSet": {
    "id": "4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234",
    "name": "marketing-group",
    "groupCount": "0"
  }
}

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 400013 Invalid site role

The value of the minimumSiteRole or siteRole attribute must be SiteAdministratorCreator or SiteAdministratorExplorer.

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method The request type wasn’t POST.
409 409121 Group set name conflict The group set name in the request already belongs to another group set. For the purpose of uniqueness checks, group set names are case-insensitive.

For more information, see Handling Errors.

Create Identity Pool

Create an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.22. 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 Cloud. Must be 1-24 characters long in Tableau Server.

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 Cloud.
  • The category name must be 1-24 characters long in Tableau Server.
  • 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.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:create
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Create metric definition

Creates a metric definition.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can create a metric definition as long as the user has write or publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions:create
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server.Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Cloud site admins only.

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/site-oidc-configuration

URI Parameter Values

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

Request Body

Copy
<tsRequest>
  <siteOIDCConfiguration
    enabled="enabled"
    clientId="clientId"
    clientSecret="clientSecret"
    authorizationEndpoint="authorizationEndpoint"
    tokenEndpoint="tokenEndpoint"
    userinfoEndpoint="userinfoEndpoint"
    jwksUri="jwksUri"
    endSessionEndpoint="endSessionEndpoint"
    allowEmbeddedAuthentication="allowEmbeddedAuthentication"
    prompt="prompt"
    customScope="customScope"
    clientAuthentication="clientAuthentication"
    essentialAcrValues="essentialAcrValues"
    voluntaryAcrValues="voluntaryAcrValues"
    emailMapping="emailMapping"
    firstNameMapping="firstNameMapping"
    lastNameMapping="lastNameMapping"
    fullNameMapping="fullNameMapping"
    useFullName="useFullName" />
</tsRequest>

Copy
{
  "siteOIDCConfiguration": {
    "enabled": "enabled",
    "clientId": "clientId",
    "clientSecret": "clientSecret",
    "authorizationEndpoint": "authorizationEndpoint",
    "tokenEndpoint": "tokenEndpoint",
    "userinfoEndpoint": "userinfoEndpoint",
    "jwksUri": "jwksUri",
    "endSessionEndpoint": "endSessionEndpoint",
    "allowEmbeddedAuthentication": "allowEmbeddedAuthentication",
    "prompt":"prompt",
    "customScope":"customScope",
    "clientAuthentication": "clientAuthentication",
    "essentialAcrValues": "essentialAcrValues",
    "voluntaryAcrValues": "voluntaryAcrValues",
    "emailMapping": "emailMapping",
    "firstNameMapping": "firstNameMapping",
    "lastNameMapping": "lastNameMapping",
    "fullNameMapping": "fullNameMapping",
    "useFullName": "useFullName"
    }
}

Request Attributes

enabled (Required) Controls whether the configuration is enabled or not. Value can be "true" or "false". For example "true".
clientId (Required) The client ID from your IdP. For example, "0oa111usf1gpUkVUt0h1".
clientSecret (Required) The client secret from your IdP.
authorizationEndpoint (Required) Use the authorization endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (authorization_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/authorize".
tokenEndpoint (Required) Use the token endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the token endpoint (token_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/token".
userinfoEndpoint (Required) Use the user information endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (userinfo_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/userinfo".
jwkUri (Required) Use the JWK set URI from your IdP. To find the value, enter the configuration URL in a browser and obtain the JWK set URI endpoint (jwks_uri) from the details that are returned. For example, "https://myidp.com/oauth2/v1/keys".
endSessionEndpoint (Optional) If single logout (SLO) is enabled for the site, which is done through Tableau Cloud site UI, you can specify the configuration URL or the end session endpoint from your IdP. For example, "https://myidp.com/oauth2/v1/logout".
allowEmbeddedAuthentication (Optional) Controls how users authenticate when accessing embedded views. Value can be "true" or "false". Default value is "false", which authenticates users in a separate pop-up window. When set to "true", users authenticate using an inline frame (IFrame), which is less secure.
customScope (Optional) Specifies a custom scope user-related value that you can use to query the IdP. For example, "openid, email, profile".
prompt (Optional) Specifies whether the user is prompted for re-authentication and consent. For example, "login, consent".
clientAuthentication (Optional) Token endpoint authentication method. Value can be "client_secret_basic" or "client_secret_post". Default value is "client_secret_basic".
essentialAcrValues (Optional) List of essential Authentication Context Reference Class values used for authentication. For example, "phr".
voluntaryAcrValues (Optional) List of voluntary Authentication Context Reference Class values used for authentication.
emailMapping (Optional) Claim for retrieving email from the OIDC token. Default value is "email".
firstNameMapping (Optional) Claim for retrieving first name from the OIDC token. Default value is "given_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false".
lastNameMapping (Optional) Claim for retrieving last name from the OIDC token. Default value is "family_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false".
fullNameMapping (Optional) Claim for retrieving name from the OIDC token. Default value is "name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "true".
useFullName (Optional) Controls what is used as the display name. Value can be "true" or "false". Default value is "false", which uses first name (firstNameMapping attribute) and last name (lastNameMapping attribute) as the user display name. When set to "true", full name (fullNameMapping attribute) is used as the user display name.

cURL Request Example

curl "https://us-west-2a.online.tableau.com/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-update-oidc-config.xml

Content of create-update-oidc-config.xml:

Copy
<tsRequest>
  <siteOIDCConfiguration
    enabled="enabled"
    clientId="clientId"
    clientSecret="clientSecret"
    authorizationEndpoint="authorizationEndpoint"
    tokenEndpoint="tokenEndpoint"
    userinfoEndpoint="userinfoEndpoint"
    jwksUri="jwksUri"
    endSessionEndpoint="endSessionEndpoint"
    allowEmbeddedAuthentication="allowEmbeddedAuthentication"
    prompt="prompt"
    customScope="customScope"
    clientAuthentication="clientAuthentication"
    essentialAcrValues="essentialAcrValues"
    voluntaryAcrValues="voluntaryAcrValues"
    emailMapping="emailMapping"
    firstNameMapping="firstNameMapping"
    lastNameMapping="lastNameMapping"
    fullNameMapping="fullNameMapping"
    useFullName="useFullName" />
</tsRequest

Response Code

200

Response Body

Copy
<tsResponse>
  <siteOIDCConfiguration
    enabled="true" 
    testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
    allowEmbeddedAuthentication="false"
    clientId="0oa111usf1gpUkVUt0h1" 
    clientSecret="&lt;omit>"
    authorizationEndpoint="https://myidp.com/oauth2/v1/authorize"
    tokenEndpoint="https://myidp.com/oauth2/v1/token"
    userinfoEndpoint="https://myidp.com/oauth2/v1/userinfo"
    jwksUri="https://myidp.com/oauth2/v1/keys"
    endSessionEndpoint="https://myidp.com/oauth2/v1/logout"
    customScope="openid, email, profile"
    prompt="login,consent"
    clientAuthentication="client_secret_basic"
    essentialAcrValues="phr"
    emailMapping="email"
    firstNameMapping="given_name"
    lastNameMapping="family_name"
    fullNameMapping="name"
    useFullName="false" />
</tsResponse>
Copy
{tsRequest:
}

Notes:

  • The response hides the client secret and replaces it with &lt;omit>.

  • You can use the testloginURL to validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.

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

Must be 1-128 characters long in Tableau Cloud. Must be 1-24 characters long in Tableau Server.

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.
  • The label value name must be 1-24 characters long in Tableau Server.
  • 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.

Version: Available in API 1.0 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Only Tableau Administrators can update a project.   Permissions Overview(Link opens in a new window)

JWT Access Scope:      tableau:projects:create     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

URI

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

POST /api/api-version/sites/site-id/projects?publishSamples=publish-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to create the project in.
publish-value (Optional) A Boolean value that specifies whether to publish the sample workbooks provided by Tableau to the project. When the publish-value is not specified in the request, or the publishSamples parameter is missing, no samples will be published. To publish the sample workbooks, set publishSamples parameter to true. This option is equivalent to the tabcmd command-line utility option, publishsamples. For more information, see tabcmd(Link opens in a new window).

Request Body

Copy
<tsRequest>
  <project 
    parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
    name="Update-Project-Name"
    description="This is the new description after the project update"
    contentPermissions="ManagedByOwner">
      <owner id="abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"/>
  </project>
</tsRequest>

Copy
{
  "project": {
    "parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
    "name": "Update-Project-Name",
    "description": "This is the new description after the project update",
    "contentPermissions": "ManagedByOwner",
    "owner": {
      "id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
    }
  }
}

Attribute Values

project name (Required) The new name for the project.
project description (Optional) The new description for the project.
project parentProjectId

(Optional) The new identifier of the parent project. Use this option to create or change project hierarchies.

To create a project as a stand alone or at the top of a project hierarchy, omit the parentProjectId attribute.

For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults.

project contentPermissions

(Optional) This value controls user permissions in a project, however, if the project is nested within a project with more restrictive policies, it will inherit those permissions and these settings will have no effect. The functional permissions of a project, including those it inherits, are available in value of contentPermission in the response body from a request to create, update, or query a project.

  • LockedToProject to lock permissions so that users cannot overwrite the default permissions set for the project
  • ManagedByOwner to allow users to manage permissions for content that they own
  • LockedToProjectWithoutNested to lock the permissions of a parent project, but not those of its child projects.

The default is ManagedByOwner. For more information, see Lock Content Permissions(Link opens in a new window).

owner id The LUID of the user that owns the project.

cURL Example

curl --request PUT "https://myServer/api/3.21/sites/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/projects/xz2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e3w" --header "Content-Type: application/xml" --header "X-Tableau-Auth;" --data "<tsRequest> <project parentProjectId='ab2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5ee0' name='new-name' description='new-description' contentPermissions='ManagedByOwner' /> </tsRequest>"

Response Code

201

Response Body

Copy
<tsResponse>
  <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
    parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
    name="Update-Project-Name"
    description="This is the new description after the project update"
    contentPermissions="ManagedByOwner"
    controllingPermissionsProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" >
      <owner id="abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"/>
  </project>
</tsResponse>

Copy
{
  "project": {
    "id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
    "parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
    "name": "Update-Project-Name",
    "description": "This is the new description after the project update",
    "contentPermissions": "ManagedByOwner",
    "controllingPermissionsProjectId": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
    "owner": {
      "id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
    }
  }
}

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 400008 Bad request The request cannot set content permissions to LockedToProjectWithoutNested for a REST API version lower than 3.8.
403 403008 Insufficient storage on site The samples could not be published because there is not enough storage space remaining on the server to accommodate the samples.
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 POST.
409 409006 Project name conflict The project name in the request already belongs to the specified site. For the purpose of uniqueness checks, project names are case-insensitive.

For more information, see Handling Errors.

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.

URI

POST /api/api-version/schedules

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

<tsRequest>
  <schedule name="schedule-name"
	priority="schedule-priority"
	type="schedule-type"
	frequency="schedule-frequency"
	executionOrder="schedule-execution-order">
	  <frequencyDetails start="start-time" end="end-time">
	    <intervals>
	      <interval interval-expression />
	    </intervals>
 	  </frequencyDetails>
  </schedule>
</tsRequest>
        

Attribute Values

schedule-name The name to give to the schedule. This name identifies the schedule in the server environment when users select a schedule and manage schedule information.
schedule-priority An integer value between 1 and 100 that determines the default priority of the schedule if multiple tasks are pending in the queue. Lower numbers have higher priority.
schedule-type Flow to create a flow schedule, Extract to create an extract refresh schedule, Subscription to create a subscription schedule, or DataAcceleration to create a data acceleration schedule. (Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)
schedule-execution-order Parallel to allow jobs associated with this schedule to run at the same time, or Serial to require the jobs to run one after the other.
schedule-frequency

This represents the granularity of the schedule.

  • Hourly. Jobs can be scheduled to run at intervals specified in run one or more times per day at intervals specified in minutes or hours. Valid intervals are 15 and 30 minutes and 2, 4, 6, 8, and 12 hours.

  • Daily. Jobs can be scheduled to run once per day.
  • Weekly. Jobs can be scheduled to run one or more times per week.
  • Monthly. Jobs can be scheduled to run once per month on a specific day.

The value you provide for schedule-frequency determines whether you must include an end-time value, and what is required in the contents of the <intervals> element.

start-time The time of day on which scheduled jobs should run (or if the frequency is hourly, on which they should start being run), in the format HH:MM:SS (for example, 18:30:00). This value is required for all schedule frequencies. The entered time will be applied based on the time zone of your server.
end-time If the schedule frequency is Hourly, the time of day on which scheduled jobs should stop being run, in the format HH:MM:SS (for example, 23:30:00). Hourly jobs will occur at the specified intervals between the start time and the end time. For other schedule frequencies, this value is not required; if the attribute is included, it is ignored. The entered time will be applied based on the time zone of your server.
interval-expression A value that specifies the interval between jobs associated with the schedule. The value you specify here depends on the value specified in schedule-frequency.

Hourly

The interval expression is only one of the following:

  • hours="interval" where interval is 1, 2, 4, 6, 8, or 12, representing how many hours between jobs.
  • minutes="interval" where interval is 15 or 30, representing how many minutes between jobs.

You can specify an interval in hours or minutes, but not both.

Daily

If the schedule frequency is Daily, no interval is specified. Any information specified in the <intervals> element is ignored.

Weekly

The interval expression is weekDay="weekday", where weekday is Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

You can specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week.

Monthly

The interval expression is monthDay="day", where day is either the day of the month (1, 2, etc.) or LastDay.

Note: If you want to specify multiple days in the month, you can do this using the web interface. You cannot create or update such a monthly schedule using REST API.

Permissions

This method can only be called by server administrators.

Response Code

201

Response Body

<tsResponse>
  <schedule id="schedule-id"
    name="schedule-name"
	state="Active-or-Suspended"
    priority="schedule-priority"
	createdAt="datetime-created"
	updatedAt="datetime-updated"
	type="Extract-or-Subscription-or-Flow"
	frequency="schedule-frequency"
	nextRunAt="datetime-next-run"
	executionOrder="Parallel-or-Serial">
	  <frequencyDetails frequency-expression >
	    <intervals>
	      <interval interval-expression />
	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsResponse>
        

Version

Version 2.3 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 400064 Error creating schedule An unspecified error occurred while trying to create the schedule.
400 409004 Bad request The content of the request body is missing or incomplete. For hourly, daily, or monthly schedules, this often means that the content of the <intervals> element does not match the expected format. The <detail> element of the error provides detail about the expected format.
405 405000 Invalid request method Request type was not POST.
409 409021 Schedule name conflict The schedule name in the request already belongs to an existing schedule.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/schedules/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-schedule.xml


Content of create-schedule.xml for an hourly schedule

<tsRequest>
  <schedule name="hourly-schedule-1"
    priority="50"
	type="Extract"
	frequency="Hourly"
	executionOrder="Parallel">
	  <frequencyDetails start="18:30:00" end="23:00:00">
		<intervals>
		  <interval hours="2" />
		</intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse >
  <schedule
    id="4d652179-36bf-47e4-a9dc-e069227c72d0"
    name="hourly-schedule-1"
    state="Active"
    priority="50"
    createdAt="2016-05-07T01:51:19Z"
    updatedAt="2016-05-07T01:51:19Z"
    type="Extract"
    frequency="Hourly"
    nextRunAt="2016-05-07T03:30:00Z"
    executionOrder="Parallel">
      <frequencyDetails start="18:30:00" end="23:00:00">
        <intervals>
           <interval hours="2" />
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
        


Content of create-schedule.xml for a daily schedule

For a daily schedule, frequencyDetails is set to Daily. The start attribute is required. No intervals element is required. Daily schedules on any recurrence must have the same start and end minute. The hour can be different. However, if the daily schedule is set to only happen once a day, then it needs only a start time and not an end time.

<tsRequest>
  <schedule
    name="daily-schedule-1"
    priority="50"
    type="Subscription"
    frequency="Daily"
    executionOrder="Parallel">
      <frequencyDetails start="02:15:00" />
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule
	id="4d652179-36bf-47e4-a9dc-e069227c72d0"
	name="daily-schedule-1"
	state="Active"
	priority="50"
	createdAt="2016-05-07T01:43:33Z"
	updatedAt="2016-05-07T01:43:33Z"
	type="Subscription"
	frequency="Daily"
	nextRunAt="2016-05-07T09:15:00Z"
	executionOrder="Parallel">
	  <frequencyDetails start="02:15:00" />
  </schedule>
</tsResponse>
        


Content of create-schedule.xml for a weekly schedule

For a weekly schedule, frequencyDetails is set to Weekly. A start attribute is required. The intervals element is required, and must include between 1 and 7 interval subelements that contain a weekDay attribute. Valid values for the weekDay attribute are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

<tsRequest>
  <schedule name="weekly-schedule-1"
	priority="50"
	type="Subscription"
	frequency="Weekly"
	executionOrder="Serial">
  	  <frequencyDetails start="18:30:00">
	    <intervals>
	      <interval weekDay="Sunday" />
	      <interval weekDay="Wednesday" />
 	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0"
    name="weekly-schedule-1"
    state="Active"
    priority="50"
    createdAt="2016-05-07T02:01:30Z"
    updatedAt="2016-05-07T02:01:30Z"
    type="Subscription"
    frequency="Weekly"
    nextRunAt="2016-05-09T01:30:00Z"
    executionOrder="Serial">
      <frequencyDetails start="18:30:00">
        <intervals>
          <interval weekDay="Sunday" />
          <interval weekDay="Wednesday" />
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
        


Content of create-schedule.xml for a monthly schedule

For a monthly schedule, frequencyDetails is set to Monthly. A start attribute is required. The intervals element is required, and must include 1 interval subelement that contains a monthDay attribute. Valid values for the monthDay attribute are integers between 1 and 31 and the string LastDay.

<tsRequest>
  <schedule name="monthly-schedule-1"
	priority="50"
	type="Subscription"
	frequency="Monthly"
	executionOrder="Parallel">
	  <frequencyDetails start="06:00:00">
	    <intervals>
	      <interval monthDay="15" />
	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule
	id="4d652179-36bf-47e4-a9dc-e069227c72d0"
	name="monthly-schedule-1"
	state="Active"
	priority="50"
	createdAt="2016-05-07T02:08:25Z"
	updatedAt="2016-05-07T02:08:25Z"
	type="Subscription"
	frequency="Monthly"
	nextRunAt="2016-06-03T13:00:00Z"
	executionOrder="Parallel">
	  <frequencyDetails start="06:00:00">
	    <intervals>
	      <interval monthDay="15" />
	    </intervals>
  	  </frequencyDetails>
  </schedule>
</tsResponse>
        

Create Site

Creates a site on Tableau Server. To make changes to an existing site, call Update Site. This method is not 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.

URI

POST /api/api-version/sites

Request Body

<tsRequest>
  <site
	name="site-name"
	contentUrl="content-url"
	adminMode="admin-mode"
	storageQuota="limit-in-megabytes"
	disableSubscriptions="disable-subscriptions"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	commentingEnabled="commenting-enabled-flag"
	revisionHistoryEnabled="enable-revision-history-flag"
	revisionLimit="num-revision-limit"
	subscribeOthersEnabled="subscribe-others-enabled-flag"
	extractEncryptionMode="extractEncryptionMode"
	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"
	webExtractionEnabled="web-extraction-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" />
</tsRequest>
        

Attribute Values

site-name The name of the site.
content-url The subdomain name of the site's URL. This value can contain only characters that are upper or lower case alphabetic characters, numbers, hyphens (-), or underscores (_). If you provide unsupported special characters, Tableau creates the site content URL by omitting those characters from the string. For example, if you provide the site URL as "test.site", Tableau converts it to "testsite" and returns this new URL in the response.
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 does not 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 userQuota. The default value is ContentAndUsers.

storage-quota (Optional) The 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.
disable-subscriptions

(Optional) Specify true to prevent users from being able to subscribe to workbooks on the specified site. The default is false.

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 version 3.10.

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.

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 is removed in API 3.19 and later (Tableau Cloud September 2021). 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 time. 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.

revision-history-enabled (Optional) true if the site maintains revisions for changes to workbooks and data sources; otherwise, false. The default is false.
num-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.

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.

extractEncryptionMode

(Optional) Specify enforced, enabled, or disabled. Default is disabled. For more information, see Extract and Encryption Methods.

requestAccessEnabled (Optional) Specify true to allow users send access request emails to content or project owners. Specify false if you do not 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 do not 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 possible number of users is set by the licenses activated on that server. For core-based licensing, there is 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).

Online administrators can get these attributes. An on premise 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 premise 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 premise 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.

web-extraction-enabled-flag

(Optional, boolean) If true, web extraction 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 true.

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

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 one of the following topics:

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 one of the following topics:

Permissions

This method can only be called by server administrators.

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:sites:create

Response Code

201

Response Body

<tsResponse>
  <site id="site-id"
 	name="site-name"
	contentUrl="content-url"
 	adminMode="admin-mode"
	disableSubscriptions="disable-subscriptions-flag"
	state="active-or-suspended"
	revisionHistoryEnabled="history-enabled-flag"
	revisionLimit="max-num-revisions"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	subscribeOthersEnabled="enable-subscription-of-others-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="encryption-mode"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	requestAccessEnabled="request-access-enabled-flag"
	webExtractionEnabled="create-extracts-on-the-web-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" />
  </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.

Response Headers

Location: /api/3.22/sites/new-site-id

Version

Version 1.0 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, incomplete, or contains malformed XML.
400 400000 Invalid storage quota The storage quota value was not a positive number.
400 400000 Invalid user quota The user quota value was not a positive number.
400 400013 Invalid administrator mode The user provided an administrator mode that is not ContentOnly or ContentAndUsers.

Note: An empty string or all whitespace is invalid.

405 405000 Invalid request method Request type was not POST.
409 409001 Site name conflict The site name in the request already belongs to an existing site.
409 409002 Site URL conflict The content URI in the request already belongs to an existing site.
409 409004 User quota and tiered capacity conflict The request cannot set both tiered capacity attributes and userQuota. One or the other must be null.
409 409004 License limit exceeded The request cannot 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 cannot set adminMode to ContentOnly and also specify a userQuota value.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-site.xml

Content of create-site.xml:

<tsRequest>
	<site name="Marketing-Site"
		contentUrl="marketingsite"
		adminMode="ContentAndUsers"
		tierCreatorCapacity="2"
		tierExplorerCapacity="1"
		tierViewerCapacity="1"
		useDefaultTimeZone="false"
		timeZone="America/Los_Angeles"/>
</tsRequest>
        

Response body:

<tsResponse>
	<site id="43e01bb6-d7f9-42ef-bc9f-0422c07520e5"
		name="Marketing-Site"
		contentUrl="marketingsite"
		adminMode="ContentAndUsers"
		disableSubscriptions="true"
		state="Active"
		revisionHistoryEnabled="true"
		revisionLimit="25"
		subscribeOthersEnabled="false"
		allowSubscriptionAttachments="true"
		guestAccessEnabled="true"
		cacheWarmupEnabled="true"  [REMOVED IN API 3.19]
		commentingEnabled="true"
        editingFlowsEnabled="false"
        schedulingFlowsEnabled="false"
		extractEncryptionMode="enabled"
		catalogingEnabled="true"
		derivedPermissionsEnabled="false"
		requestAccessEnabled="false"
		runNowEnabled="true"
		userQuota="4"
		tierCreatorCapacity="2"
		tierExplorerCapacity="1"
		tierViewerCapacity="1"
		useDefaultTimeZone="false"
		timeZone="America/Los_Angeles" />
</tsResponse>
        

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.

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.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to create the subscription in.

JWT Access Scope

tableau:tasks:create (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Tableau Server Request

Create a subscription task and add it to a server schedule on Tableau Server.
For Tableau Cloud, see Tableau Cloud Request.

Request Body

Copy
<tsRequest>
  <subscription
    subject="subscription-subject"
    attachImage="attach-image-flag"
    attachPdf="attach-pdf-flag"
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option"    
    message="message">
      <content id="content-id"
        type="content-type"    
        sendIfViewEmpty="send-view-if-empty-flag"/>    
      <schedule id="schedule-id" />
      <user id="user-id" />
    </subscription>
</tsRequest>
Copy
{
  "subscription": {
    "subject": "subscription-subject",
    "attachImage": "attach-image-flag",
    "attachPdf": "attach-pdf-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "message": "message",
    "content": {
      "id": "content-id",
      "type": "content-type",
      "sendIfViewEmpty": "send-view-if-empty-flag"
    },
    "schedule": {
      "id": "schedule-id"
    },
    "user": {
      "id": "user-id"
    }
  }
}

subscription-subject A description for the subscription. This description is displayed when users list subscriptions for a site in the server environment. A description is required.
attach-image-flag

(Optional) Setting this true will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither attachImage or attachPdf are specified.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachImage to false will cause an error.

attach-pdf-flag

(Optional) Setting this true will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachPdf to true will cause an error.

page-orientation (Optional) The orientation of the pages produced when attach-pdf-flag is true. The value can be Portrait or Landscape. If this parameter is not present the page orientation will default to Portrait.
page-size-option (Optional) The type of page produced, which determines the page dimensions when attach-pdf-flag is true. The value can be: A3, A4, A5, B5, Executive, Folio, Ledger, Legal, Letter, Note, Quarto, or Tabloid. If this parameter is not present the page type will default to Letter.
message The text body of the subscription email message.
content-type Workbook to create a subscription for a workbook, or View to create a subscription for a view.
send-view-if-empty-flag (Optional) Applies to views only. If true, an image is sent even if the view specified in a subscription is empty. If false, nothing is sent if the view is empty. The default value is true.
content-id The ID of the workbook or view to subscribe to.
schedule-id The ID of a schedule to associate the subscription with. To determine what schedules are available, call List Server Schedules. The type of the schedule must be Subscription.
user-id The ID of the user to create the subscription for.

Note: The user must have an email address defined in Tableau Server.

Permissions

The following list summarizes the permissions required to subscribe a user to specific content:

  • Tableau Server users who are server administrators can subscribe any user to any content.
  • Site administrators can subscribe any user on the site to any content on that site.
  • Project leaders can subscribe users to any content that they are project leaders for.
  • Content owners can subscribe users to any content they own.
  • Non-owners can subscribe themselves to any content that they have Read (view) permissions for.

Response Code

201

Response Body

Copy
<tsResponse>
  <subscription id="subscription-id"
    subject="subscription-subject"
    suspended="suspended-flag"
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option" 
    message="message" >
      <content id="content-id"
        type="content-type" 
        sendIfViewEmpty="send-view-if-empty-flag"/>
      <schedule id="schedule-id" name="schedule-name" />
      <user id="user-id" name="user-name" />
  </subscription>
</tsResponse>
Copy
{
  "subscription": {
    "id": "subscription-id",
    "subject": "subscription-subject",
    "suspended": "suspended-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "message": "message",
    "content": {
      "id": "content-id",
      "type": "content-type",
      "sendIfViewEmpty": "send-view-if-empty-flag"
    },
    "schedule": {
      "id": "schedule-id",
      "name": "schedule-name"
    },
    "user": {
      "id": "user-id",
      "name": "user-name"
    }
  }
}

Response Headers

Location: /api/3.22/sites/site-id/subscriptions/new-subscription-id

Version

Available in API 2.3 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 400067 Invalid subscription subject The subscription subject is null or empty.
400 400068 Invalid subscription target The content type specified in the request body is not a workbook or view.
400 400069 Invalid subscription type The subscription type is not Workbook or View.
400 400069 Invalid schedule type The schedule type is not Subscription.
403 403060 No permissions to create subscription. The user does not have permission to create a subscription for the specified content.
403 403063 No user permissions for content. The user specified in the request body does not have Read (view) permissions for the specified content.
403 403064 No user email address. The user does not have an email address.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404002 User not found The user specified in the request body doesn't correspond to an existing user.
400 404006 Workbook not found The workbook ID in the request body doesn't correspond to an existing workbook.
404 404011 View not found The view ID in the request body doesn't correspond to an existing view.
404 404023 Schedule not found The schedule ID in the request body doesn't correspond to an existing schedule.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Tableau Cloud Request

Create a subscription task and define its frequency on Tableau Cloud.
For Tableau Server, see Tableau Server Request.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Administrators and any user with the creator or explorer role can create a custom schedule for a subscription task.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:tasks:create     Access Scopes Overview: Cloud(Link opens in a new window)

URI

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

URI Parameter Values

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

Request Body

Copy
<tsRequest>
  <subscription 
  subject="finance report" 
  attachImage="true" 
  attachPdf="true" 
  pageOrientation="true" 
  pageSizeOption="Folio" 
  message="Daily finance report"> 
    <content id="13237fd-6365-44d5-925b-644e5281b605"
      type="Workbook" 
      sendIfViewEmpty="false"/> 
    <user id="6t543fd-6365-44d5-925b-644e52897y65"/>
  </subscription>
  <schedule frequency="Daily">
    <frequencyDetails start="18:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Sunday"/>
        <interval WeekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Copy
{
  "subscription": {
    "subject": "finance report",
    "attachImage": "true",
    "attachPdf": "true",
    "pageOrientation": "true",
    "pageSizeOption": "Folio",
    "message": "daily finance report",
    "content": {
      "id": "13237fd-6365-44d5-925b-644e5281b605",
      "type": "Workbook",
      "sendIfViewEmpty": "false"
    },
    "user": {
      "id": "456"
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}

Request Attributes

subject, contentId, and userId are required to create a custom schedule for a subscription, other attributes are optional with defaults. All attributes are optional when updating a custom schedule for a subscription.

subscription subject (Required to create subscription) string: A description for the subscription. This description is displayed when users list subscriptions for a site in the server environment.
subscription attachImage

boolean: Setting this true will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither attachImage or attachPdf are specified. Default is false.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachImage to false will cause an error.

subscription attachPdf

boolean: Setting this true will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. Default is false.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachPdf to true will cause an error.

subscription pageOrientation enumeration: The orientation of the pages produced when attach-pdf-flag is true. The value can be Portrait or Landscape. If this parameter is not present the page orientation will default to Portrait.
subscription pageSizeOption enumeration: The type of page produced, which determines the page dimensions when attach-pdf-flag is true. The value can be: A3, A4, A5, B5, Executive, Folio, Ledger, Legal, Letter, Note, Quarto, or Tabloid. If this parameter is not present the page type will default to Letter.
subscription message string: The text body of the subscription email message.
content id (Required to create subscription) LUID: The LUID of the workbook or view the user should be subscribed to.
content type (Required to create subscription) enumeration: Workbook to create a subscription for a workbook, or View to create a subscription for a view.
content sendIfViewEmpty boolean: Applies to views only. If true, an image is sent even if the view specified in a subscription is empty. If false, nothing is sent if the view is empty. The default value is true.
userId (Required to create subscription) LUID: The LUID of the user to create the subscription for.

Note: The user must have an email address defined in Tableau Server.

schedule frequency (Required to create subscription) enumeration: The scheduled frequency for triggering the extract refresh. Valid values include:
  • Hourly
  • Daily
  • Weekly
  • Monthly
frequencyDetails start (Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.
frequencyDetails end

(Required to create subscription) time: If the schedule frequency is Hourly, or Daily with an interval of hours less than 24, then end is the time of day on which scheduled jobs should stop being run. The valid format is HH:MM:SS. Time should be specified in 5 minute increments and the difference between start and end times should be increments of 60 minutes. For example, a valid frequencyDetail would be:

<frequencyDetail start="20:45:00" end="21:45:00">
  . . . 
</frequencyDetail>
interval {interval type} (Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in the start and end values of the frequencyDetails of the schedule. The type and valid values for an interval expression depend on the declared frequency of the schedule as follows:

FrequencyValid interval values
Hourly The value of an interval for an Hourly schedule can be only one of either:
  • hours=“1" The number of hours between jobs. 1 is the only valid value.
  • minutes=“60" The number of minutes between jobs. 60 is the only valid value.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday.

    For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="1"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
    <intervals>

Daily The value of Daily can have multiple weekday elements, but only one hours declaration. An hours interval is required.
  • hours=“interval" The interval between execution of jobs on the weekday(s) specified. Valid values are 2, 4, 6, 8, 12, or 24. Note that if the interval value of a daily schedule is less than 24, a frequencyDetail end time must be supplied.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

    For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="4"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
    <intervals>
WeeklyweekDay=“weekday" The day of the week the schedule should run on. Multiple days can be specified for a Weekly schedule. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.
Monthly

The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval:

Specify the day(s) using the number of the day in the month;

  • monthDay=“day" The number of the day of the month. Valid values are the whole numbers 1 to 31 or LastDay. If you specify monthDay by day number then you can use multiple interval instances to choose for the job to run on multiple days in the month. If you use LastDay then only one instance of interval can be used in the schedule to specify the last day of the month.

Specify the day by describing which occurrence of a weekday within the month.

  • monthDay=“occurrence_of_weekday" Weekday=“weekday" The occurrence of the specified weekday within the month when a job should be run. Valid values for occurrencee_of_weekday are First, Second, Third, Fourth, Fifth, or LastDay. Valid values for weekday are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday. If the value is lastDay then the job will run on the last occurrence of the specified weekday in the month.

    For example, to make a schedule that that would run a job on the third Thursday of each month, you would use:
    Copy
    <interval monthDay="Third" weekDay="Thursday"/>

cURL Request Example

curl --location --request POST "qa-near.tsi.lan/api/3.22/sites/a946d998-2ead-4894-bb50-1054a91dcab3/tasks/subscription" - header "Content-Type: application/xml" --data "<tsRequest> <subscription subject="finance report" attachImage="true" attachPdf="true" pageOrientation="true" pageSizeOption="Folio" message="daily finance report"> <content id="13237fd-6365-44d5-925b-644e5281b605" type="Workbook" sendIfViewEmpty="false"/><user id="6t543fd-6365-44d5-925b-644e52897y65"/> </subscription> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> <intervals> <interval weekDay='Sunday'/> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"

Response Code

200

Response Body

Copy
<tsResponse>
  <subscription
    id="45678fd-6365-44d5-925b-644e52834567"
    subject="finance report" 
    attachImage="true" 
    attachPdf="true" 
    pageOrientation="true" 
    pageSizeOption="Folio" 
    message="Daily finance report"> 
      <content 
        id="13237fd-6365-44d5-925b-644e5281b605"
        type="Workbook" 
        sendIfViewEmpty="false"/> 
      <user id="09876fd-6365-44d5-925b-644e528d5678"/>
  </subscription>
  <schedule id="54321fd-6365-44d5-925b-644e52812345"
    createdAt="2023-04-06T23:43:12-0700"
    updatedAt="2023-04-06T23:43:12-0700"
    frequency="Daily"
    nextRunAt="2023-04-06T23:43:12-0700" />
      <frequencyDetails start="18:30:00" end="23:30:00">
        <intervals>
          <interval hours="4"/>
          <interval weekDay="Sunday"/>
          <interval weekDay="Wednesday"/>
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
Copy
{
  "subscription": {
    "id": "789",
    "subject": "finance report",
    "attachImage": "true",
    "attachPdf": "true",
    "pageOrientation": "true",
    "pageSizeOption": "Folio",
    "message": "Daily finance report",
    "content": {
      "id": "13237fd-6365-44d5-925b-644e5281b605",
      "type": "Workbook",
      "sendIfViewEmpty": "false"
    },
    "user": {
      "id": "09876fd-6365-44d5-925b-644e528d5678"
    }
  },
  "schedule": {
    "id": "54321fd-6365-44d5-925b-644e52812345",
    "createdAt": "2023-04-06T23:43:12-0700",
    "updatedAt": "2023-04-06T23:43:12-0700",
    "frequency": "Daily",
    "nextRunAt": "2023-04-06T23:43:12-0700",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
             { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
         ]
      }
    }
  }
}

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 404002 User not found The user specified in the request could not be found.
404 404025 Subscription not found The task for the subscription 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 subscription

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

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user that has read or connect permission to Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:create
Access Scopes Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

POST /api/api-version/sites/site-id/decrypt-extracts

Parameter Values

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

Request Body

None

Permissions

Tableau Server administrators can call this method.

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 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Delete a Webhook

Deletes the specified webhook.

URI

DELETE /api/3.6/sites/<site-id>/webhooks/<webhook-id>

Parameter Values

site-id The ID of the site that contains the workbook to be deleted.  
webhook-id The ID of the webhook.  

Request Body

None.

Permissions

This method can only be called by server and site administrators.

Response Code

204

Response Body

None.

Delete analytics extension connection from site

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

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: Can only be called by users with site or server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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 an ask data lens.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can be called by users with administrator and lens owner permissions. Permissions Overview

License: No additional license required.

Access Scope: `tableau:lenses:delete` Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

DELETE /api/api-version/sites/site-luid/lenses/lens-luid/permissions/groups/group-luid/capability-name/capability-mode

DELETE /api/api-version/sites/site-luid/lenses/lens-luid/permissions/users/user-luid/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid Required. The LUID of the site that contains the view.
lens-luid Required. The LUID of the lens to delete permissions for.
group-luid Optional (one user or group must be specified). The LUID of the group to remove the permission for.
user-luid Optional. The LUID of the user to remove the permission for.
capability-name

The capability to remove the permission for.

The valid capabilities for a view are ChangePermissions, Delete, Move, Read, Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission.

Request Body

None

Permissions

Users with server or site administrator permissions, and non-administrators that have Delete or ChangePermissions permission (either explicitly or implicitly) for the lens, can delete ask data lens permissions.

Response Code

204

Response Body

None

Version

Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for an ask data lense. Valid capabilities for a lens are ChangePermissions, Delete, Move, Read, and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to delete permissions on the view.
403 403039 Project permissions locked The parent project that contains the specified ask data lens has its permissions locked.
404 404000 Site not found The site ID or URL namespace 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.
404 404046 Lens not found The ask data lens LUID in the URI doesn't correspond to an existing view.
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 specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or an invalid capability value (other than Allow or Deny).
404 404014 Capability not assigned The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny).
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Authentication Configuration

Delete an authentication instance.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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: 

URI

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

Note: Deprecated in API 3.17 - the following resource is no longer supported and will be retired in future releases: 

URI DELETE api/api-version/sites/site-id/connected-applications/client-id

Parameter Values

api-version The version of the API to use, such as 3.22. 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:

URI

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

Note: Deprecated in API 3.17 - the following resource is no longer supported and will be retired in future releases: 

URI DELETE api/api-version/sites/site-id/connected-applications/client-id/secrets/secret-id

Parameter Values

api-version The version of the API to use, such as 3.22. 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.

Version: Available in API 3.18 (Tableau Cloud December 2024) and later. Not available for Tableau Server. Version Overview

License: No additional license required.

Permissions: Tableau administrators can delete a custom view. Other users can delete any custom view that they own.  Permissions Overview

JWT Access Scope: tableau:views:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

DELETE /api/api-version/sites/site-luid/customviews/custom-view-luid

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
custom-view-luid The LUID for the custom view being updated.

Request Body

None.

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

cURL Request Example

curl -L -X DELETE "https://qa-near/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/37d015c6-bc28-4c88-989c-72c0a171f7aa" -H "X-Tableau-Auth: njR9EGn0QSCpbDrUOh0IKg|wamRRyVFFUHTVwFL6OWEyOggxCwWYXuq|a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

201

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

URI

DELETE /api/api-version/sites/site-id/tasks/dataAcceleration/dataAcceleration-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the task.
dataAcceleration-id The ID of the task to remove.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

None

Version

In Tableau Server 2020.2 (API 3.8) through 2021.4 (API 3.15) data acceleration is supported.

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.

For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 409087 Permission denied The user isn't authorized to view data acceleration tasks.
403 409087 Permission denied The user isn't authorized to access the workbook.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404026 Task not found The task id in the URI doesn't correspond to an existing task.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/dataAcceleration/7a2a7c6d-5e4f-3a2b-1c0d-9e8f7a6b3r4q" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

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

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.22. 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 delete.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a data source for which they have Read (view) and Delete permissions (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user called this method but doesn't have Read (view) and Delete permission for the data source.
404 404000 Site not found The site ID or URL namespace 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 in the site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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.

URI

DELETE /api/api-version/sites/site-id/favorites/user-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to remove the favorite from.
datasource-id The ID of the data source to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the data source (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Forbidden favorites access A non-administrator user attempted to delete a data source from a different user's favorites.
404 404000 Site not found The site ID or URL namespace 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
404 404010 Data source not a favorite The data source ID in the URI exists but is not a favorite of the specified user.
404 404011 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 DELETE.

For more information, see Handling Errors.

Delete Data Source Permission

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

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/datasources/datasource-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.22. 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 remove the permission for.
group-id The ID of the group to remove the permission for.
user-id The ID of the user to remove the permission for.
capability-name

The capability to remove the permission for. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), Write, and SaveAs.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Users who are not server administrators or site administrators can call this method only if they have permission to delete permissions from the data source (either explicitly or implicitly).

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:permissions:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the data source.
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.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not assigned The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny).
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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

Version: Available in API 3.2 (Tableau Cloud / Tableau Server 2018.3) and later. Version Overview(Link opens in a new window)

License: No additional license required.>

Permissions: This method can be called by server and site administrators, and by users who are owners or recipients of the specified data-driven alert.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:data_driven_alerts:delete     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

None

Response Code

204

Response Body

None

Version

Errors

HTTP status error Code Condition Details
403 403004 Delete forbidden A user called this method who does not have the required permissions
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

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.22. 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.22. 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, and metric 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.

URI

Workbooks:

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks/users/user-luid/capability-name/capability-mode

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks/groups/group-luid/capability-name/capability-mode

Data sources:

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources/users/user-luid/capability-name/capability-mode

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources/groups/group-luid/capability-name/capability-mode

Data roles:

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles/users/user-luid/capability-name/capability-mode

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles/groups/group-luid/capability-name/capability-mode

Lenses:

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses/users/user-luid/capability-name/capability-mode

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses/groups/group-luid/capability-name/capability-mode

Metrics:

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics/users/user-luid/capability-name/capability-mode

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics/groups/group-luid/capability-name/capability-mode

Flows:

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows/users/user-luid/capability-name/capability-mode

DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows/groups/group-luid/capability-name/capability-mode

Databases:

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

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

Tables:

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

DELETE /api/api-version/sites/site-luid/projects/project-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.22. For more information, see REST API and Resource Versions.
site-id The LUID of the site that contains the project.
project-id The LUID of the project to remove the default permission for.
group-id The LUID of the group to remove the default permission for.
user-id The LUID of the user to remove default permission for.
capability-name

The capability to remove the permissions for.

Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, Write, RunExplainData, and CreateRefreshMetrics.

Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, SaveAs, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Users who are not server administrators can remove permissions for a project only if they have ProjectLeader permissions for that project (either explicitly or implicitly).

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:permissions:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permissions to remove permissions for the project.
403 403095 Delete permissions for flows forbidden A non-administrator user called this method but doesn't have permissions to remove permissions for the project where the flow is located.
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 URI 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 404012 Group not found A group LUID in the URI doesn't correspond to an existing group.
404 404013 Capability not assigned The capability in the URI isn't assigned to the specified user or group.
404 404013 Capability not found The capability in the URI 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 LUID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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.22. 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 Cloud site admins only.

Response Code

204

Response Body

None

Version

Introduced Tableau Cloud June 2022 (API 3.16). Currently not available for Tableau Server.

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.

URI

DELETE /api/api-version/sites/site-luid/tasks/extractRefreshes/task-luid

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the extract refresh task.
task-luid The LUID of the extract refresh task to remove.

JWT Access Scope

tableau:tasks:delete (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete an extract refresh task for which they have Read (view) and Delete permissions (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404026 Task not found The task id in the URI doesn't correspond to an existing extract refresh task.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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.

URI

POST /api/api-version/sites/site-id/workbookss/workbook-id/deleteExtract

Path Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The LUID of the site.
datasource-id The LUID of the workbook containing the extract to be deleted.

Permissions

Extracts for data sources can be deleted by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

Request Body

<tsRequest>
  <datasources includeAll="true"/>
</tsRequest>
        

Request Parameter Values

None.

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 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@delete-extracts-for-workbook.xml"

Content of create-extracts-for-workbook.xml

<tsResponse>
  <datasources includeAll="true" />
</tsRequest>

Response body:

None. Response code is 200.

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.

URI

DELETE /api/api-version/sites/site-id/flows/flow-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-id The ID of the flow to delete.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a flow for which they have Read (view) and Delete permissions (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user called this method but doesn't have Read (view) and Delete permission for the flow.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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.

URI

DELETE /api/api-version/sites/site-id/favorites/user-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to remove the favorite from.
datasource-id The ID of the data source to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the data source (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Forbidden favorites access A non-administrator user attempted to delete a data source from a different user's favorites.
404 404000 Site not found The site ID or URL namespace 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
404 404010 Flow not a favorite The flow ID in the URI exists but is not a favorite of the specified user.
404 404027 Data source not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Flow Permission

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

URI

DELETE /api/api-version/sites/site-id/flows/flow-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/flows/flow-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-id The ID of the flow to remove the permission for.
group-id The ID of the group to remove the permission for.
user-id The ID of the user to remove the permission for.
capability-name The capability to remove the permission for. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete permissions from a flow only if they have ChangePermissions permission for flow (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a flow. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the flow.
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.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not found The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allowor Denyat the end of the URI.
404 404013 Capability not assigned The capability in the URI is not assigned to the specified user or group with the specified mode (Allowor Deny).
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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.

URI

DELETE /api/api-version/sites/site-id/groups/group-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
group-id The ID of the group to delete.

Request Body

None

Permissions

This method can be called by site 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:groups:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group or the group is not part of the specified site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

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.

Version: Available in API 3.22 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:delete     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

DELETE /api/api-version/sites/site-id/groupsets/group-set-id

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
group-set-id The ID of the group set to delete.

Request Body

None

cURL Request Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

Response Code

204

Response Body

None

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type wasn’t DELETE.
409 409120 Group set not found The group set ID in the URI doesn't correspond to an existing group set or the group set isn’t part of the specified site.

For more information, see Handling Errors.

Delete Identity Pool

Delete an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Delete Identity Store

Delete an identity store.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

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

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

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can delete a metric from a definition as long as the user has write or publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:delete
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

DELETE /api/api-version/sites/site-id/metrics/metric-luid

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the metric.
metric-luid The unique ID of the metric to remove.

Request Body

None

Permissions

Users who are not administrators can delete a metric for which they have explicit or implicit Read (view) and Delete permission.

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:metrics:delete

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
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Metric not found The metric ID in the URI doesn't correspond to an existing metric.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics/6561daa3-20e8-407f-ba09-709b178c0b4a" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

Delete metric definition

Deletes a metric definition.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can delete a metric definition as long as the user has write or publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions:delete
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

DELETE /api/api-version/sites/site-luid/projects/project-luid

Parameter Values

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

Request Body

None

Permissions

Only server administrators and site administrators can call this method.

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:projects:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403003 Deletion forbidden You attempted to delete a default project that cannot be deleted.
404 404000 Site not found The site LUID or URL namespace in the URI doesn't correspond to an existing site.
404 404005 Project not found The project LUID in the URI doesn't correspond to an existing project or the project is not found on this site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

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.

URI

DELETE /api/api-version/sites/site-id/favorites/user-id/projects/project-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
user-id The ID of the user to remove the favorite from.
project-id The ID of the project to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a project only from their own favorites.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Forbidden favorites access A non-administrator user attempted to delete a project from a different user's favorites.
404 404000 Site not found The site ID or URL namespace 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.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/favorites/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/projects/89a82d78-664f-45a1-8256-d4d2961a070b" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Delete Project Permission

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

URI

DELETE /api/api-version/sites/site-id/projects/project-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/projects/project-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
project-id The ID of the project to remove the permission for.
group-id The ID of the group to remove the permission for.
user-id The ID of the user to remove project the permission for.
capability-name The capability to remove the permission for. In Tableau Server 10.0, valid capabilities for a project are ProjectLeader, Read (view), and Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can remove permissions for a project only if they have ChangePermissions (version 2.0) or ProjectLeader (version 2.1) permissions for that project (either explicitly or implicitly).

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:permissions:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a project. For a list of valid capabilities, see the capability-name attribute earlier.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permissions to remove default permissions for the project.
403 403004 Delete forbidden A non-administrative user tried to update the project, but does not have permissions to the project.
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 URI doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
404 404012 Group not found A group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not assigned The capability in the URI isn't assigned to the specified user or group.
404 404013 Capability not found The capability in the URI 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.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Quality Warning Trigger by ID

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

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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.22. 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.

URI

DELETE /api/api-version/schedules/schedule-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
schedule-id The ID of the schedule to delete. To determine what schedules are available, call List Server Schedules.

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400059 Error deleting the schedule. An unspecified error occurred during the deletion operation.
404 404023 Schedule not found The specified schedule doesn't correspond to an existing schedule on the site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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

URI

Delete site

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

DELETE /api/api-version/sites/site-name?key=name

DELETE /api/api-version/sites/content-url?key=contentUrl

Delete site asynchronously (beginning in API 3.18)

DELETE /api/api-version/sites/async-delete/site-id

DELETE /api/api-version/sites/async-delete/site-name?key=name

DELETE /api/api-version/sites/async-delete/content-url?key=contentUrl

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to delete.
site-name The name of the site to delete. If you specify a site name, you must also include the parameter key=name.
content-url

The permanent name of the site to sign in to. The content URL appears in the URL path of Tableau content in your browser address bar after the Tableau Server URL.

mySite is the content URL in the following example:

http://<server or cloud URL>/#/site/mySite/explore

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

Delete site

204

Delete site asynchronously (beginning in API 3.18)

201

Response Body

Delete site

None

Delete site asynchronously (beginning in API 3.18)

<tsResponse>
   <job id="job-id"
     mode="mode"
     type="type"
	 progress="progress"
	 createdAt="createdAt"
	 finishCode="finishCode" />
</tsResponse>

The <job> element returns the following attributes:

  • job-id is a unique identifier for the job. You can use the value of this attribute to check the status of the delete job by passing it to the Query Job(Link opens in a new window) method.

  • mode has the value of Asynchronous.

  • type has the value of SiteDelete.

  • progress is set to 0 when the asynchronous delete job is created, and then changes to 100 when the job is complete. This value indicates percentage of job progress.

  • createdAt provides a complete date and time that indicates when asynchronous delete was initiated.

  • finishCode is set to 1 when the asynchronous delete job is created, and then changes to 0 when the job is complete.

Version

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

Errors

HTTP status error Code Condition Details
403 403002 Deletion not allowed. An attempt was made to delete the default Tableau Server site.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

cURL Request Example

Delete site

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

curl "http://MY-SERVER/api/3.22/sites/marketing-site?key=contentUrl" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

Delete site asynchronously (beginning in API 3.18)

curl "http://MY-SERVER/api/3.22/sites/async-delete/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

curl "http://MY-SERVER/api/3.22/sites/async-delete/marketing-site?key=contentUrl" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

curl "http://MY-SERVER/api/3.22/sites/async-delete/marketing-site-name?key=name" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The responses above will return the job ID for a successful delete operation. You can use the value to check the status of the delete job by passing it to the Query Job(Link opens in a new window) method.

Delete Subscription

Deletes the specified subscription on Tableau Server or Tableau Cloud.

URI

DELETE /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the subscription.
subscription-id The ID of the subscription to delete. To determine what subscriptions are available, call Query Subscriptions.

JWT Access Scope

tableau:tasks:delete (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

None

Permissions

Tableau Server users can call this method to delete any subscription that they had permission to create. For details, see Create Subscription.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400062 Error deleting the subscription. An unspecified error occured during the deletion operation.
401 401002 User not authenticated. The user making the request has not been authenticated for this site.
403 403059 Delete forbidden. A non-administrator user called this method but doesn't have permission to delete the subscription.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete subscription

Deletes a specified subscription to a metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can delete subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:delete
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.22. 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 remove the tag from.
tag-name The name of the tag to remove from the data source.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or data source owners can delete a tag from a data source only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400077 Error deleting tag There was a problem deleting the tag from the specified data source.
403 403004 Deleting tags forbidden A non-administrator user called this method but doesn't have permission to delete a tag from the specified data source.
404 404000 Site not found The site ID or URL namespace 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.
404 404007 Tag not found The tag in the URI doesn't exist for the specified data source.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Tag from Database

Delete a tag from a database.

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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.22. 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.

URI

DELETE /api/api-version/sites/site-id/views/view-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
view-id The ID of the view to remove the tag from.
tag-name The name of the tag to remove from the view.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or workbook owners can delete a tag from a workbook only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400078 Error deleting tag There was a problem deleting the tag from the specified view.
403 403004 Deleting tags forbidden A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404007 Tag not found The tag in the URI doesn't exist for the specified workbook.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Tag from Workbook

Deletes a tag from the specified workbook.

URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to remove the tag from.
tag-name The name of the tag to remove from the workbook.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or workbook owners can delete a tag from a workbook only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400051 Error deleting tag There was a problem deleting the tag from the specified workbook.
403 403004 Deleting tags forbidden A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404007 Tag not found The tag in the URI doesn't exist for the specified workbook.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete the Extract from a Data Source

Delete the extract of a data source in a site.

URI

POST /api/api-version/sites/site-id/datasources/datasource-id/deleteExtract

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The LUID of the site.
datasource-id The LUID of the datasource whose extract is to be deleted.

Permissions

Extracts for data sources can be deleted by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

Response Code

204 No Content

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.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"

Response body:

None.

Delete User from Data-Driven Alert

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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.
user-id The ID (not name) of the user to remove from the data-driven alert.

Version: Available in API 3.2 (Tableau Cloud / Tableau Server 2018.3) and later. Version Overview(Link opens in a new window)

License: No additional license required.>

Permissions: This method can only be called by server administrators and site administrators, and by users who are owners of the specified alert.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:data_driven_alerts:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

None

Response Code

204

Response Body

None

Version

Errors

HTTP status error Code Condition Details
403 403004 Delete forbidden A user called this method who does not have the required permissions.
403 409029 Deleting recipient from data-driven alert forbidden The user is not authorized to remove the recipient from the data-driven alert.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 Resource Not Found The user ID specified in the request body is invalid.
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7/users/ff43cb47-f208-4d2f-9a22-0fbb6d29f7f1" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

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 the CSV Import File Guidelines(Link opens in a new window).

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that users are being deleted from.

Request Body

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

--boundary-string
Content-Disposition: form-data; name=\"tableau_user_delete\"; filename=\"users.csv\"
Content-Type: text/csv
--boundary-string--

Permissions

This method can only be called by server and site administrators.

Response Code

204

Response Body

None

Version

Version 3.15 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 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/delete \
-H 'cache-control: no-cache' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-H 'x-tableau-auth: AVjAKZb3SQimzoqyMmQXEg|9OSHQrwCXF83SIR2XCuDEK91AM7v3FZr' \
-F tableau_user_delete=@users.csv

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.

URI

DELETE /api/api-version/sites/site-id/favorites/user-id/views/view-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
user-id The ID of the user to remove the favorite from.
view-id The ID of the view to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a view only from their own favorites.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Forbidden Favorites access A non-administrator user attempted to delete a view from a different user's favorites.
404 404000 Site not found The site ID or URL namespace 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
404 404010 View not a favorite The view ID in the URI exists but is not a favorite of the specified user.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete View Permission

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

URI

DELETE /api/api-version/sites/site-id/views/view-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/views/view-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
view-id The ID of the view to delete permissions for. You can obtain this ID by calling Query Views for Site.
group-id The ID of the group to remove the permission for.
user-id The ID of the user to remove the permission for.
capability-name

The capability to remove the permission for.

The valid capabilities for a view are AddComment, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission.

Request Body

None

Permissions

Users who are not server administrators or site administrators can delete permissions from a view only if they have ChangePermissions permissions on the view (either explicitly or implicitly).

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:permissions:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a view.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to delete permissions on the view.
403 403039 Project permissions locked The parent project that contains the specified view has its permissions locked.
403 403096 Parent workbook tabs enabled The specified view currently has permissions inherited from its parent workbook. View permission can be deleted if the parent workbook has its tabs disabled.
404 404000 Site not found The site ID or URL namespace 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.
404 404011 View not found The view ID in the URI 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 an invalid capability value (other than Allow or Deny).
404 404014 Capability not assigned The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny).
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/fbfa6f03-982c-4930-8ec1-d5949a19125d/views/0524c7ce-250b-45b1-adf2-d08f1648643c/permissions/users/ff43cb47-f208-4d2f-9a22-0fbb6d29f7f1/AddComment/Allow" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

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.

URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to remove.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a workbook for which they have Read (view) and Delete permissions (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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.

URI

DELETE /api/api-version/sites/site-id/favorites/user-id/workbooks/workbook-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to remove the favorite from.
workbook-id The ID of the workbook to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can remove a workbook only from their own favorites.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Access to Favorites forbidden A non-administrator user attempted to delete a workbook from a different user's favorites.
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.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404010 Workbook not a favorite The workbook ID in the URI exists but belongs to a different user.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Workbook Permission

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

URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/permissions/users/user-id/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to remove the permission for.
group-id The ID of the group to remove the permission for.
user-id The ID of the user to remove the permission for.
capability-name

The capability to remove the permission for. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, Write, RunExplainData, and CreateRefreshMetrics.

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Users who are not server administrators or site administrators can delete permissions from a workbook only if they have ChangePermissions permission for workbook (either explicitly or implicitly).

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:permissions:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read, Share_view, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to delete permissions from 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 The user ID in the URI doesn't correspond to an existing user.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not found The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny at the end of the URI.
404 404013 Capability not assigned The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny).
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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.


Deletes a specific dashboard extension from the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: Can only be called by users with site or server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Download Data Source

Downloads a data source in .tdsx format.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/content

GET /api/api-version/sites/site-id/datasources/datasource-id/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.22. 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 download.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the data source specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the data source. You can use this parameter to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Users who are not server administrators or site administrators can download a data source only if they have ExportXml permission for the data source (either explicitly or implicitly).

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:datasources:download

Response Code

200

Response Body

The data source content in .tdsx format (Content-Type: application/octet-stream).

The response will have the following content disposition header:

Content-Disposition: name="tableau_datasource"; filename="datasource-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403028 Read forbidden A non-administrator user attempted to download a data source, but the caller doesn't have Read 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 ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > my-datasource.tdsx

The response is a file that contains the data source.

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.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number/content

Parameter Values

api-version The version of the API to use, such as 3.22. 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 download.
revision-number The revision number of the data source to download. To determine what versions are available, call Get Data Source Revisions.

Request Body

None

Permissions

Tableau Server users who are site administrators can download data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

200

Response Body

The data source content in .tdsx format (Content-Type: application/octet-stream).

The response will have the following content disposition header:

Content-Disposition: name="tableau_datasource"; filename="datasource-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403028 Read forbidden A non-administrator user attempted to download a data source, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
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.
404 404024 Data source revision not found The revision number in the URI doesn't correspond to an existing data source revision.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Download Flow

Downloads a flow in .tfl or .tflx format.

URI

GET /api/api-version/sites/site-id/flows/flow-id/content

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-id The ID of the flow to download.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can download a flow only if they have download permission for the flow (either explicitly or implicitly).

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403097 Read forbidden A non-administrator user attempted to download a flow, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" >

Response: The response is a file that contains the flow.

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.

URI

GET /api/api-version/sites/site-id/views/view-id/crosstab/excel

GET /api/api-version/sites/site-id/views/view-id/crosstab/excel?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/views/view-id/crosstab/excel?vf_<fieldname>=filter-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
view-id The ID of the view to use as the source of the crosstab to be downloaded as an .xlsx file.
max-age-minutes (Optional) The maximum number of minutes an .xlsx file will be cached on the server before being refreshed. To prevent multiple .xlsx requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
filter-value The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter /excel?vf_year=2017 would only display data from the year 2017. To learn more, see View filter queries.

Request Body

None

Permissions

To export a crosstab to an .xlsx of a view, users who are not server administrators or site administrators need Read and ExportData permissions for the workbook containing the view and for the view itself.

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .xlsx file. The response header content will have Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

Version

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

Errors

HTTP status error Code Condition Details
400 400101 Unknown error

There was a problem downloading or querying this file.

400 400130 Unknown error

The view ID in the URI doesn't correspond to a view available on the specified site.

401 4001XX Unauthorized

The authentication token for the request is missing, invalid, or expired.

403 4031XX Unauthorized

A user attempted to download a .xlsx file without Read and/or ExportData permissions for the workbook or view, and is not an administrator.

404 404xxx Site or view not found The site or view specified in the request could not be found.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/crosstab/excel?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response is a file that contains the crosstab, whose data is no older than 60 minutes, saved as an .xlsx file.

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.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/content

GET /api/api-version/sites/site-id/workbooks/workbook-id/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to download.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the workbook specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can download a workbook only if they have ExportXml permission for the workbook (either explicitly or implicitly).

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:workbooks:download

Response Code

200

Response Body

One of the following, depending on the format of the workbook:

  • The workbook's content in .twb format (Content-Type: application/xml)
  • The workbook's content in .twbx format (Content-Type: application/octet-stream)

In both cases, the response will have the following content disposition header:

Content-Disposition: name="tableau_workbook"; filename="workbook-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403019 Read forbidden A non-administrator user attempted to download a workbook, but the caller doesn't have ExportXml permission.
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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > c:\files\my-workbook.twbx

The response is a file that contains the workbook.

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.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?type=page-type&orientation=page-orientation

GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?maxAge=max-age-minutes

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to use as the source of the .pdf file to be downloaded.
max-age-minutes (Optional) The maximum number of minutes a workbook PDF will be cached before being refreshed. To prevent multiple PDF requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
page-orientation (Optional) The orientation of the pages in the .pdf file produced. The value can be Portrait or Landscape. If this parameter is not present the page orientation will default to Portrait.
page-type

(Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be: A3, A4, A5, B5, Executive, Folio, Ledger, Legal, Letter, Note, Quarto, or Tabloid.

If this parameter is not present the page type will default to Legal.

Request Body

None

Permissions

To download a .pdf of a workbook, Tableau Server users who are not server administrators or site administrators need Read and ExportImage permissions for the workbook. The user needs Read and ExportImage permissions for a view in a workbook in order for that view to appear in the .pdf.

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .pdf file. The response header content will have Content-Type:application/pdf.

Version

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

Errors

HTTP status error Code Condition Details
400 400101 Unknown error

There was a problem downloading or querying this workbook.

403 403004 Unauthorized

A non-administrator user attempted to download a pdf, but they don't have Read and/or ExportImage permissions for the workbook or user does not have Read permissions for the views of the workbook.

403 403105 Unauthorized

The PDF export feature is disabled on the server or the server is not configured to allow PDF exports using the REST API.

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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/pdf?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -o "response.pdf"

The response is a file that contains the workbook, whose data is no older than 60 minutes, saved as a pdf.

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.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/powerpoint

GET /api/api-version/sites/site-id/workbooks/workbook-id/powerpoint?maxAge=max-age-minutes

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to use as the source of the .pptx file to be downloaded.
max-age-minutes (Optional) The maximum number of minutes a workbook .pptx will be cached before being refreshed. To prevent multiple .pptx requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.

Request Body

None

Permissions

To download a .pptx of a workbook, Tableau Server users who are not server administrators or site administrators need Read and ExportImage permissions for the workbook. The user needs Read and ExportImage permissions for a view in a workbook in order for that view to appear in the .pptx.

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .pptx file. The response header content will have Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation.

Version

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

Errors

HTTP status error Code Condition Details
400 400101 Unknown error

There was a problem downloading or querying this workbook.

401 4001XX Unknown error

There was a problem downloading or querying this workbook.

403 4031XX Unauthorized

A non-administrator user attempted to download a .pptx file, but they don't have Read and/or ExportImage permissions for the workbook or user does not have Read permissions for the views of the workbook.

403 403105 Unauthorized

The PowerPoint export feature is disabled on the server or the server is not configured to allow PowerPoint exports using the REST API.

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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/powerpoint?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -o "response.pptx"

The response is a file that contains the workbook, whose data is no older than 60 minutes, saved as a .pptx.

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.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to download.
revision-number The revision number of the workbook to download. To determine what versions are available, call Get Workbook Revisions. Note that the current revision of a workbook cannot be accessed by this call; use Download Workbook instead.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the workbook specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Users who are site administrators can download workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can download workbook revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified workbook.
  • Save (write) permissions for the project that contains the workbook.

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:workbooks:download

Response Code

200

Response Body

One of the following, depending on the format of the workbook:

  • The workbook's content in .twb format (Content-Type: application/xml)
  • The workbook's content in .twbx format (Content-Type: application/octet-stream)

In both cases, the response will have the following content disposition header:

Content-Disposition: name="tableau_workbook"; filename="workbook-filename"

Version

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

Errors

HTTP status error Code Condition Details
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403019 Read forbidden A non-administrator user attempted to download a workbook, but the caller doesn't have required permissions.
404 404024 Workbook revision not found The revision number in the URI doesn't correspond to an existing data source revision.
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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Enable or disable analytics extensions on server

Enables or disables analytics extensions on a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

POST /api/api-version/sites/site-id/encrypt-extracts

Parameter Values

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

Request Body

None

Permissions

Tableau Server administrators can call this method.

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 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Generate current metric value insight bundle

Generates a bundle the current aggregated value for each metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can create a metric in a definition as long as Permissions Overview

License: No additional license required.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Generate detail insight bundle

Generates a detail insight bundle.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Generate springboard insight bundle

Generates a springboard insight bundle.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Get a Webhook

Returns information about the specified webhook.

URI

GET /api/3.6/sites/<site-id>/webhooks/<webhook-id>

Parameter Values

site-id The ID of the site that contains the webhook. 
webhook-id The ID of the webhook.  

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

<tsResponse>
  <webhook
    id="webhook-id"
    name="webhook-name"
    isEnabled="true"
    statusChangeReason=""
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url"/>
      </webhook-destination>
      <owner id="webhook_owner_luid" name="webhook_owner_name"/>
  </webhook>
</tsResponse>

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.


Gets the details of a specific dashboard extension on the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: Can only be called by users with site or server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.11 (Tableau Cloud March 2021/ Server 2021.1) Version Overview

Permissions: Can only be called by users with site or server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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 the details of the specified ask data lens.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can be called by users who have Read access to the lens. Permissions Overview

License: No additional license required.

Access Scope: `tableau:lenses:read` Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.17 ( Tableau Cloud December 2022) and later. Not available for Tableau Server. Version Overview

Permissions: Tableau administrators can get statistics for all content Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.


Gets the details of a specific dashboard extension on the blocked list of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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: Deprecated in API 3.17 - the following resource is no longer supported and will be retired in future releases: 

URI GET api/api-version/sites/site-id/connected-applications/client-id

Parameter Values

api-version The version of the API to use, such as 3.22. 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

The request returns details about the connected app, including the following:

  • <secret>: Information related to the secret only if it has been previously generated. To create a secret for a connected app, see Create Connected App Secret. To get the secret value, see Query Connected App Secret.
  • <name>: Name of the connected app.
  • <enabled>: Whether the connected app is enabled or not.
  • <clientId>: The ID of the connected app.
  • <projectId>: The project that the connected app's access level is scoped to.
  • <domainSafelist>: If specified, one or more domains that the connected app is allowed to be hosted on.
  • <unrestrictedEmbedding>: Whether the connected app can be hosted on all domains. If false is returned, the <domainSafelist> attribute determines the domain access.

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: Deprecated in API 3.17 - the following resource is no longer supported and will be retired in future releases: 

URI GET api/api-version/sites/site-id/connected-applications/client-id/secrets/secret-id

 

Parameter Values

api-version The version of the API to use, such as 3.22. 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

The request returns details about the secret associated with the connected app, including the following:

  • <value>: The token value of the secret.
  • <id>: The ID of the secret.

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.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) Version Overview

Permissions: Search results will be limited to those objects that the Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.19 ( Tableau Cloud March 2023 / Server Version Overview

Permissions: Suggestions will be limited to those objects that the Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: This method can be called by users that have permissions Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

GET /api/api-version/sessions/current

Parameter Values

api-version

The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

This method can be called by all authenticated users.

Response Code

200

Response Body

<tsResponse">
  <session>
	<site id="a946d998-2ead-4894-bb50-1054a91dcab3"
  	  name="site-name"
	  contentUrl=""
      adminMode="admin-mode"
      disableSubscriptions="disable-subscription-flag"
      state="state"
      revisionHistoryEnabled="revision-history-enabled-flag"
	  subscribeOthersEnabled="subscribe-others-enabled-flag"
	  guestAccessEnabled="guest-access-enabled-flag"
	  cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	  editingFlowsEnabled="editing-flows-enabled-flag"
      schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	  extractEncryptionMode="extract-encryption-mode"
	  mobileBiometricsEnabled="mobile-biometrics-enabled-flag"
	  sheetImageEnabled="sheetimage-enabled-flag"
	  catalogingEnabled="catalog-enabled-flag"
	  derivedPermissionsEnabled="true"/>
    <user authSetting="ServerDefault"
	  externalAuthUserId=""
	  id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
	  lastLogin="2020-04-29T04:59:08Z"
	  name="workgroupuser"
	  siteRole="ServerAdministrator"/>
 </session>
</tsResponse>
        

The response for users without administrator permissions contains only the site user, id, name, and content-url attributes.

Version

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

Errors

HTTP status error Code Condition Details
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example Response

<tsResponse">
  <session>
    <site id="a946d998-2ead-4894-bb50-1054a91dcab3"
	  name="Default"
	  contentUrl="" adminMode="ContentAndUsers"
	  disableSubscriptions="false"
	  state="Active"
	  revisionHistoryEnabled="true"
	  subscribeOthersEnabled="true"
	  guestAccessEnabled="false"
	  cacheWarmupEnabled="true" [REMOVED IN API 3.19]
      editingFlowsEnabled="false"
      schedulingFlowsEnabled="false"
	  extractEncryptionMode="enabled"
	  mobileBiometricsEnabled="false"
	  sheetImageEnabled="true"
	  catalogingEnabled="true"
	  derivedPermissionsEnabled="true"/>
    <user authSetting="ServerDefault"
	  externalAuthUserId=""
	  id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
	  lastLogin="2020-04-29T04:59:08Z"
	  name="workgroupuser"
	  siteRole="ServerAdministrator"/>
  </session>
</tsResponse>
        

Get Custom View

Gets the details of a specified custom view.

Version: Available in API 3.18 (Tableau Cloud December 2024) and later. Not available for Tableau Server. Version Overview

License: No additional license required.

Permissions: Tableau administrators can get the details of a custom view. Other users can get the details of any custom view that they have Read permissions for.  Permissions Overview

JWT Access Scope: tableau:content:read     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

GET /api/api-version/sites/site-luid/customviews/custom-view-luid

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
custom-view-luid The LUID for the custom view being updated.

Request Body

None.

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:content:read

cURL Request Example

curl -L -X GET "https://qa-near/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/37d015c6-bc28-4c88-989c-72c0a171f7aa" -H "X-Tableau-Auth: njR9EGn0QSCpbDrUOh0IKg"wamRRyVFFUHTVwFL6OWEyOggxCwWYXuq"a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

200

Response Body

<tsResponse >
  <pagination pageNumber="1" pageSize="100" totalAvailable="1673"/>
  <customView
    id="37d015c6-bc28-4c88-989c-72c0a171f7aa"
    name="New name 2"
    createdAt="2016-02-03T23:35:09Z"
    updatedAt="2022-09-28T23:56:01Z"
    shared="false">
      <view id="8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f" name="circle"/>
      <workbook id="2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5" name="marks and viz types 2"/>
      <owner id="cdfe8548-84c8-418e-9b33-2c0728b2398a" name="workgroupuser"/>
  </customView>
</tsResponse>

{
  "pagination": {
	"pageNumber": "1",
	"pageSize": "100",
	"totalAvailable": "1673"
  },
  "customView": {
	"id": "37d015c6-bc28-4c88-989c-72c0a171f7aa",
	"name": "New name 2",
	"createdAt": "2016-02-03T23:35:09Z",
	"updatedAt": "2022-09-28T23:56:01Z",
	"shared": "false",
	"view": {
	  "id": "8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f",
	  "name": "circle"
	},
  	"workbook": {
	  "id": "2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5",
	  "name": "marks and viz types 2"
	},
	"owner": {
	  "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
	  "name": "workgroupuser"
    }
  }
}

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.

Version: Available in API 3.18 (Tableau Cloud December 2022) and later. Not available for Tableau Server. Version Overview

License: No additional license required.

Permissions: Tableau administrators download the image of a custom view. Other users candownload the image of any custom view that they have Publish permissions for.  Permissions Overview

JWT Access Scope: tableau:views:download     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

GET /api/api-version/sites/site-luid/customviews/custom-view-luid/image

GET /api/api-version/sites/site-id/customviews/view-id/image?resolution=image-resolution

GET /api/api-version/sites/site-id/customviews/view-id/image?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/customviews/view-id/image?vf_<fieldname>=filter-value

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
custom-view-luid The LUID for the custom view being updated.
image-resolution (Optional) The resolution of the image. Image width and actual pixel density are determined by the display context of the image. Aspect ratio is always preserved. Set the value to high to ensure maximum pixel density.
max-age-minutes (Optional) The maximum number of minutes a view image will be cached before being refreshed. To prevent multiple image requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
filter-value The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter /data?vf_year=2017 would only display data from the year 2017. To learn more, see View filter queries.

Request Body

None.

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

cURL Request Example

curl -L -X GET "https://qa-near/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/37d015c6-bc28-4c88-989c-72c0a171f7aa/image" -H "X-Tableau-Auth: njR9EGn0QSCpbDrUOh0IKg"wamRRyVFFUHTVwFL6OWEyOggxCwWYXuq"a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

200

Response Body

None. Tableau returns a an image file as a 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.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the task.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <dataAccelerationReport>
    <comparisonRecord site="Default" sheetURI="sheetURI" unacceleratedSessionCount="unacceleratedSessionCount" averageUnAcceleratedPLT="averageUnAcceleratedPLT" acceleratedSessionCount="acceleratedSessionCount" averageAcceleratedPLT="averageAcceleratedPLT" />
</tsResponse>
					
        

Attribute Values

sheetURI The URI of the sheet in the workbook.
unacceleratedSessionCount The number of sessions that were created to load the workbook sheet before it was accelerated. For example, if you loaded it 7 times in a row, the session is reused so the count will still be 1. Generally, the more data you compare, the better the comparison is. Note: If sheets were loaded but never accelerated, they are not shown.
averageUnAcceleratedPLT The average page load time for the sheet before it was accelerated.
acceleratedSessionCount The number of sessions that were created to load the workbook sheet after it was accelerated.
averageAcceleratedPLT The average page load time for the sheet after it was accelerated.

Version

In Tableau Server 2020.2 (API 3.8) through 2021.4 (API 3.15) data acceleration is supported.

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.

For more information, see REST API and Resource Versions.

Errors

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 40500 Invalid requests method Request type was not GET

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dataAccelerationReport" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:


<tsResponse version-and-namespace-settings>
  <dataAccelerationReport>
    <comparisonRecord site="Default" sheetURI="Live/Sheet1" unacceleratedSessionCount="0" averageUnAcceleratedPLT="0.0" acceleratedSessionCount="1" averageAcceleratedPLT="0.166" />
  ...
  </dataAccelerationReport>
</tsResponse>
          

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.

URI

GET /api/api-version/sites/site-id/tasks/dataAcceleration

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the task.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
<tasks>
 <task>
  <dataAcceleration id="id" consecutiveFailedCount="0" type="DataAccelerationTask">
    <schedule id="id" name="name" state="Active" priority="75" createdAt="2020-02-25T02:49:31Z" updatedAt="2020-02-25T04:00:44Z" type="DataAcceleration" frequency="Hourly" nextRunAt="2020-02-25T08:00:00Z">
     <frequencyDetails start="00:00:00" end="00:00:00">
	  <intervals>
		<interval hours="4"/>
	  </intervals>
     </frequencyDetails>
   </schedule>
   <workbook id="id"/>
  </dataAcceleration>
 </task>
 <task>
 ... additional tasks ...
 </task>
</tasks>
</tsResponse>
					
        

Version

In Tableau Server 2020.2 (API 3.8) through 2021.4 (API 3.15) data acceleration is supported.

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.

For more information, see REST API and Resource Versions.

Errors

403 409087 Permission denied The user isn't authorized to view data acceleration tasks.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 40500 Invalid requests method Request type was not GET

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/dataAcceleration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:


<tsResponse version-and-namespace-settings>
  <task>
   <dataAcceleration id="9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c" consecutiveFailedCount="0" type="DataAccelerationTask">
    <schedule id="9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5r4c" name="name" state="Active" priority="75" createdAt="2020-02-25T02:49:31Z" updatedAt="2020-02-25T04:00:44Z" type="DataAcceleration" frequency="Hourly" nextRunAt="2020-02-25T08:00:00Z">
     <frequencyDetails start="00:00:00" end="00:00:00">
      <intervals>
       <interval hours="4"/>
      </intervals>
     </frequencyDetails>
   </schedule>
  <workbook id="9t8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c"/>
 </dataAcceleration>
  </task>
</tsResponse>
          

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.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source to get revisions for.
datasource-id The ID of the data source to get revisions for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
       totalAvailable="total-available" />
  <revisions>
    <revision createdAt="date" revisionNumber="1" isDeleted="false">
      <user id="user-id" name="user-name"/>
    </revision>
    <revision createdAt="date" revisionNumber="2" isDeleted="false">
    </revision>
    <revision createdAt="date" revisionNumber="3" isCurrent="true">
        <user id="user-id" name="user-name"/>
    </revision>
  </revisions>
</tsResponse>
        

If the revision element includes the attribute isDeleted="true", the data source has been deleted and cannot be downloaded using the Download Data Source Revision method.

If a user has been deleted from the site, no <user> element is included in the <revision> element.

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403054 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 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 GET.

For more information, see Handling Errors.

Get Data-Driven Alert

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Users with the Administrator, Creator, or Explorer role can add DDAs to views they have permissions to.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:data_driven_alerts:read     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

Request Body

None

Response Code

200

Response Body

<tsResponse>
  <dataAlert id="alert-id" subject="alert-subject" creatorId="creator-id" createdAt="created-date" updatedAt="updated-date" frequency="alert-frequency" public="is-public-flag">
    <owner id="owner-id" name="username"/>
      <view id="view-id" name="view-name">
        <workbook id="workbook-id" name="workbook-name"/>
        <project id="project-id" name="project-name"/>
      </view>
      <recipients>
        <recipient id="recipient-id"/>
      </recipients>
  </dataAlert>
</tsResponse>
        

The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A user queried this method who does not have the required permissions
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
404 404000 Site not found The site ID or URL namespace 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.

Example

curl "http://MY-SERVER/api/3.22/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <dataAlert id="e5a4b73e-5cbb-412d-907e-f31cc31684f7" subject="Data alert - Shipping" creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-13T20:55:29Z" updatedAt="2018-08-21T00:05:34Z" frequency="daily" public="true">
    <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
    <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
      <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
      <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
    </view>
    <recipients>
      <recipient id="4"/>
    </recipients>
  </dataAlert>
</tsResponse>

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: 

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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: 

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.

URI

GET /api/api-version/sites/site-id/settings/embedding

Path Parameter Values

 
api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the views.

Request Body

None

Response Code

200

Permissions

Any Tableau Cloud or Tableau Server user can call this method.

Response Body

<tsResponse>
  <siteid="view-id"
        <settings unrestrictedEmbeddingname="true-or-false"
  </site>
</tsResponse>
        
Example Response
<tsResponse>
      <settings unrestrictedEmbedding="false"/>
    </site>
</tsResponse>

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/settings/embedding" -X GET -H "X-Tableau-Auth:1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"

Version

API version 3.16 and later.

Errors

HTTP status error Code Condition Details
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.

Get enabled state of analytics extensions on server

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

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

GET /api/api-version/sites/site-id/tasks/extractRefreshes/task-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
task-id The ID of the extract refresh that you want information about.

JWT Access Scope

tableau:tasks:read (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of extract refresh tasks that they own.

Response Code

200

Response Body

Tableau Server and Tableau Cloud return different payloads in response to this request.

Tableau Server Request

For Tableau Server an extract refresh task with a server schedule is returned.

Copy
<tsResponse>
  <task>
    <extractRefresh id="refresh_task_id"
      priority="nn"
      consecutiveFailedCount="n"
      type="REFRESH_EXTRACT">
        <schedule id="schedule_id"
          name="schedule_name"
          state="state"
          priority="nn"
          createdAt="DATE_TIME"
          updatedAt="DATE_TIME"
          type="Extract"
          frequency="frequency"
          nextRunAt="DATE_TIME" />
        <datasource id="datasource_id" />
    </extractRefresh>    
  </task>
  <task>
    <!-- ... additional tasks ... -->
  </task>
</tsResponse>
Copy
[
  {
    "extractRefresh": {
      "id": "refresh_task_id",
      "priority": "nn",
      "consecutiveFailedCount": "n",
      "type": "REFRESH_EXTRACT",
      "schedule": {
        "id": "schedule_id",
        "name": "schedule_name",
        "state": "state",
        "priority": "nn",
        "createdAt": "DATE_TIME",
        "updatedAt": "DATE_TIME",
        "type": "Extract",
        "frequency": "frequency",
        "nextRunAt": "DATE_TIME"
      },
      "datasource": {
        "id": "datasource_id"
      }
    }
  },
  []
]

Tableau Cloud Request

For Tableau Cloud an extract refresh task with its frequencye is returned.

Response for a server schedule on Tableau Server:

Copy
<tsResponse>
  <task>
    <extractRefresh id="0ece2369-c4eb-4382-be0f-961039d708a0" priority="50" consecutiveFailedCount="5" type="RefreshExtractTask">
      <schedule frequency="Weekly" nextRunAt="2023-06-08T04:50:00Z">
        <frequencyDetails start="21:50:00">  
          <intervals>
            <interval weekDay="Wednesday"/>
          </intervals>
        </frequencyDetails>
       </schedule>
      <workbook id="7e766949-7166-4b3d-90ba-784f7575743b"/>
    </extractRefresh>
  </task>
</tsResponse>
Copy
{
  "task": {
    "extractRefresh": {
      "id": "0ece2369-c4eb-4382-be0f-961039d708a0",
      "priority": "50",
      "consecutiveFailedCount": "5",
      "type": "RefreshExtractTask",
      "schedule": {
        "frequency": "Weekly",
        "nextRunAt": "2023-06-08T04:50:00Z",
        "frequencyDetails": {
          "start": "21:50:00",
          "intervals": {
            "interval": [
              { "weekDay": "Thursday" }
            ]
          }
        }
      },
      "workbook": {
        "id": "7e766949-7166-4b3d-90ba-784f7575743b"
      }
    }
  }
}

Version

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

Errors

403 403004 Operation unauthorized The user is not authorized to get the task.
404 404026 Task not found The task ID in the URI doesn't correspond to an existing task.
405 40500 Invalid requests method Request type was not GET

For more information, see Handling Errors.

Get Favorites for User

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

URI

GET /api/api-version/sites/site-id/favorites/user-id

GET /api/api-version/sites/site-id/favorites/user-id?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
user-id The ID of the user for which you want to get a list favorites.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they are the user for which they want to get a list of favorites.

Response Code

200

Response Body

<tsResponse version-and-namespace-settings>
  <favorites>
	<favorite label="favorite-label">
	  <view id="view-luid"
		name="view-name"
		contentUrl="content-url"
		createdAt="created-at"
		updatedAt="updated-at"
		viewUrlName="view-url-name">
	      <workbook id="workbook-luid"/>
		  <project id"project-luid"/>
		  <tags />
	  </view>
	</favorite>
	<!--      . . .more favorites. . .      -->
  </favorites>
</tsResponse>

The value of view-url-name is the name of the view in its URL. For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1 in your browser address bar, then the view-url-name would be VIEW_1. Modifying the name (display name) of a view will not impact the view-url-name (path element of the view's URL).

Response when favorite items have been deleted

In the case where an item selected as a favorite has been deleted the reponse body will contain only the label of the favorite.

<tsResponse>
  <favorites>
	<favorite label="favorite-label">
  </favorites>
</tsResponse>
        

Version

Version 2.5 and later. Support for favorite projects added in version 3.1. For more information, see REST API and Resource Versions.

Errors

403 403004 Forbidden Favorites access A non-administrator user called this method but doesn't have permission to view the specified user's favorites.
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.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/favorites/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="Global Economic Indicators">
	  <view id="796c9371-a180-46b7-9970-feffe8573d47"
		name="Overview"
		contentUrl="Superstore/sheets/Overview"
		createdAt="2015-11-09T21:39:59Z"
		updatedAt="2019-08-30T21:05:37Z"
		viewUrlName="Overview" >
		  <workbook id="65e18031-b2f0-4ab6-994b-2c5520b830bb"/>
		  <owner id="abb3e4c1-e650-4704-870a-03fb7615136f"/>
		  <project id="3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"/>
		  <tags/>
	  </view>
	</favorite>
  </favorites>
</tsResponse>

Get Flow Run

Gets a flow run.

URI

GET /api/api-version/sites/site-id/flows/runs/flow-run-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-run-id The ID of the flow run.

Request Body

None

Response Code

200

Response Body

<tsResponse>
   <flowRun id="flowRun_id"
    flow id="flow_id"
    status="status"
    startedAt="DATE_TIME"
    completedAt="DATE_TIME"
    progress="100"
    backgroundJobId="background_job_id"/>
     <flowParameterRuns>
       <parameterRuns parameter Id="parameter_id"
        name="parameter_name"
        description="parameter_description"
        overrideValue="override_value"/>
     </flowParameterRuns>
   </flowRun>
</tsResponse> 

The status attribute can be: Pending, InProgress, Success, Cancelled, or Failed.

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Get forbidden User does not have permissions to get the flow run. A user can view a flow run if they have permission to view the flow.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404036 Flow run not found The flow run ID in the URI doesn't correspond to an existing flow run.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Flow Run Task

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

URI

GET /api/api-version/sites/site-id/tasks/runFlow/task-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
task-id The ID of the scheduled flow run task that you want information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of scheduled flow run tasks that they own.

Response Code

200

Response Body

<tsResponse>
   <task>
     <flowRun id="flowRun_id"
      priority="nn"
      consecutiveFailedCount="n"
      type="RunFlowTask">
       <schedule id="schedule_id"
        name="schedule_name"
        state="state"
        priority="nn"
        createdAt="DATE_TIME"
        updatedAt="DATE_TIME"
        type="flowRun"
        frequency="frequency"
        nextRunAt="DATE_TIME"/>
         <flow id="flow_id"
          name="flow_name"/>
	    <parameters>
		<parameter id="parameter_id"
                type="data_type"
                name="parameter_name"
                description="parameter_description"
                value="parameter_value"
                isRequired="true-or-false">
		  <domain xsi:type="flowParameterListDomainType-or-flowParameterAnyDomainType"
                  domainType="domain_type">
		  </domain>
	        </parameter>
	    </parameters>
     </flowRun>
   </task>
</tsResponse> 

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Operation unauthorized The user is not authorized to get the task.
404 404026 Task not found The task ID in the URI doesn't correspond to an existing task.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/runFlow/1bff10bb-57ae-43df-8774-a86d14aef432" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings> <task> <flowRun id="1bff10bb-57ae-43df-8774-a86d14aef432" priority="50" consecutiveFailedCount="2" type="RunFlowTask"> <schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T18:12:09Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T18:14:00Z"/> <flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/> <parameters> <parameter id="ebfad780-c19f-42a2-822a-406468269a02" type="string" name="Region" description="" value="North" isRequired="false"> <domain xsi:type="flowParameterListDomainType" domainType="any"> </domain> </parameter> </parameters> </flowRun> </task> </tsResponse>

Get Flow Run Tasks

Returns a list of scheduled flow tasks for the site.

URI

GET /api/api-version/sites/site-id/tasks/runFlow

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of scheduled flow tasks for the flows that they own.

Response Code

200

Response Body

<tsResponse>
   <tasks>
     <task>
       <flowRun id="flowRun_id"
        priority="nn"
        consecutiveFailedCount="n"
        type="RunFlowTask">
         <schedule id="schedule_id"
          name="schedule_name"
          state="state"
          priority="nn"
          createdAt="DATE_TIME"
          updatedAt="DATE_TIME"
          type="flowRun"
          frequency="frequency"
          nextRunAt="DATE_TIME" />
           <flow id="flow_id"/>
             <parameters>
               <parameter id="parameter_id"
                type="data_type"
                name="parameter_name"
                description="parameter_description"
                value="parameter_value"
                isRequired="true-or-false">
		  <domain xsi:type="flowParameterListDomainType-or-flowParameterAnyDomainType"
                  domainType="domain_type">
		    </domain>
                </parameter>
	      </parameters>
       </flowRun>
      </task>
        ... additional tasks ...
    </tasks>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/runFlow" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
    <tasks>
        <task>
            <flowRun id="1bff10bb-57ae-43df-8774-a86d14aef432" priority="50" consecutiveFailedCount="2" type="RunFlowTask">
                <schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:32:00Z"/>
                <flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/>
		 <parameters>
			<parameter id="ebfad780-c19f-42a2-822a-406468269a02" type="string" name="Region" description="" value="North" isRequired="false">
			<domain xsi:type="flowParameterListDomainType" domainType="any">
			</domain>
			</parameter>
	     </parameters>
            </flowRun>
        </task>
        <task>
            <flowRun id="f11741cb-9646-4fb8-bbac-6d099c8d56b9" priority="50" consecutiveFailedCount="2" type="RunFlowTask">
                <schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:32:00Z"/>
                <flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/>
		 <flowParameterSpecs/>
            </flowRun>
        </task>
        <task>
            <flowRun id="357aaf2b-758d-4feb-a447-822528635a67" priority="44" consecutiveFailedCount="2" type="RunFlowTask">
                <schedule id="6d4e61d0-2e2f-4f48-abc8-0695b95a5287" name="Every 15 mins!" state="Active" priority="50" createdAt="2018-11-08T20:45:47Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:45:00Z"/>
                <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good"/>
		 <flowParameterSpecs/>
            </flowRun>
        </task>
   </tasks>
</tsResponse> 

Get Flow Runs

Get flow runs.

URI

GET /api/api-version/sites/site-id/flows/runs

GET /api/api-version/sites/site-id/flows/runs?filter=filter-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site.
filter-expression (Optional) An expression that lets you specify a subset to return. You can filter on predefined fields such as the userId of the user who started the flow run, flowId, progress, startedAt, and completedAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.

Request Body

None

Response Code

200

Response Body

<tsResponse>
   <flowRuns>
     <flowRuns id="flowRuns_id"
      flow id="flow_id"
      status="status"
      startedAt="DATE_TIME"
      completedAt="DATE_TIME"
      progress="100"
      backgroundJobId="background_job_id"/>
       <flowParameterRuns>
	  <parameterRuns parameterId="parameter_id"
          name="parameter_name"
          description="parameter_description"
	   overrideValue="override_value"/>
	</flowParameterRuns>
    </flowRuns>
     ... additional flow runs....
</tsResponse> 

The status attribute can be: Pending, InProgress, Success, Cancelled, or Failed.

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Get forbidden User does not have permissions to get the flow run.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the filter doesn't correspond to an existing user.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Group Set

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

Version: Available in API 3.22 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:read     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

GET /api/api-version/sites/site-id/groupsets/group-set-id

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-set-id The ID of the group set you want information for.

Request Body

None

cURL Request Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/8cf3b6c1-839f-4eae-b41f-2144165193f2" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy
<tsResponse version-and-namespace-settings>
  <groupSet id="8cf3b6c1-839f-4eae-b41f-2144165193f2">
    <group id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"  
      name="All Users"
      groupCount="2">
    </group>
    <group id="4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234" 
      name="Researchers" >
    </group>
  </groupSet>
</tsResponse>
Copy
{
  "groupSet": {
    "@id": "8cf3b6c1-839f-4eae-b41f-2144165193f2",
    "group": [
      {
        "@id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d",
        "@name": "All Users",
        "@groupCount": "2"
      },
      {
        "@id": "4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234",
        "@name": "Researchers"
      }
    ]
  }
}

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method The request type wasn’t GET.
409 409120 Group set not found The group set ID in the request body doesn't correspond to an existing group set.

For more information, see Handling Errors.

Get Groups for a User

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

URI

GET /api/api-version/sites/site-id/users/user-id/groups

GET /api/api-version/sites/site-id/users/user-id/groups?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
user-id The ID of the user whose group memberships are listed.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can only be called by server administrators and site 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:users:read

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
  <groups>
    <group id="user-id" name="user-name" >
    	<domain name="group-domain-name"/>
	</group>
    <!--      . . . additional groups ...      -->
  </groups>
</tsResponse>
        

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
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.
404 404012 User not found The group ID in the URI doesn't correspond to an existing user.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/groups" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <groups>
    <group id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="All Users" >
	  <domain name="mydomain"/>
	</group>
	<group id="4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234" name="Researchers" >
	  <domain name="mydomain"/>
    </group>
  </groups>
</tsResponse>

Get Identity Pool

Get information about an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

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

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

URI

GET /api/api-version/sites/site-id/tasks/linked/linked-task-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
linked-task-id The ID of the scheduled linked task that you want information about.

Request Body

None

Permissions

All Tableau users can view linked tasks information, but can only see information about the flows in the response body if they have permissions to flows included in the linked task.

Response Code

200

Response Body

<tsResponse>
   <linkedTasks id= "linkedTasks-id"
      numSteps="number-of-steps">
       <schedule id="schedule_id"
        name="schedule-name"
        state="Active-or-Suspended"
        priority="priority"
        createdAt="datetime-created"
        updatedAt="datetime-updated"
        type="schedule-type"
        frequency="frequency"
        nextRunAt="datetime-nextrun"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="linked-tasks-step-id>
          stepNumber="step-number"
          stopDownstreamTasksOnFailure="true-or-false"/>
          ...additional linked tasks steps...
         <task>
           <flowRun id="flow-run-id"
            priority="priority"
            consecutiveFailedCount="consecutive-failed-count"
            type="task-type">
            <flow id = flow-id"
             name="flow-name"
           </flowRun>
         </task>
       </linkedTaskSteps>
       ...additional linked tasks steps...
     </linkedTasksSteps>
   </linkedTasks>
</tsResponse> 

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Operation unauthorized The user is not authorized to get the task.
404 404045 Linked task not found The task ID in the URI doesn't correspond to an existing linked task.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/linked/1bff10bd-57ae-37df-8774-a86d14aef432" -X GET -H "X-Tableau-Auth:12ab34cd56ef98ab90ce12ef34ab52cd"

Example response:

<tsResponse version-and-namespace-settings> <linkedTasks id="18d267af-4c40-4dz6-8234-6ag8c3dea67f" numSteps="2"> <schedule id="3ee04ae9-4dbf-45b5-a6d6-18fa19f2jb8a" name="Run Flow - Every Sunday - 4:00PM" state="Active" priority="50" createdAt="2021-01-21T19:15:53Z" updatedAt="2022-02-27T16:00:59Z" type="Flow" frequency="Weekly" nextRunAt="2022-03-06T16:00:00Z"/> <linkedTaskSteps> <linkedTaskSteps id="738fffc7-6a21-4af5-b49e-2c47f51480d2" stepNumber="1" stopDownstreamTasksOnFailure="true"> <task> <flowRun id="690c3b2c-a309-4683-9e6e-166517dc8598" priority="50" consecutiveFailedCount="0" type="RunFlowTask"> <flow id="56809d67-aca9-4f08-9fdc-4b6473c3ff02" name="r-3"/> </flowRun> </task> </linkedTaskSteps> </tsResponse>

Get Linked Tasks

Returns a list of scheduled linked tasks for a site.

URI

GET /api/api-version/sites/site-id/tasks/linked

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.

Request Body

None

Permissions

All Tableau users can view linked tasks information, but can only see information about the flows in the response body if they have permissions to flows included in the linked task.

Response Code

200

Response Body

<tsResponse>
   <linkedTasks>
     <linkedTasks id= "linkedTasks-id"
      numSteps="number-of-steps">
       <schedule id="schedule_id"
        name="schedule-name"
        state="Active-or-Suspended"
        priority="priority"
        createdAt="datetime-created"
        updatedAt="datetime-updated"
        type="schedule-type"
        frequency="frequency"
        nextRunAt="datetime-nextrun"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="linked-tasks-step-id>
          stepNumber="step-number"
          stopDownstreamTasksOnFailure="true-or-false"/>
          ...additional linked tasks steps...
         <task>
           <flowRun id="flow-run-id"
            priority="priority"
            consecutiveFailedCount="consecutive-failed-count"
            type="task-type">
            <flow id = flow-id"
             name="flow-name"
           </flowRun>
         </task>
       </linkedTaskSteps>
       ...additional linked tasks steps...
     </linkedTasksSteps>
     ... additional linked tasks ...
    </linkedTasks>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
400 400154 Generic query linked task error Could not get a list of linked tasks for some reason other than the ones specified below.
403 403155 Linked tasks disabled Linked tasks has been disabled for your site or server.
403 403004 Operation unauthorized You do not have permissions to see the list of linked tasks
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a6b7c6d-5e4f-4a2b-1c0d-9e8f7s6b5c4d/tasks/linked" -X GET -H "X-Tableau-Auth:12ab34cd56ef98ab90ce12ef34ab52cd"

Example response:

<tsResponse version-and-namespace-settings>
   <linkedTasks>
     <linkedTasks id="18d267af-4c40-4dz6-8234-6ag8c3dea67f"
      numSteps="2">
       <schedule id="3ee04ae9-4dbf-45b5-a6d6-18fa19f2jb8a"
        name="Run Flow - Every Sunday - 4:00PM"
        state="Active" priority="50"
        createdAt="2021-01-21T19:15:53Z"
        updatedAt="2022-02-27T16:00:59Z"
        type="Flow" frequency="Weekly"
        nextRunAt="2022-03-06T16:00:00Z"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="738fffc7-6a21-4af5-b49e-2c47f51480d2"
          stepNumber="1"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="690c3b2c-a309-4683-9e6e-166517dc8598"
              priority="50"
              consecutiveFailedCount="0"
              type="RunFlowTask">
               <flow id="56809d67-aca9-4f08-9fdc-4b6473c3ff02" name="r-3"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
         <linkedTaskSteps id="b9668563-e2c3-414d-b461-084a3d951cc5"
          stepNumber="2"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="2bb8e959-f5da-4691-903e-be73eed08a4c"
              priority="50"
              consecutiveFailedCount="0"
              type="RunFlowTask">
              <flow id="19ed906f-4752-4f89-a3ca-19b406efd596"
               name="flights"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
     </linkedTasks>
     <linkedTasks id="abf4c0d2-0b5a-4dd1-9667-70b22bd73fe9"
      numSteps="2">
       <schedule id="92811890-d91c-456a-83b6-94db7d7041be"
        name="Run Flow - Weekday 2:00AM"
        state="Active" priority="50"
        createdAt="2021-01-21T19:15:52Z"
        updatedAt="2022-03-01T02:00:59Z"
        type="Flow"
        frequency="Weekly"
        nextRunAt="2022-03-02T02:00:00Z"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="3061807b-e0f4-48ab-bbdd-7e032ff25858"
          stepNumber="1"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="c914cf4c-23e4-437c-b25b-11735bf586nf"
              priority="50"
              consecutiveFailedCount="0"
              type="RunFlowTask">
               <flow id="5a421e12-6dc4-42b5-9723-e8e667c728f3"
                name="Test3"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
         <linkedTaskSteps id="ed515d51-7715-4d3f-zf16-46e6f90cd5cf"
          stepNumber="2"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="fb945078-85c3-4f78-8214-f6fb3374d67e"
              priority="50"
              consecutiveFailedCount="2"
              type="RunFlowTask">
               <flow id="1ea76ax2-4ef3-49d3-9892-f1840b6e55da"
                name="Superstore Flow"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
       </linkedTaskSteps>
     </linkedTasks>
   </linkedTasks>
</tsResponse>

Get metric

Gets the details of the specified metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user get a metric's details as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

GET /api/api-version/sites/site-id/metrics/metric-luid;

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The unique ID of the site that contains the metric.>
metric-luid The unique ID of the metric.  

Request Body

None

Permissions

This method can be called by any user, but those without administrator permissions will only be able to view responses for metrics they own.

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:content:read

Response Code

200

Response Body

                <tsResponse>
  <metric id="metric-id"
	name="metric-name"
	description="metric-description"
	webpageUrl="metric-content-url"
	createdAt="datetime-created"
	updatedAt="datetime-updated"
	suspended="suspended-flag">
  	  <project id="project-id"
	    name="project-name"/>
	  <owner id="metric-owner-id"/>
	  <tags>
	    <tag label="tag"/>
	    <!-- ... additional tags ... -->
	  </tags>
	  <underlyingView id="view-id"/>
  </metric>
</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 Permissions issue The user does not have permissions to read the specified metric.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Metric not found The metric ID in the URI doesn't correspond to an existing metric.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics/6561daa3-20e8-407f-ba09-709b178c0b4a" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Body

                    <tsResponse>
  <metric id="6561daa3-20e8-407f-ba09-709b178c0b4a"
    name="my metric name"
    description="Description of my metric."
    webpageUrl="https://MY-SERVER/#/site/site-name/metrics/site-num"
    createdAt="2020-01-02T01:02:03Zd"
    updatedAt="2020-01-02T01:02:03Z"
    suspended="true">
      <project id="32e79edb-6cfd-47dc-ad79-e8ec2fbb1d33"
        name="my project name"/>
      <owner id="32e79edb-6cfd-47dc-ad79-e8ec2fbb1d33"/>
      <tags/>
      <underlyingView id="29dae0cd-1862-4a20-a638-e2c2dfa682d4"/>
  </metric>
</tsResponse>
        

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.

URI

GET /api/api-version/sites/site-luid/metrics/metric-luid/data

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the data source to get revisions for.
metric-luid The LUID of the metric whose data should be returned.

Request Body

None

Permissions

Tableau administrators, and non-administrator and users with Read capability for a metric, will be able to get its data.

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:metrics:download

Response Code

200

Response Body

your_timestamp_column_name,your_measure_column_nametimestamp_1,measure_1timestamp_2,measure_1

Version

Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 40000 Bad request The LUID of the site or metric was malformed.
401 40100 Not authorized The authentication token provided in the request header was invalid or has expired.
403 403054 Not authorized A non-administrator user attempted to get metric data, but does not have sufficient permissions.
404 404000 Site not found The site LUIID in the URI doesn't correspond to an existing site.
404 Metric not found The metric LUID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.
429 405000 Too many requests The concurrent request limit for the site was exceeded. Retry after a pause.

For more information, see Handling Errors.

Example

Request command line:

curl "http://MY-SERVER/api/3.16/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/metrics/2474164d-8d37-4a4c-abc7-c2070fd25fd5/data" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response:

Timestamp,Measure
2021-12-31:11:59:57-0800,3
2021-12-31:11:59:58-0800,2
2021-12-31:11:59:59-0800,1

Get metric definition

Gets a metric definition and optionally metrics it contains.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions_metrics:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Get Mobile Security Settings for Server

Gets the mobile security settings for the server.

Version: Available in API 3.19 (Tableau Cloud December 2022 / Server 2023.1) and later.. Version Overview

License: No additional license required.

Permissions: Only Tableau server and site administrators can get mobile security settings for the server.  Permissions Overview

JWT Access Scope: Not available.     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

GET /api/api-version/settings/mobilesecuritysettings

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

cURL Request Example

curl -L -X GET "https://qa-server.tsi.lan/api/3.18/settings/mobilesecuritysettings" -H "Accept: application/json" -H "X-Tableau-Auth: ejET2rVmS2e81XiZ9G4lzQ|Iz71DR2lu3r0zHpcOAH2OoRQZlPfxACC|a905dbfd-6550-4546-908b-3e055fcc026d" --data-raw ""

Response Code

200

Response Body

Copy
<tsResponse>
    <mobileSecuritySettingsList>
        <mobileSecuritySettings name="mobile.security.jailbroken_device" enabled="true">
            <iosConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </iosConfig>
            <androidConfig severity="critical" enabled="false">
                <valueList>false</valueList>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name="mobile.security.malware_detection" enabled="true">
            <iosConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </iosConfig>
            <androidConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name ="mobile.security.max_offline" enabled="true">
            <iosConfig enabled="true" severity="critical">
                <valueList>14</valuelist>
            </iosConfig>
            <androidConfig enabled="true" severity="critical">
                <valueList>14</valuelist>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name="mobile.security.screenshot" enabled="false">
            <androidConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </androidConfig>
        </mobileSecuritySettings>
    </mobileSecuritySettingsList>
</tsResponse>

Copy
{
    "mobileSecuritySettingsList": {
        "mobileSecuritySettings": [
            {
                "name": "mobile.security.jailbroken_device",
                "enabled": true,
                "iosConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                },
                "androidConfig": {
                    "valueList": [
                        "false"
                    ],
                    "enabled": true,
                    "severity": "critical"
                }
            },
            {
                "name": "mobile.security.malware_detection",
                "enabled": true,
                "iosConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                },
                "androidConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                }
            },
            {
                "name": "mobile.security.max_offline",
                "enabled": true
                "iosConfig": {
                    "valueList": [
                        "14"
                    ],
                    "enabled": true,
                    "severity": "critical"
                },
                "androidConfig": {
                    "valueList": [
                        "14"
                    ],
                    "enabled": true,
                    "severity": "critical"
                },
            },
            {
                "name": "mobile.security.screenshot",
                "enabled": false,
                "androidConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                }
            }
        ]
    }
}

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.

Version: Available in API 3.18 (Tableau Cloud December 2022) and later. Not available for Tableau Server. Version Overview

License: No additional license required.

Permissions: Only Tableauserver and site administrators can get mobile security settings.  Permissions Overview

JWT Access Scope: Not available.     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

GET /api/api-version/sites/site-luid/settings/mobilesecuritysettings

URI Parameter Values

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

cURL Request Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy
<tsResponse>
    <mobileSecuritySettingsList>
        <mobileSecuritySettings name="mobile.security.jailbroken_device" enabled="true">
            <iosConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </iosConfig>
            <androidConfig severity="critical" enabled="false">
                <valueList>false</valueList>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name="mobile.security.malware_detection" enabled="true">
            <iosConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </iosConfig>
            <androidConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name ="mobile.security.max_offline" enabled="true">
            <iosConfig enabled="true" severity="critical">
                <valueList>14</valuelist>
            </iosConfig>
            <androidConfig enabled="true" severity="critical">
                <valueList>14</valuelist>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name="mobile.security.screenshot" enabled="false">
            <androidConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </androidConfig>
        </mobileSecuritySettings>
    </mobileSecuritySettingsList>
</tsResponse>

Copy
{
    "mobileSecuritySettingsList": {
        "mobileSecuritySettings": [
            {
                "name": "mobile.security.jailbroken_device",
                "enabled": true,
                "iosConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                },
                "androidConfig": {
                    "valueList": [
                        "false"
                    ],
                    "enabled": true,
                    "severity": "critical"
                }
            },
            {
                "name": "mobile.security.malware_detection",
                "enabled": true,
                "iosConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                },
                "androidConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                }
            },
            {
                "name": "mobile.security.max_offline",
                "enabled": true
                "iosConfig": {
                    "valueList": [
                        "14"
                    ],
                    "enabled": true,
                    "severity": "critical"
                },
                "androidConfig": {
                    "valueList": [
                        "14"
                    ],
                    "enabled": true,
                    "severity": "critical"
                },
            },
            {
                "name": "mobile.security.screenshot",
                "enabled": false,
                "androidConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                }
            }
        ]
    }
}

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.

Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Cloud site admins only.

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

GET /api/api-version/sites/site-luid/site-oidc-configuration

URI Parameter Values

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

Request Body

None

cURL Request Example

curl "https://us-west-2a.online.tableau.com/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy
<tsResponse>
  <siteOIDCConfiguration
    enabled="true" 
    testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
    allowEmbeddedAuthentication="false"
    clientId="0oa111usf1gpUkVUt0h1" 
    clientSecret="&lt;omit>"
    authorizationEndpoint="https://myidp.com/oauth2/v1/authorize"
    tokenEndpoint="https://myidp.com/oauth2/v1/token"
    userinfoEndpoint="https://myidp.com/oauth2/v1/userinfo"
    jwksUri="https://myidp.com/oauth2/v1/keys"
    endSessionEndpoint="https://myidp.com/oauth2/v1/logout"
    customScope="openid, email, profile"
    prompt="login,consent"
    clientAuthentication="client_secret_basic"
    essentialAcrValues="phr"
    emailMapping="email"
    firstNameMapping="given_name"
    lastNameMapping="family_name"
    fullNameMapping="name"
    useFullName="false" />
</tsResponse>
Copy
{tsResponse:
}

Notes:

  • The response hides the client secret and replaces it with &lt;omit>.

  • You can use the testloginURL to validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.

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.

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

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can create a metric in a definition as long as Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:create
Access Scopes Overview: Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

GET /api/api-version/sites/site-id/content/recent

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the views and workbooks.

Request Body

None

Permissions

Users who are not server administrators or site administrators, the method returns only the views and workbooks that the user owns or has Read permissions for (either explicitly or implicitly).

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:content:read

Response Code

200

Response Body

<tsResponse >
<recents>
  <recent>
	<view
	  id="view-id"
	  name="view-name"
	  contentUrl="view-content-url"
	  createdAt="created-at-time"
	  updatedAt="updated-at-time"
	  viewUrlName="view-url-name">
		<workbook id=""workbook-of-view" "/>
		<owner id="owner-id" />
		<project id="project-id" />
		<tags/>
	</view>
  </recent>
  <recent>
    <workbook
 	  id="workbook-id"
	  name="workbook-name"
	  description="workbook-description"
	  contentUrl="workbook-content-url"
	  webpageUrl="workbook-webpage-url"
	  showTabs="show-tags-flag"
	  size="size-in-mb"
	  createdAt="created-at-time"
	  updatedAt="updated-at-time"
	  encryptExtracts="encrypt-extracts-flag"
	  defaultViewId="default-view-id" >
        <project id="project-id"/>
        <owner id="ownwer-id"
		name="project-name" />
        <tags/>
	</workbook>
  </recent>
  <!--  more recently viewed views and workbooks  -->
</tsResponse>
        

The value of view-url-name is the name of the view in its URL. For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1 in your browser address bar, then the the view-url-name would be VIEW_1. Modifying the name (display name) of a view will not impact the view-url-name (path element of the view's URL).

Version

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

Errors

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.

Example

curl -X GET "https://qa-windows/api/3.5/sites/cd24a433-b66c-46cd-a4af-6cde73db9ee1/content/recent" -H "X-Tableau-Auth: pI8NzKb-S5-Jqiatds8jrQ|GKUYlgHjuHSPSVfS38plFpH31UkHGtNl"

Example response:

<tsResponse >
  <recents>
    <recent>
      <view
	    id="8a922e79-3041-4916-942e-1a18162ef8a9"
	    name="MySQL PostgresSQL"
	    contentUrl="my_site1"
	    createdAt="2019-01-28T20:33:35Z"
	    updatedAt="2019-01-28T20:44:05Z"
		viewUrlName="MySQL_PostgresSQL">
		  <workbook id="1eb0d238-c9d2-49ec-a0ce-762ddc6f9827"/>
		  <owner id="2dbbee8a-202c-4a74-82d6-8e3544f55ceb"/>
		  <project id="50b87b02-74b6-11e8-a4b0-df15be81c0c4"/>
		  <tags/>
      </view>
    </recent>
    <recent>
	  <workbook
	    id="5589cf2b-8601-43f9-9151-0f6c2db760cc"
	    name="Connections-AmazonAurora (1)"
	    description=""
	    contentUrl="my_site2"
	    webpageUrl="https://my_server/#/workbooks/222"
	    showTabs="false"
	    size="7"
	    createdAt="2019-02-13T20:52:37Z"
	    updatedAt="2019-02-13T20:52:38Z"
	    encryptExtracts="false"
	    defaultViewId="d4bed763-1cb1-4924-b455-6a6c298d860d">
	      <project id="add6c395-11b8-4d57-a66b-733220a33aa0" name="project2"/>
	      <owner id="3f90c20d-069f-46dd-b5a0-6e7092140790" name="my_name"/>
	      <tags/>
	  </workbook>
    </recent>
    <!--  more recently viewed views and workbooks  --%gt;
  </recent>
</tsResponse>
            

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.

URI

GET /api/api-version/sites/site-id/recommendations/?type=view

Path Parameters

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

Request Body

None

Permissions

This method can be called by any site user or administrator.

Response Code

200

Response Body

<tsRequest>
 <recommendations>
   <recommendation score="recommendation_score">
     <view id="view_id" />
     <similarUsersExplanation>
       <users>
         <user id="user_id_1" />
         <user id="user_id_2" />
       </users>
     </similarUsersExplanation>
   </recommendation>
   <recommendation score="recommendation_score">
     <view id="view_id" />
     <popularExplanation />
   </recommendation>
 </recommendations>
</tsRequest>
        

Version

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

Errors

HTTP status error Code Condition Details
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.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/recommendations?type=view" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsRequest>
 <recommendations>
   <recommendation score="94.100233876">
     <view id="0f0d33ac-027d-42a7-94bf-4f0b13e07652" />
     <similarUsersExplanation>
       <users>
         <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
         <user id="f33n9d9c-8b8a-8f8e-7d7c-7b7a6f6d0p12" />
       </users>
     </similarUsersExplanation>
   </recommendation>
   <recommendation score="94.038491833">
     <view id="w33533ac-027d-42a7-94bf-4f0b13e0so32" />
     <popularExplanation />
   </recommendation>
 </recommendations>
</tsRequest>
          

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.

URI

GET /api/api-version/schedules/schedule-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
schedule-id The ID of the specific schedule.
Note: You can get the schedule id from running the List Server Schedules method. For more information, see Jobs, Tasks, and Schedules Methods

Request Body

None

Permissions

On Tableau Server, any user able to schedule extract refreshes and any site or server administrator can get schedules.

Response Code

200

Response Body

<tsResponse >
   <schedule id = "schedule id"
	name = "schedule-name"
	state="Active-or-Suspended"
	priority= "priority"
	createdAt="datetime-created"
	updatedAt="datetime-last-updated"
	type="schedule-type"
	frequency="extractrefresh-or-flow-or-subscription"
	nextRunAt="datetime-nextrun"
	executionOrder="Parallel-or-Serial" >
	   <frequencyDetails start="time"
		<intervals>
		  <interval schedule-frequency/>
		</intervals>
	   </frequencyDetails>
   </schedule>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
404 404027 Schedule not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/schedules/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
   <schedule id="60456a5c-0293-4fed-9391-6d94a5f42b48"
	name="My Schedule"
	state="Active"
	priority="50"
	createdAt="2020-02-24T22:18:20Z"
	updatedAt="2020-02-24T22:18:20Z"
	type="Extract"
	frequency="Monthly"
	nextRunAt="2020-02-25T19:20:00Z"
	executionOrder="Parallel">
	   <frequencyDetails start="11:20:00">
		<intervals>
		   <interval monthDay="Customized Monthly"/>
		</intervals>
	   </frequencyDetails>
   </schedule>
</tsResponse>
        

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.

URI

GET /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the subscriptions.
subscription-id The ID of the subscription to get information for.

JWT Access Scope

tableau:tasks:read (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

None

Permissions

Tableau Server administrators and all site administrators can get subscription information for users of projects within the scope of their administrative permissions. Other users can get subscription information only for their own subscriptions.

Curl Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Tableau Server and Tableau Cloud return different payloads in response to this request.

For Tableau Server: Server schedule is returned.

Response Code

200

Response Body

Tableau Server and Tableau Cloud return different payloads in response to this request.

Tableau Server Request

For Tableau Server, a subscription task with a server schedule is returned.

Copy
<tsResponse>
  <subscription id="subscription-id" 
    subject="subscription-subject"
    attachImage="attach-image-flag" attachPdf="attach-pdf-flag"
    suspended="suspended-flag"
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option">
      <content id="content-id"
           type="content-type"
         sendIfViewEmpty="send-view-if-empty-flag"/>
      <schedule id="schedule-id" name="schedule-name" />
      <user id="user-id" name="user-name" />
   </subscription>
 </tsResponse>
Copy
{
  "subscription": {
    "id": "subscription-id",
    "subject": "subscription-subject",
    "attachImage": "attach-image-flag",
    "attachPdf": "attach-pdf-flag",
    "suspended": "suspended-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "content": {
      "id": "content-id",
      "type": "content-type",
      "sendIfViewEmpty": "send-view-if-empty-flag"
    },
    "schedule": {
      "id": "schedule-id",
      "name": "schedule-name"
    },
    "user": {
      "id": "user-id",
      "name": "user-name"
    }
  }
}

Tableau Cloud Request

For Tableau Cloud, a subscription task with frequency is returned.

Copy
 <tsResponse>
  <subscription id="92cb4f51-7a15-41d4-bce4-a0fcce5fa985" subject="Subscription - postman" message="Test out postman Subscriptions" attachImage="true" attachPdf="false" suspended="false">
    <content id="be016ba6-d0a8-44ae-a057-b6df6931ccaa" type="Workbook" sendIfViewEmpty="true"/>
    <schedule frequency="Weekly" nextRunAt="2023-06-08T17:05:00-0700">
      <frequencyDetails start="17:05:00">
        <intervals>
          <interval weekDay="Thursday"/>
        </intervals>
      </frequencyDetails>
    </schedule>
    <user id="14064b01-7d58-4978-bdeb-a5f8d7694863" name="mysite.com"/>
  </subscription>
</tsResponse>
Copy
{
  "subscription": {
    "id": "92cb4f51-7a15-41d4-bce4-a0fcce5fa985",
    "subject": "Subscription - postman",
    "message": "Test out postman Subscriptions",
    "attachImage": "true",
    "attachPdf": "false",
    "suspended": "false",
    "content": {
      "id": "be016ba6-d0a8-44ae-a057-b6df6931ccaa",
      "type": "Workbook",
      "sendIfViewEmpty": "true"
    },
    "schedule": {
      "frequency": "Weekly",
      "nextRunAt": "2023-06-08T17:05:00-0700",
      "frequencyDetails": {
        "start": "17:05:00",
        "intervals": {
          "interval": [
            { "weekDay": "Thursday" }
          ]
        }
      }
    },
    "user": {
      "id": "14064b01-7d58-4978-bdeb-a5f8d7694863",
      "name": "gmysite.com"
    }
  }
}

Version

For Tableau Server: API 2.3 and later. For Tableau Cloud: API 3.20 (June 2023) and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403058 Unauthorized The user attempted to get information for a subscription that they don't have permission to access.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404025 Subscription not found The specified subscription doesn't correspond to an existing subscription.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get subscription

Gets a specified subscription to a metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of a subscription. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.17 ( Tableau Cloud December 2022) and later. Not available for Tableau Server. Version Overview

Permissions: Tableau administrators can get statistics for all content Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

GET /api/api-version/sites/site-id/settings/notifications

GET /api/api-version/sites/site-id/settings/notifications?filter=filter-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the users.
filter-expression

(Optional) An expression that lets you specify a subset of notification preferences to return. You can filter on the following fields and corresponding options:

  • channel: email, in_app, and slack
  • notificationType: comments, webhooks, prepflow, share, dataalerts,and extractrefresh

You can include multiple filter expressions. For more information, see Filtering and Sorting.

Request Body

None

Permissions

This method can only be called by a Server Administrator, a Site Administrator Creator, or a Site Administrator Explorer.

Response Code

200

Response Body

<tsResponse>
  <userNotificationsPreferences>
    <userNotificationsPreference channel="channel"
      notificationType="notification-type"
      enabled="true-or-false"
      disabledByOverride="true-or-false"/>
    <userNotificationsPreference channel="channel"
      notificationType="notification-type"
      enabled="true-or-false"
      disabledByOverride="true-or-false"/>
   <!-- ... additional notification preferences ... -->
  </userNotificationsPreferences>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 409109 Invalid request Invalid notification type.
400 409100 Invalid request Invalid channel.
403 403004 Invalid permissions Invalid permission to update site user notification settings.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method The request type was not GET.

For more information, see Handling Errors.

Example

Example response:

<tsResponse>
  <userNotificationsPreferences>
    <userNotificationsPreference channel="email"
      notificationType="comments"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="email"
      notificationType="webhooks"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="email"
      notificationType="prepflow" enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="email"
      notificationType="share"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="email"
      notificationType="dataalerts"
      enabled="true"
      disabledByOverride="true"/>
    <userNotificationsPreference channel="email"
      notificationType="extractrefresh"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="in_app"
      notificationType="comments"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="in_app"
      notificationType="prepflow"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="in_app"
      notificationType="share"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="in_app"
      notificationType="extractrefresh"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="slack"
      notificationType="comments"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="slack"
      notificationType="prepflow"
      enabled="true"
      disabledByOverride="false"/>
    <userNotificationsPreference channel="slack"
      notificationType="share"
      enabled="true"
      disabledByOverride="false"/>
     <userNotificationsPreference channel="slack"
      notificationType="dataalerts"
      enabled="true"
      disabledByOverride="false"/>
  </userNotificationsPreferences>
</tsResponse>
			

Get Users in Group

Gets a list of users in the specified group.

URI

GET /api/api-version/sites/site-id/groups/group-id/users

GET /api/api-version/sites/site-id/groups/group-id/users?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to get the users for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can only be called by server administrators and site 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:groups:read

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
      totalAvailable="total-available" />
	    <users>
	      <user id="user-id"
	    name="user-name"
	    siteRole="site-role"
	    lastLogin="last-login-date-time"
	    externalAuthUserId="authentication-id-from-external-provider"
		language="language-code"
		locale="locale-code" />
	    ... additional user information ...
   </users>
</tsResponse>
        

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

The externalAuthUserId value is returned for Tableau Cloud; it represents ID stored in Tableau's single sign-on (SSO) system. For other server configurations, this field contains null, and the value of lastLogin is an empty string.

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
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.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <users>
    <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="Adam" siteRole="Explorer" />
    <user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Bob" siteRole="ExplorerCanPublish"
	language="en-GB" locale="GB" />
  </users>
</tsResponse>

Get Users on Site

Returns the users associated with the specified site.

URI

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

GET /api/api-version/sites/site-id/users?filter=filter-expression

GET /api/api-version/sites/site-id/users?sort=sort-expression

GET /api/api-version/sites/site-id/users?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/users?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the users.
filter-expression (Optional) An expression that lets you specify a subset of users to return. You can filter on predefined fields such as name and lastLogin. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the views or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand &.

Request Body

None

Permissions

This method can only be called by server administrators and site 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:users:read

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="page-number"
     pageSize="page-size"
     totalAvailable="total-available" />
   <users>
    <user email="email"
      id="user-id"
      fullName="full-name"
      name="user-name"
      siteRole="site-role"
      lastLogin="date-time"
      externalAuthUserId="authentication-id-from-external-provider"
      authSetting="auth-setting"
      language="language-code"
      locale="locale-code">
        <domain name="domain-name" />
    </user>
    <user email="email"
      id="user-id"
      fullName="full-name"
      name="user-name"
      siteRole="site-role"
      lastLogin="date-time"
      externalAuthUserId="authentication-id-from-external-provider"
      authSetting="auth-setting"
      language="language-code"
      locale="locale-code">
        <domain name="domain-name"/>
    </user>

  </users>
</tsResponse>

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

The externalAuthUserId value is returned for Tableau Cloud; it represents ID stored in Tableau's single sign-on (SSO) system. For other server configurations, this field contains null, and the value of lastLogin is an empty string.

Note: The authSetting attribute is only returned if you are using Tableau Server with site-specific SAML enabled, or Tableau Cloud with either SAML or OpenID enabled.

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
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.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="161"/>
  <users>
    <user email="alex@example.com"
      id="9f9e9d9c8-b8a8-f8e7-d7c7-b7a6f6d6e6d"
      fullName="Alex Smith" name="Alex"
      siteRole="Viewer" language="en-GB" locale="GB">
        <domain name="tsi.lan" />
    </user>
    <user email="jannaj@example.org"
      id="12ab34cd5-6ef7-8ab9-0cd1-2ef34ab56cd"
      fullName="Janna Johnson" name="Janna"
      siteRole="Unlicensed"  language="en-GB" locale="GB" >
        <domain name="tsi.lan" />
    </user>
    <user email="fred.zuzuki@example.net"
      id="9a8a7b6b5-c4c3-d2d1-e0e9-a8a7b6b5b4b"
      fullName="Fred Suzuki" name="Fred"
      siteRole="ExplorerCanPublish" language="en-GB" locale="GB">
        <domain name="tsi.lan" />
    </user>

    ... more users ...
  </users>
</tsResponse>
        

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=siteRole:eq:Unlicensed&sort=name:asc" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

This example includes a filter to return the users whose site role is Unlicensed and specifies that the results should be sorted by the name value.

Get View

Gets the details of a specific view.

URI

GET /api/api-version/sites/site-id/views/view-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
view-id The ID of the view whose details are requested.

Request Body

None

Permissions

For users who are not server administrators or site administrators, the method returns only the views that the user owns or has Read permissions for (either explicitly or implicitly).

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:content:read

Response Code

200

Response Body

<tsResponse>
	<view id="view-id"
	  name="view-name"
	  contentUrl="path-to-view"
	  createdAt="created-date"
	  updatedAt="updated-date"
	  viewUrlName="view-url-name">
	    <workbook id="workbook-id"/>
		<owner id="owner-id"/>
		<project id="project-id"/>
		<tags/>
	</view>
</tsResponse>
        

The value of view-url-name is the name of the view in its URL. For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1 in your browser address bar, then the view-url-name would be VIEW_1. Modifying the name (display name) of a view will not impact the view-url-name (path element of the view's URL).

Version

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

Errors

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Resource not found The view ID in the URI doesn't correspond to an existing view.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6ds" -X GET -H "X-Tableau-Auth:RDEj_zqgQtGGcCiD3BXnSA|abXWv8thv5ocrXLNU7axCicQu3UdfgeX"

Example response:

<tsResponse>
  <view id="57dc5674-23aa-4a83-b3d4-8653cf3c735f"
	name="Sheet 1"
	contentUrl="workbook/sheets/Sheet1"
	createdAt="2019-05-07T17:59:42Z"
	updatedAt="2019-05-07T17:59:48Z"
	viewUrlName="view-name">
	  <workbook id="0cee459c-9640-4d10-a33d-c6ee98b72beb"/>
	  <owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
	  <project id="0ef6e0e6-b775-4d0c-8a1c-1b82e6343526"/>
	  <tags/>
  </view>
</tsResponse>
          

Get View by Path

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

URI

GET /api/api-version/sites/site-id/views?filter=viewUrlName:eq:view-name

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
view-name The name of the view as it appears in the URL to the view. For https://MY_SERVER/#/MY_SITE/views/workbook-name/Sheet1?:iid=1, the name would be Sheet1.

Request Body

None

Permissions

For users who are not server administrators or site administrators, the method returns only the views that the user owns or has Read permissions for (either explicitly or implicitly).

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:content:read

Response Code

200

Response Body

<tsResponse>
	<view id="view-id"
	  name="view-name"
	  contentUrl="path-to-view"
	  createdAt="created-date"
	  updatedAt="updated-date"
	  viewUrlName="view-name"  >
		<workbook id="workbook-id"
		<owner id="ownwer-ide"
		<project id="product-id"
		<tags/>
	</view>
	<!--      . . .more views with the same name. . .      -->
</tsResponse>
        

The value of view-url-name is the name of the view in its URL. For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1 in your browser address bar, then the view-url-name would be VIEW_1. Modifying the name (display name) of a view will not impact the view-url-name (path element of the view's URL).

Version

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

Errors

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Resource not found The view ID in the URI doesn't correspond to an existing view.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views?filter=viewUrlName:eq:Sheet1" -X GET -H "X-Tableau-Auth:RDEj_zqgQtGGcCiD3BXnSA|abXWv8thv5ocrXLNU7axCicQu3UdfgeX"

Example response:

<tsResponse>
  <view id="57dc5674-23aa-4a83-b3d4-8653cf3c735f"
	name="Sheet 1"
	contentUrl="workbook/sheets/Sheet1"
	createdAt="2019-05-07T17:59:42Z"
	updatedAt="2019-05-07T17:59:48Z">
	viewUrlName="Sheet1" >
 	  <workbook id="0cee459c-9640-4d10-a33d-c6ee98b72beb"/>
	  <owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
	  <project id="0ef6e0e6-b775-4d0c-8a1c-1b82e6343526"/>
	  <tags/>
  </view>
</tsResponse>
          

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.

Version: Available in API 2.0 and later. Data acceleration and data freshness policy setting update are added in API 3.22 (Tableau Cloud February 2024 / Server 2024.2). Version Overview

License: No additional license required.

Permissions: You can get workbok details if you are a user with implicit or explicit Read permissions for the workbook, or are a Tableau Administrator.  Permissions Overview

JWT Access Scope: tableau:content:read     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id

GET /api/api-version/sites/site-id/workbooks/content-url?key=contentUrl

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
content-url

The permanent name of the site to sign in to. The content URL appears in the URL path of Tableau content in your browser address bar after the Tableau Server URL.

mySite is the content URL in the following example:

http://<server or cloud URL>/#/site/mySite/explore

Request Body

None

Response Code

200

cURL Request Example

curl -L -X GET "http://qa-near/api/3.17/sites/a946d998-2ead-4894-bb50-1054a91dcab3/workbooks/simple-highlight?key=contentUrl" -H "X-Tableau-Auth:HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3"

Response Body

Copy
<tsResponse>
  <workbook id="0828bd63-dea5-454f-8f54-30f9a92760ff" 
    name="WB_Election_live" 
    description="" contentUrl="WB_Election_live" 
    webpageUrl="http://MyServer/#/workbooks/4" 
    showTabs="false" size="1" createdAt="2024-01-25T23:42:57Z" 
    updatedAt="2024-01-25T23:42:57Z" 
    encryptExtracts="false" 
    defaultViewId="10f6d099-fe90-41a1-a77b-1512b818d23c">
      <project id="7eb51f54-bbca-11ee-9262-638afb01250c" name="Default"/>
      <location id="7eb51f54-bbca-11ee-9262-638afb01250c" type="Project" name="Default"/>
      <owner id="09d032b6-d17d-444c-afbe-d71c22f7ee31" name="test"/>
      <tags/>
      <views>
        <view id="fcc36499-fd2d-42af-8e2c-29d1c7893edd" 
            name="Votes" 
            contentUrl="WB_Election_live/sheets/Votes" 
            createdAt="2024-01-25T23:42:57Z" 
            updatedAt="2024-01-25T23:42:57Z" 
            viewUrlName="Votes">
            <tags/>
            <dataAccelerationConfig accelerationEnabled="true" 
                accelerationStatus="Pending"/>
          </view>
        </views>
        <dataFreshnessPolicy option="FreshAt">
            <freshAtSchedule time="08:15:00" frequency="Week" timezone="America/Los_Angeles">
                <intervals>
                    <interval weekDay="MONDAY"/>
                </intervals>
            </freshAtSchedule>
        </dataFreshnessPolicy>
  </workbook>
</tsResponse>

Copy
{
  "workbook": {
    "id": "0828bd63-dea5-454f-8f54-30f9a92760ff",
    "name": "WB_Election_live",
    "description": "",
    "contentUrl": "WB_Election_live",
    "webpageUrl": "http://MyServer/#/workbooks/4",
    "showTabs": "false",
    "size": "1",
    "createdAt": "2024-01-25T23:42:57Z",
    "updatedAt": "2024-01-25T23:42:57Z",
    "encryptExtracts": "false",
    "defaultViewId": "10f6d099-fe90-41a1-a77b-1512b818d23c",
    "project": {
      "id": "7eb51f54-bbca-11ee-9262-638afb01250c",
      "name": "Default"
    },
    "location": {
      "id": "7eb51f54-bbca-11ee-9262-638afb01250c",
      "type": "Project",
      "name": "Default"
    },
    "owner": {
      "id": "09d032b6-d17d-444c-afbe-d71c22f7ee31",
      "name": "test"
    },
    "tags": [],
    "views": {
      "view": {
        "id": "fcc36499-fd2d-42af-8e2c-29d1c7893edd",
        "name": "Votes",
        "contentUrl": "WB_Election_live/sheets/Votes",
        "createdAt": "2024-01-25T23:42:57Z",
        "updatedAt": "2024-01-25T23:42:57Z",
        "viewUrlName": "Votes",
        "tags": [],
        "dataAccelerationConfig": {
          "accelerationEnabled": "true",
          "accelerationStatus": "Pending"
        }
      }
    },
    "dataFreshnessPolicy": {
      "option": "FreshAt",
      "freshAtSchedule": {
        "time": "08:15:00",
        "frequency": "Week",
        "timezone": "America/Los_Angeles",
        "intervals": {
          "interval": {
            "weekDay": "MONDAY"
          }
        }
      }
    }
  }
}

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Errors

HTTP status error Code Condition Details
403 403018 Read forbidden A non-administrator user attempted to query the workbook, but the caller doesn't have Read permission.
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 LUID or contentUrl in the URI doesn't correspond to an existing workbook, or the querystring ?key=contentUrl is not capitalized correctly.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

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

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/downGradeInfo?productVersion=downgrade-target-version

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook that downgrade info is being shown for.
workbook-id The ID of the workbook being downgraded.
downgrade-target-version The Tableau release version number the workbook is being downgraded to.

Request Body

None

Permissions

Tableau Server users who are site administrators can get downgrade information for workbooks on the site that they are administrators for. Users who are not server administrators or site administrators can get downgrade information for workbooks they have permissions to.

Response Code

200

Response Body

<tsResponse>
  <downgradeInfo>
	<downgradedFeature name="feature-downgraded-name" severity="level-of-severity"/>
	<!-- more downgraded feature info -->
  </downgradeInfo>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
400 400114 Unknown downgrade error The workbook cannot be exported to a downgraded version due to an unknown error.
400 400115 Invalid downgrade version The downgrade version specified is not a valid Tableau version number.
400 400116 Downgrade version not supported The downgrade version specified refers to a Tableau version that is not supported.
403 40310 Access to downgrade info denied The caller does not have permissions required to access download info for this workbook.
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.

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.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook to get revisions for.
workbook-id The ID of the workbook to get revisions for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get workbook revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified workbook.
  • Save (write) permissions for the project that contains the workbook.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
       totalAvailable="total-available" />
  <revisions>
    <revision createdAt="date" revisionNumber="1" isDeleted="false">
      <user id="user-id" name="user-name"/>
    </revision>
    <revision createdAt="date" revisionNumber="2" isDeleted="false">
    </revision>
    <revision createdAt="date" revisionNumber="3" isCurrent="true">
        <user id="user-id" name="user-name"/>
    </revision>
  </revisions>
</tsResponse>
        

If the revision element includes the attribute isDeleted="true", the workbook has been deleted and cannot be downloaded using the Download Workbook Revision method.

If a user has been deleted from the site, no <user> element is included in the <revision> element.

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403056 A non-administrator user attempted to get workbook 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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

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.

URI

PUT /api/api-version/sites/site-id/recommendations/dismissals

Path Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.

Request Body

<tsRequest>
	<recommendationDismissal>
		<view id="view_luid" />
	</recommendationDismissal>
</tsRequest>
          

Request Parameters

view-luid The LUID of the view to be added to the list of views hidden from recommendation for a user.

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

None

Version

Version 1.0 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.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The content ID in the URI doesn't correspond to an existing content of the requested type.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dismissals -X PUT \
-H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" \
-d "@hide-view.xml"
          

Content of hide-view.xml

<tsRequest>
  <recommendationDismissal>
    <view id="57dc5674-23aa-4a83-b3d4-8653cf3c735f" />
  </recommendationDismissal>
</tsRequest>
          

Example response:

No response body. Response code is 204.

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.


Import an existing ask data lens on a server to a site, and optionally transform the metadata of the lens in the process.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) Version Overview

Permissions: This method can only be called by server administrators Permissions Overview

License: No additional license required.

Access Scope: `tableau:lenses:create` Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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 the 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.22. 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 multipart request is required. For more information on multipart 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" />
  <!--    more users    -->
</tsRequest>
--boundary-string--

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

Attribute Values

path-to-csv The filepath 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.

(For Tableau Server: This attribute only applies when adding users to sites with site-specific SAML enabled in settings.)

You can assign the following values for this attribute:

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

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.

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

201 Created

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" /e>
</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" authSetting="OpenID"/></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.

URI

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

Parameter Values

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

Request Body

None

Permissions

Users who are not server administrators or site administrators can initiate a file upload only if they have publishing rights on the site.

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:file_uploads:create

Response Code

201

Response Body

<tsResponse>
  <fileUpload uploadSessionId=new-upload-session-id
     fileSize=0 />
</tsResponse>        

Version

Version 2.0 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 403015 Access to Favorites forbidden A non-administrator user attempted to initiate a file upload, but the caller doesn't have publishing rights on the site.
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 POST.

For more information, see Handling Errors.

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.22. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

None

Permissions

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

Introduced Tableau Cloud June 2022 (API 3.16). Currently not available for Tableau Server.

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.


Lists the dashboard extensions on the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: This method can only be called by users with server or Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: This method can be called by users that have permissions Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

GET /api/api-version/sites/site-luid/lens/lens-Luid/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the metrics.
lens-luid The LUID of the ask data lens whose permissions are being listed.

Request Body

None

Permissions

Users with server or site administrator permissions, and non-administrators that have Read permission (either explicitly or implicitly), can list permissions for an ask data lens.

lu

Response Code

200

Response Body

<tsResponse>
  <permissions>
	<parent type="Project" id="project-luid" />
    <lens id="lens-luid"  name ="lens-name/>
    <granteeCapabilities>
      <user id="user-luid" />
      <capabilities>
        <capability name="capability" mtode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        <--    ... additional capabilities ...    -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-luid" />
      <capabilities>
        <capability name="capability" mode="Allow-or-Deny" />
        <capability name="capability" mode="Allow-or-Deny" />
        <--    ... additional capabilities ...    -->
      </capabilities>
    </granteeCapabilities>
    <--    ... additional grantee capability sets ...    -->
  </permissions>
</tsResponse>

Note: The parent element is included in the response only if the lens' permissions are determined by project-level default permissions and project permissions are 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.

Version

Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. For more information, see REST API and Resource Versions.

Errors

HTTP statuserror CodeConditionDetails
403403018Read forbiddenA non-administrator user attempted to query metrics for the site, but the caller doesn't have Read permission.
404404000Site not foundThe site ID in the URI doesn't correspond to an existing site.
404404046Lens not foundA lens with the requested LUID could be found.
405405000Invalid request methodRequest type was not GET.

For more information, see Handling Errors.

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.


Returns a list of ask data lenses in a site.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can be called by any user. Responses will include only the lenses to the user has access to. Permissions Overview

License: No additional license required.

Access Scope: `tableau:lenses:read` Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

List Authentication Configurations

List information about all authentication instances.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.


Lists the dashboard extensions on the blocked list of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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: Deprecated in API 3.17 - the following resource is no longer supported and will be retired in future releases: 

URI GET api/api-version/sites/site-id/connected-applications

Parameter Values

api-version The version of the API to use, such as 3.22. 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 connected app, including the following:

  • <secret>: Information related to the secret only if it has been previously generated. To create a secret for a connected app, see Create Connected App Secret. To get the secret value, see Query Connected App Secret.
  • <name>: Name of the connected app.
  • <enabled>: Whether the connected app is enabled or not.
  • <clientId>: The ID of the connected app.
  • <projectId>: The project that the connected app's access level is scoped to.
  • <domainSafelist>: If specified, one or more domains that the connected app is allowed to be hosted on.
  • <unrestrictedEmbedding>: Whether the connected app can be hosted on all domains. If false is returned, the <domainSafelist> attribute determines the domain access.

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.

Version: Available in API 3.18 (Tableau Cloud December 2024) and later. Not available for Tableau Server. Version Overview

License: No additional license required.

Permissions: Tableau administrators can get the list of the custom views on a site, including details of each custom view. For details of non-administrator users' permissions, see Permissions Details .  Permissions Overview

JWT Access Scope: tableau:content:read     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

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

GET /api/api-version/sites/site-luid/customviews?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/customviews?sort=sort-expression

GET /api/api-version/sites/site-id/customviews?fields=field-expression

GET /api/api-version/sites/site-id/customviews?fields=filter-expression

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression

(Optional) An expression that lets you specify the set of available fields to return. When a request has a valid field expression, describing the attributes of a Tableau resource like a workbook or datasource, only the attributes specified in the expression will be present in the response. For example, a field expression that results in a response containing only the resources LUIDs of the resources being requested would look like:

?field=id

You can qualify the expression to return values based upon predefined keywords such as _default_, which returns only default values, and _all_, which returns default and non-default values. You can include multiple field expressions in a request, and mix field, sort, and filter expressions in the same request.

The supported fields for custom views are its attributes: id, name, createdAt, updatedAt, and shared.

For more information, see Using Fields in the REST API.

filter-expression

(Optional) An expression that lets you filter which Tableau resources are present in the response. A filter expression has a resource, an operator, and a value. For example, a filter that returns only resources created after a specified date would look like:

?filter=createdAt:gt:2016-08-26T18:00:33Z (where gt is the greater-than operator)

You can include multiple filter expressions in a request, and mix field, sort, and filter expressions in the same request.

The supported filters for custom views use the eq (equals) operator, with the resources: viewId, ownerId, and workbookId.

For more information, see Filtering and Sorting in the Tableau REST APII.

sort-expression

(Optional) An expression that lets you sort the Tableau resources present in the response. A sort expression contains an attribute name and a direction (asc or desc). For example, a sort expression that sorts the requested resource by creation date with the latest date first would look like:

?sort=createdAt:desc

You can include multiple sort expressions in a request, and mix field, sort, and filter expressions in the same request.

The supported filters for custom views use the eq (equals) operator, with the resources: viewId, ownerId, and workbookId.

For more information, see Filtering and Sorting in the Tableau REST API.

Request Body

None.

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

cURL Request Example

curl -L -X GET "https://qa-near/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews" -H "X-Tableau-Auth: njR9EGn0QSCpbDrUOh0IKg"wamRRyVFFUHTVwFL6OWEyOggxCwWYXuq"a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

200

Response Body

<tsResponse >
  <pagination pageNumber="1" pageSize="100" totalAvailable="1673"/>
  <customViews>
	<customView
	  id="37d015c6-bc28-4c88-989c-72c0a171f7aa"
	  name="New name 2"
	  createdAt="2016-02-03T23:35:09Z"
	  updatedAt="2022-09-28T23:56:01Z"
	  shared="false">
	    <view id="8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f" name="circle"/>
	    <workbook id="2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5" name="marks and viz types 2"/>
	    <owner id="cdfe8548-84c8-418e-9b33-2c0728b2398a" name="workgroupuser"/>
	</customView>
	<!--    more custom views   -->
  </customViews>
</tsResponse>

{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "1673"
  },
  "customViews": {
	"customView": {
	  "id": "37d015c6-bc28-4c88-989c-72c0a171f7aa",
	  "name": "New name 2",
	  "createdAt": "2016-02-03T23:35:09Z",
	  "updatedAt": "2022-09-28T23:56:01Z",
	  "shared": "false",
	  "view": {
	    "id": "8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f",
	    "name": "circle"
	  },
	  "workbook": {
	    "id": "2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5",
	    "name": "marks and viz types 2"
	  },
	  "owner": {
	    "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
	    "name": "workgroupuser"
	  }
	}
	// more customViews
  }
}

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.


Lists the dashboard extension settings of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

List Data-Driven Alerts on Site

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

URI

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

URI

GET /api/api-version/sites/site-id/dataAlerts?pageSize=page-size&pageNumber=page-number

URI

GET /api/api-version/sites/site-id/dataAlerts?filter=viewId:eq:view-luid

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains data-driven alerts.

Version: Available in API 3.2 (Tableau Cloud / Tableau Server 2018.3) and later. Version Overview(Link opens in a new window)

License: No additional license required.>

Permissions: This method can only be called by server administrators and site administrators, and by users who are owners of the specified alert.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:data_driven_alerts:read     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

None

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
  <dataAlerts>
    <dataAlert id="alert-id" subject="alert-subject" creatorId="creator-id" createdAt="created-date" updatedAt="updated-date" frequency="alert-frequency" public="is-public-flag">
      <owner id="owner-id" name="username"/>
      <view id="view-id" name="view-name">
        <workbook id="workbook-id" name="workbook-name"/>
        <project id="project-id" name="project-name"/>
      </view>
    </dataAlert>
  </dataAlerts>
</tsResponse>
        

The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

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 the sites at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403004 Read forbidden A user queried this method who does not have the required permissions
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 or URL namespace 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.

Example

curl "http://MY-SERVER/api/3.22/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <dataAlerts>
    <dataAlert id="e5a4b73e-5cbb-412d-907e-f31cc31684f7" subject="Data alert - Shipping" creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-13T20:55:29Z" updatedAt="2018-08-21T00:05:34Z" frequency="daily" public="true">
      <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
      <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
        <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
        <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
      </view>
    </dataAlert>
  </dataAlerts>
</tsResponse>

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.

URI

GET /api/api-version/sites/site-id/schedules/schedule-id/extracts

GET /api/api-version/sites/site-id/schedules/schedule-id/extracts?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 2.2. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the refresh tasks.
schedule-id The ID of the schedule to get extract information for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

JWT Access Scope

Not available.

For more information on access scopes and connected apps, see Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window).

Request Body

None

Permissions

This method can only be called by server administrators and site administrators. When a site administrator calls this method, the payload contains only the tasks that are associated with the site that the user is signed in to.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
     pageSize="page-size"
     totalAvailable="total-available" />
  <extracts>
    <extract id="task-id"
      priority="task-priority"
      type="incremental-or-full" >
        <workbook id="workbook-id" />
    </extract>
    <extract id="task-id"
      priority="task-priority"
      type="incremental-or-full" >
        <datasource id="datasource-id" />
    </extract>
    ... additional extract refresh tasks ...
  </extracts>
</tsResponse>
        

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
400 400047 Invalid schedule type The schedule type does not represent an extract refresh task. (For example, it might be a subscription task.)
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.
404 404 Schedule not found The schedule ID in the URI doesn't correspond to an existing schedule.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/schedules/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba/extracts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
<pagination pageNumber="1" pageSize="100" totalAvailable="2" />
  <extracts>
    <extract id="639c7e80-0d11-44b2-9b5b-018ffc5eddb4" priority="60" type="FullRefresh">
      <datasource />
    </extract>
    <extract id="303f6c45-fb48-47aa-88d3-0dd87f5f5c74" priority="50" type="FullRefresh">
      <workbook />
    </extract>
  </extracts>
</tsResponse>

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.

URI

GET /api/api-version/sites/site-id/tasks/extractRefreshes

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.

JWT Access Scope

tableau:tasks:read (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

cURL Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/extractRefreshes" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of extract refresh tasks that they own.

Response Code

200

Response Body

Tableau Server and Tableau Cloud return different payloads in response to this request.

Tableau Server Request

For Tableau Server a lst of extract refresh tasks with their server schedules is returned.

Copy
<tsResponse>
  <tasks>
    <task>
      <extractRefresh id="refresh_task_id"
        priority="nn"
        consecutiveFailedCount="n"
        type="REFRESH_EXTRACT">
          <schedule id="schedule_id"
            name="schedule_name"
            state="state"
            priority="nn"
            createdAt="DATE_TIME"
            updatedAt="DATE_TIME"
            type="Extract"
            frequency="frequency"
            nextRunAt="DATE_TIME" />
          <datasource id="datasource_id" />
      </extractRefresh>    
    </task>
    <task>
      <!-- ... additional tasks ... -->
    </task>
  </tasks>                                
</tsResponse>
Copy
{
  "tasks": [
    {
      "extractRefresh": {
        "id": "refresh_task_id",
        "priority": "nn",
        "consecutiveFailedCount": "n",
        "type": "REFRESH_EXTRACT",
        "schedule": {
          "id": "schedule_id",
          "name": "schedule_name",
          "state": "state",
          "priority": "nn",
          "createdAt": "DATE_TIME",
          "updatedAt": "DATE_TIME",
          "type": "Extract",
          "frequency": "frequency",
          "nextRunAt": "DATE_TIME"
        },
        "datasource": {
          "id": "datasource_id"
        }
      }
    },
    []
  ]
}

Tableau Cloud Request

For Tableau Cloud a list of extract tasks with their frequency is returned.

Response for a server schedule on Tableau Server:

Copy
<tsResponse>
  <tasks>
    <task>
      <extractRefresh id="0ece2369-c4eb-4382-be0f-961039d708a0" priority="50" consecutiveFailedCount="5" type="RefreshExtractTask">
        <schedule frequency="Weekly" nextRunAt="2023-06-08T04:50:00Z">
          <frequencyDetails start="21:50:00">  
            <intervals>
              <interval weekDay="Wednesday"/>
            </intervals>
          </frequencyDetails>
        </schedule>
        <workbook id="7e766949-7166-4b3d-90ba-784f7575743b"/>
      </extractRefresh>
    </task>
  </tasks>
</tsResponse>
Copy
{
  "tasks": {
    "task": {
      "extractRefresh": {
        "id": "0ece2369-c4eb-4382-be0f-961039d708a0",
        "priority": "50",
        "consecutiveFailedCount": "5",
        "type": "RefreshExtractTask",
        "schedule": {
          "frequency": "Weekly",
          "nextRunAt": "2023-06-08T04:50:00Z",
          "frequencyDetails": {
            "start": "21:50:00",
            "intervals": {
              "interval": [
                { "weekDay": "Thursday" }
              ]
            }
          }
        },
        "workbook": {
          "id": "7e766949-7166-4b3d-90ba-784f7575743b"
        }
      }
    }
  }
}

Version

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

Errors

405 40500 Invalid requests method Request type was not GET

For more information, see Handling Errors.

List Identity Pools

List all identity pools.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

List Identity Stores

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

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Can be called by any user, but only returns definitions Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions_metrics:read
Access Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

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

GET /api/api-version/sites/site-id/metrics?filter=filter-expression

GET /api/api-version/sites/site-id/metrics?sort=sort-expression

GET /api/api-version/sites/site-id/metrics?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/metrics?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the metrics.
filter-expression (Optional) An expression that lets you specify a subset of metrics to return. You can filter on predefined fields such as metric name, or attributes of the associated owner or project. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which metric information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the metrics or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

Users who are not administrators can get only the metrics for which they have implicit or explicit Read (view) permissions.

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:content:read
            

Response Code

200

Response Body

                    <tsResponse>
  <pagination pageNumber="page-number"
     pageSize="page-size"
     totalAvailable="total-available" />
  <metrics>
    <metric id="metric-id"
		name="name"
		description="metric-description"
		webpageurl="metric-webpageurl"
        createdAt="datetime-created"
	    updatedAt="datetime-updated"
	    suspended="suspended-flag" >
	      <project id="project-id" name="project-name" />
	      <owner id="user-id" />
	      <tags>
	        <tag label="tag"/>
	        ... additional tags ...
	     </tags>
	<underlyingView" id="view-id" />
   </metric>
   ... additional metrics ...
  </metrics>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size exceeds upper limit The page size parameter exceeds the system-wide upper limit of 1000.
403 403018 Read forbidden A non-administrator user attempted to query metrics for the site, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Metrics not found No metrics are configured for this site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response body:

                    <tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="27"/>
  <metrics>
    <metric id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
		name="my first metric"
        description="Description of my_first_metric."
		webpageUrl="https://MY-SERVER/#/site/site-name/metrics/site-num"
		createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
		suspended="false" >
	      <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
	      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	      <tags/>
		underlyingView="29dae0cd-1862-4a20-a638-e2c2dfa682d4"
    </metric>
    <metric id="29dae0cd-1862-4a20-a638-e2c2dfa682d4a" name="my_second_metric"
		description="Description of my second metric."
		webpageUrl="https://MY-SERVER/#/site/site-name/metrics/site-num"
        createdAt="2014-02-19T10:19:23Z" updatedAt="2015-12-29T013:23:45Z"
		suspended="false" >
		  <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="default"/>
	      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	      <tags>
          <tag label="training" ></tags>
    </metric>
	<!-- ...more metrics ... --:>
  </metrics>
  </tsResponse>
        

List metrics in definition

Lists the metrics contained in a metric definition.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions_metrics:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.21 (Tableau Cloud October 2023) and later.Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Any Tableau Cloud user. If you're a Tableau Cloud site admin, you can list the PATs of a user when you are the site admin on all sites that the PAT owner is a member of. Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

GET /api/api-version/sites/site-luid/users/user-luid/personal-access-tokens

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
user-luid The LUID of the user. The user LUID is returned after you successfully authenticate to the Tableau REST API.

Request Body

None

cURL Request Example

curl "http://myco/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/d5704762-603a-42b2-a9a7-f9cd2b2c4253/personal-access-tokens" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy
<tsResponse>
    <personalAccessTokens>
        <personalAccessToken tokenName="user_pat1" tokenGuid="011b6267-a067-473a-9d16-b34cc58f90df" lastUsedAt="2023-06-13T16:55:46Z" expiresAt="2024-06-12T16:55:46Z"/>
        <personalAccessToken tokenName="user_pat4" tokenGuid="0fb30637-b638-4ce2-bbac-ac6611104ed9" lastUsedAt="2023-06-13T16:55:51Z" expiresAt="2024-06-12T16:55:51Z"/>
        <personalAccessToken tokenName="user_pat5" tokenGuid="db8c0b5d-5946-4f7c-a966-af334a3d10a5" lastUsedAt="2023-06-13T16:55:56Z" expiresAt="2024-06-12T16:55:56Z"/>
    </personalAccessTokens>
</tsResponse>

Copy
{
  "personalAccessTokens": [
    {
      "tokenName": "user_pat1",
      "tokenGuid": "011b6267-a067-473a-9d16-b34cc58f90df",
      "lastUsedAt": "2023-06-13T16:55:46Z",
      "expiresAt": "2024-06-12T16:55:46Z"
    },
    {
      "tokenName": "user_pat4",
      "tokenGuid": "0fb30637-b638-4ce2-bbac-ac6611104ed9",
      "lastUsedAt": "2023-06-13T16:55:51Z",
      "expiresAt": "2024-06-12T16:55:51Z"
    },
    {
      "tokenName": "user_pat5",
      "tokenGuid": "db8c0b5d-5946-4f7c-a966-af334a3d10a5",
      "lastUsedAt": "2023-06-13T16:55:56Z",
      "expiresAt": "2024-06-12T16:55:56Z"
    }
  ]
}

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

Introduced Tableau Cloud June 2022 (API 3.16). Currently not available for Tableau Server.

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.

URI

GET /api/api-version/domains/

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

<tsRequest>
  <domainList>
    <domain id="domain-id-int"
  	  name="domain-name"
	  shortName="domain-nickname" />
  </domainList>
</tsRequest>
        

Version

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

Errors

HTTP status error Code Condition Details
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/domains" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response body:

<tsRequest>
  <domainList>
    <domain id="1045" name="domain.com" shortName="myDomainNickName" />
    < . . . more domains . . . />
  </domainList>
</tsRequest>
        

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.

URI

GET /api/api-version/schedules

GET /api/api-version/schedules?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 2.2. For more information, see REST API and Resource Versions.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

On Tableau Server, any user able to schedule extract refreshes and any site or server administrator can get schedules.

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="pageNumber" pageSize="page-size"
	totalAvailable="total-available" />
   <schedules>
  	<schedule id="schedule-id"
	   name="schedule-name"
	   state="Active-or-Suspended"
	   priority="schedule-priority"
	   createdAt="datetime-created"
	   updatedAt="datetime-last-updated"
	   type="extract-or-subscription-or-flow"
	   frequency="schedule-frequency"
	   nextRunAt ="datetime-next-run-time"
	   endScheduleAt ="datetime-expiration" />
	... additional schedules ...
   </schedules>
</tsResponse>
        

The datetime-created, datetime-last-updated, datetime-next-run-time, and datetime-expiration attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Example

curl "http://MY-SERVER/api/3.22/schedules" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings >
   <pagination pageNumber="1" pageSize="100" totalAvailable="3" />
   <schedules>
	<schedule id="ca3ce4f5-666c-4bb8-a763-5df24783881f"
	   name="Hourly"
	   state="Active"
	   priority="50"
	   createdAt="2011-03-30T22:32:35Z"
	   updatedAt="2016-01-13T01:00:02Z"
	   type="Extract"
	   frequency="Hourly"
	   nextRunAt="2016-01-13T23:00:00Z" />
	<schedule id="13abd238-0b22-4789-bcc4-614d31908310"
	   name="Saturday night"
	   state="Active"
	   priority="50"
	   createdAt="2010-10-28T21:11:33Z"
	   updatedAt="2016-01-10T07:00:00Z"
	   type="Extract"
	   frequency="Weekly"
	   nextRunAt="2016-01-17T07:00:00Z" />
	<schedule id="b6a6d11a-9e20-49f1-9b74-693f196b9aca"
	   name="End of the month"
	   state="Suspended"
	   priority="50"
	   createdAt="2010-10-28T21:11:33Z"
	   updatedAt="2016-01-01T07:00:03Z"
	   type="Extract"
	   frequency="Monthly"
	   nextRunAt="2016-02-01T07:00:00Z" />
   </schedules>
</tsResponse>
          

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

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.


Lists the dashboard extension settings of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

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

GET /api/api-version/sites/site-id/subscriptions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the subscriptions.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

JWT Access Scope

tableau:tasks:read (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

None

Curl Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/subscriptions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Permissions

Tableau Server administrators and all site administrators can get subscription information for users of projects within the scope of their administrative permissions. Other users can get subscription information only for their own subscriptions.

Response Code

200

Response Body

Tableau Server and Tableau Cloud return different payloads in response to this request.

Tableau Server Request

For Tableau Server, a subscription task with a server schedule is returned.

Copy
<tsResponse>
   <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available"  />
   <subscriptions>
     <subscription id="subscription-id"
       subject="subscription-subject"
       attachImage="attach-image-flag"
       attachPdf="attach-pdf-flag"
       suspended="suspended-flag"
       pageOrientation="page-orientation"
       pageSizeOption="page-size-option" >
         <content id="content-id"
           type="content-type"
           sendIfViewEmpty="send-view-if-empty-flag"/>
         <schedule id="schedule-id" name="schedule-name"/>
         <user id="user-id" name="user-name" />
     </subscription>
     <!--   ... additional subscriptions ...   -->
   </subscriptions>
 </tsResponse>
Copy
{
  "pagination": {
    "pageNumber": "pageNumber",
    "pageSize": "page-size",
    "totalAvailable": "total-available"
  },
  "subscriptions": {
    "subscription": {
      "id": "subscription-id",
      "subject": "subscription-subject",
      "attachImage": "attach-image-flag",
      "attachPdf": "attach-pdf-flag",
      "suspended": "suspended-flag",
      "pageOrientation": "page-orientation",
      "pageSizeOption": "page-size-option",
      "content": {
        "id": "content-id",
        "type": "content-type",
        "sendIfViewEmpty": "send-view-if-empty-flag"
      },
      "schedule": {
        "id": "schedule-id",
        "name": "schedule-name"
      },
      "user": {
        "id": "user-id",
        "name": "user-name"
      }
    }
  }
}

Tableau Cloud Request

For Tableau Cloud, a task with frequency is returned.

Copy
<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
  <subscriptions>
    <subscription id="92cb4f51-7a15-41d4-bce4-a0fcce5fa985" 
      subject="Subscription - postman" 
      message="weekly report" 
      attachImage="true" 
      attachPdf="false" 
      suspended="false">
        <content id="be016ba6-d0a8-44ae-a057-b6df6931ccaa" 
          type="Workbook" sendIfViewEmpty="true"/>
            <schedule frequency="Weekly" 
              nextRunAt="2023-06-08T17:05:00-0700">
                <frequencyDetails start="17:05:00">
                  <intervals>
                    <interval weekDay="Thursday"/>
                  </intervals>
                </frequencyDetails>
              </schedule>
              <user id="14064b01-7d58-4978-bdeb-a5f8d7694863" 
                name="me@mysite.com"/>
    </subscription>
  </subscriptions>
</tsResponse>
Copy
{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "1"
  },
  "subscriptions": {
    "subscription": {
      "id": "92cb4f51-7a15-41d4-bce4-a0fcce5fa985",
      "subject": "Subscription - postman",
      "message": "weekly report",
      "attachImage": "true",
      "attachPdf": "false",
      "suspended": "false",
      "content": {
        "id": "be016ba6-d0a8-44ae-a057-b6df6931ccaa",
        "type": "Workbook",
        "sendIfViewEmpty": "true"
      },
      "schedule": {
        "frequency": "Weekly",
        "nextRunAt": "2023-06-08T17:05:00-0700",
        "frequencyDetails": {
          "start": "17:05:00",
          "intervals": {
            "interval": [
              { "weekDay": "Thursday" }
            ]
          }
        }
      },
      "user": {
        "id": "14064b01-7d58-4978-bdeb-a5f8d7694863",
        "name": "memysite.com"
      }
    }
  }
}

Version

For Tableau Server: API 2.3 and later. For Tableau Cloud: API 3.20 (June 2023) and later. For more information, see REST API and Resource Versions.

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 the sites at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

List subscriptions

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

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user that has read or connect permission to Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:read
Access Scopes Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

List Tableau extensions server settings

Lists the settings for extensions of a server.

Version: Available in API 3.21 (Tableau Server 2023.3) and later. Not available for Tableau Cloud. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by users with server administrator permissions.   Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available.

URI

GET /api/api-version/settings/extensions

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

None

cURL Request Example

curl --location http://MY-SERVER/api/3.22/settings/extensions" --header "X-Tableau-Auth: SBGBfOYRSN2JoFe866wpIg|hLI0ZzWmK3xfMtwD8WoztCMqfWaFdcCj|a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

200

Response Body

Copy
<tsRequest>
<extensionsServerSettings>
        <extensionsGloballyEnabled>true</extensionsGloballyEnabled>
    </extensionsServerSettings>
</tsRequest>
Copy
{
  "extensionsServerSettings": {
    "extensionsGloballyEnabled": "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 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.

Version: Available in API 3.21 (Tableau Cloud June 2023 / Tableau Server 2023.3) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by users with site or server administrator permissions.   Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available.

URI

GET /api/api-version/sites/site-luid/settings/extensions

URI Parameter Values

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

Request Body

None

cURL Request Example

curl --location "http://MY-SERVER/api/3.22/sites/a946d998-2ead-4894-bb50-1054a91dcab3/settings/extensions " --header "X-Tableau-Auth: SBGBfOYRSN2JoFe866wpIg|hLI0ZzWmK3xfMtwD8WoztCMqfWaFdcCj|a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

200

Response Body

Copy
<tsResponse>
    <extensionsSiteSettings>
        <extensionsEnabled>true</extensionsEnabled>
        <useDefaultSetting>false</useDefaultSetting>
        <safeList>
            <url>http://localhost:9123/Dynamic.html</url>
            <fullDataAllowed>true</fullDataAllowed>
            <promptNeeded>true</promptNeeded>
        </safeList>
    </extensionsSiteSettings>
</tsResponse>
Copy
{
  "extensionsEnabled": "true",
  "useDefaultSetting": "false",
  "safeList": {
    "url": "http://localhost:9123/Dynamic.html",
    "fullDataAllowed": "true",
    "promptNeeded": "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 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.

Version: Preview release available in some regions API 3.21 (Tableau Cloud October 2023 / Server 2023.3) and later. Version Overview

License: No additional license required.

Permissions: Only Tableau administrators can list users whose default view is the specified custom view.  Permissions Overview

JWT Access Scope: tableau:content:read     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

GET /api/api-version/sites/site-luid/customviews/custom-view-luid/default/users

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
custom-view-luid The LUID for the custom view being updated.

Request Body

None.

cURL Request Example

curl --location 'https://qa-near.tsi.lan/api/3.21/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/3321cb71-6606-4d78-8a0c-e69a7e7d2261/default/users' --header 'Accept: application/xml' --header 'X-Tableau-Auth: LfzV48kKRUOYMYbzamWRpA|bfkD8ruGmN8ZNGmdL03PHB0gMHGtCfOk|a946d998-2ead-4894-bb50-1054a91dcab3'

Response Code

200

Response Body

Copy
<tsResponse >
  <pagination pageNumber="1" 
    pageSize="100" 
    totalAvailable="1"/>
      <users>
        <user id="5c9a81df-7ec0-4752-a057-82cd2bb22c44"/>
      </users>
</tsResponse>
Copy
{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "1"
  },
  "users": {
    "user": [
      {
        "id": "5c9a81df-7ec0-4752-a057-82cd2bb22c44"
      }
    ]
  }
}

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 Virtual Connection Database Connections

Returns a list of database connections found in the specified virtual connection and information about them.

Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1) and later. Version Overview

License: Requires Tableau Data Management(Link opens in a new window).

Permissions: Users who are not administrators can query a virtual connection only if they have explicit or implicit [Connect] (view) permission for the virtual connection.  Permissions Overview

JWT Access Scope: Not available.

URI

GET /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/connections

GET /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/connections?pageSize=page-size&pageNumber=page-number

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site that contains the virtual connection.
virtual-connection-luid The LUID for the virtual connection that includes the database connections.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

cURL Request Example

curl --location --request GET "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections/26bc30d8-90d6-4af1-922d-ac285e7b08fb/connections?X-Tableau-Auth =3bl3fJb0T6qxhaCqneNhWg"Nmv6zrJfYeiiovCuEs2grrBAZlREbRGl"a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" />
  <virtualConnectionConnections>
    <connection
      id="connection-id" 
      serverAddress="server-address" 
      dbClass="database-type" 
      serverPort="port-number" 
      userName="connection-user-name"/>
  </virtualConnectionConnections>
</tsResponse>

{
  "pagination": {
    "pageNumber": "pageNumber",
    "pageSize": "page-size",
    "totalAvailable": "total-available"
  },
  "virtualConnectionConnections": {
    "connection": {
      "id": "connection-id",
      "serverAddress": "server-address",
      "dbClass": "database-type",
      "serverPort": "port-number",
      "userName": "connection-user-name"
    }
  }
}

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 Connections

Returns a list of available virtual connection names and IDs.

Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1) and later. Version Overview

License: Requires Tableau Data Management(Link opens in a new window).

Permissions: By default, all users can view virtual connections.  Permissions Overview

JWT Access Scope: Not available.

URI

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

GET /api/api-version/sites/site-luid/virtualconnections/?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-luid/virtualconnections/?filter=filter-expression

GET /api/api-version/sites/site-luid/virtualconnections/?sort=sort-expression

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site that contains the virtual connection.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of virtual connections to return. You can filter on predefined fields such as name, tags, and createdAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which virtual connection information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.

Request Body

None

cURL Request Example

curl --location --request GET "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections" \ --header "X-Tableau-Auth: 3bl3fJb0T6qxhaCqneNhWg"Nmv6zrJfYeiiovCuEs2grrBAZlREbRGl"a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

200

Response Body

<tsResponse> 
  <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="total-available" />
  <virtualConnections>
    <virtualConnection 
      createdAt="datetime-created" 
      hasExtracts="has-extracts-flag" 
      id="virtual-connection-luid" 
      isCertified="is-certified-flag" 
      name="virtualconnection-name" 
      updatedAt="datetime-updated" 
      webpageUrl="web-page-url"/>
  </virtualConnections>
</tsResponse>

{
  "pagination": {
    "pageNumber": "page-number",
    "pageSize": "page-size",
    "totalAvailable": "total-available"
  },
  "virtualConnections": {
    "virtualConnection": {
      "createdAt": "datetime-created",
      "hasExtracts": "has-extracts-flag",
      "id": "virtual-connection-luid",
      "isCertified": "is-certified-flag",
      "name": "virtualconnection-name",
      "updatedAt": "datetime-updated",
      "webpageUrl": "web-page-url"
    }
  }
}

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.

URI

GET /api/3.6/sites/<site-id>/webhooks

Parameter Values

site-id The ID of the site that contains the webhooks.   

Request Body

None

Permissions

This method can only be called by server and site administrators.

Response Code

200

Response Body

<tsResponse>
  <webhooks>
    <webhook
      id="webhook-id"
      name="webhook-name"
      isEnabled="true"
      statusChangeReason=""
      event="api-event-name">
        <webhook-source>
          <webhook-source-api-event-name />
        </webhook-source>
        <webhook-destination>
          <webhook-destination-http method="POST" url="url"/>
        </webhook-destination>
        <owner id="webhook_owner_luid" name="webhook_owner_name"/>
  </webhook>
  <!--  ... additional webhooks ...  -->
  </webhooks>
</tsResponse>

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

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

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.

URI

PUT /api/api-version/sites/site-id/orderFavorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
user-id The ID of the user for which you want to get a list favorites.

Request Body

<tsRequest>
   <favoriteOrderings>
	<favoriteOrdering favoriteId="favorite-id" favoriteType="content-type" favoriteIdMoveAfter="favorite-id-after" favoriteTypeMoveAfter="content-type" />
   </favoriteOrderings>
</tsRequest>
          

Attribute Values

favorite-id The ID of the favorite you want to move.
content-type The content type of a favorite. To specify the type, use one of the following values:
  • datasource
  • workbook
  • view
  • project
  • flow
These values are not case sensitive.
favorite-id-after The ID of the favorite that should follow, or come after, the favorite you want to move.

Permissions

Users who are not server administrators or site administrators can call this method only if they are the user for which they want to move favorites.

Response Code

200

Response Body

None

Version

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

Errors

403 403004 Forbidden Favorites access A non-administrator user called this method but doesn't have permission to view the specified user's favorites.
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.
404 404010 Favorite not found The favorite ID specified doesn't correspond to a user's favorite.

For more information, see Handling Errors.

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.

Version: Available in API 2.0 and later. Version overview

License: Available for Tableau Server and Tableau Cloud.

Permissions: You can publish a data source if you have implicit or explicit Publish permissions for the data source, or are a Tableau administrator. Note: The queryTaggingEnabled attribute is returned only for administrator users. Permissions Overview

JWT Access Scope: tableau:datasources:create     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

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.

URI

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

POST /api/api-version/sites/site-luid/datasources?overwrite=overwrite-flag&asJob=asJob-value

POST /api/api-version/sites/site-luid/datasources?append=append-flag

POST /api/api-version/sites/site-luid/datasources?uploadSessionId=upload-session-id&datasourceType=datasource-file-type&overwrite=overwrite-flag&append=append-flag

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site to publish to.
overwrite-flag true to overwrite a data source that has the same name, or false to fail if the specified data source already exists. The default is false. If overwrite-flag is set to true but the data source doesn't already exist, the operation succeeds.

You can include both the overwrite and append parameters in a request, but they cannot both be true.

asJob-value A Boolean value that is used to publish data sources asynchronously. If you set this value to false (the default), the publishing process runs as a synchronous process. If a data source is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job.
append-flag true to append the data being published to an existing data source that has the same name. The default is false. If append-flag is set to true but the data source doesn't already exist, the operation fails.

In order to append data to a published data source on Tableau Server, both the source file and the published file must be an extract with the file extension .hyper or .tde. The schema of the source and the published extract must match.

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

You can include both the overwrite and append parameters in a request, but they cannot both be true.

upload-session-luid If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session LUID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
datasource-file-type hyper, tds, tdsx, or tde the kind of file that you are uploading. This value is required if you are calling Publish Data Source in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request.

Request Body

The content type in the header of requests to publish a data source must use the mixed multipart content type with a boundary string definition, in the form of: Content-Type: multipart/mixed; boundary=boundary-string.

Publishing a file in the request body

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
	<datasource name="Sales"
	useRemoteQueryAgent="False"
	description="Sales Data Source">
		<connectionCredentials name="janedoe"
		  password="xxxxxx"
			embed="True" />
		<project id="ff2a8360-3c2b-4b05-a793-7607c602e1fb" />
  </datasource>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_datasource"; filename="Sales.TDSX"
Content-Type: application/octet-stream
	content-of-datasource-file
--boundary-string--
		

Committing a file previously uploaded

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
	<datasource name="Sales" >
		<connectionCredentials name="janedoe" password="xxxxxx"
			embed="False" oAuth="True" />
		<project id="ff2a8360-3c2b-4b05-a793-7607c602e1fb" />
  </datasource>
</tsRequest>
--boundary-string--
						

Publishing a file in the request body


Content-Length: 16301
Content-Type: multipart/form-data; boundary=----------------------my_boundary_string
----------------------my_boundary_string
Content-Disposition: form-data; name="part1.json"
Content-Type: application/json
{
  "the_JSON" : {
	"foo" :  "bar"
  }
}
----------------------my_boundary_string
Content-Disposition: form-data; name="datasource.tdsx"
Content-Type: application/pdf
  "datasource": {
	"name": "Sales",
	"useRemoteQueryAgent": "True",
	"description": "Sales Data Source",
	"connectionCredentials": {
	  "name": "janedoe",
	  "password": "xxxxxx",
	  "embed": "True"
	},
	"project": {
	  "id": "ff2a8360-3c2b-4b05-a793-7607c602e1fb"
	}
  }
}
----------------------my_boundary_string--

Committing a file previously uploaded


Content-Length: 16301
Content-Type: multipart/form-data; boundary=----------------------my_boundary_string
Content-Disposition: form-data; name="part1.json"
Content-Type: application/json
{
  "the_JSON" : {
	"foo" :  "bar"
  }
}
----------------------my_boundary_string
Content-Disposition: form-data; name="datasource.tdsx"
Content-Type: application/pdf
  "datasource": {
	"name": "Sales",
	"connectionCredentials": {
	  "name": "janedoe",
	  "password": "xxxxxx",
	  "embed": "True",
	  "oAuth": "True"
	},
	"project": {
	  "id": "ff2a8360-3c2b-4b05-a793-7607c602e1fb"
	}
  }
}
----------------------my_boundary_string--
						

Request Attributes

boundary-string (Required) A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string

datasource name (Required) The name to assign to the data source when it is saved on the server.
datasource useRemoteQueryAgent (Optional) When true, this flag will allow your Tableau Cloud site to use Tableau Bridge clients(Link opens in a new window). Bridge allows you to maintain data sources with live connections to supported on-premises data sources.
datasource description (Optional) A description of the datasource.
connectionCredentials

The <connectionCredentials> element is required if the data source requires credentials. If the data source does not require credentials, Tableau will ignore this element if it is present. connectionCredentials attributes are:

username
(Required, depending on oAuth setting) The connection ceredentials username.

password
(Required, depending on oAuth setting) The connection credential password.

embed
(Optional) If true credentials are embedded in the datasource. Default is false.

oAuth
(Optional) If the data source connection is configured to use OAuth, set this to true to specify that the value of the name attribute in the connectionCredentials element is an OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the data source. For more information, see OAuth Connections(Link opens in a new window) in the Tableau Server documentation.

project The LUID of the project to assign the data source to. If the project is not specified, the data source will be published to the default project.
datasource-file-name The file name (including extension) of the data source file to upload. This attribute is used in the request body only if the request also includes the content of the data source file; it is not used if you are committing a file uploaded using previous requests.
content of datasource file The content of the data source file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.
askDataEnablement

This attribute is not available in API 3.12 and later (Tableau Cloud September 2021 / Server 2021.3).

cURL Example

curl "http://MY_SERVER/api/3.4/sites/ff2a8360-3c2b-4b05-a793-7607c602e1fb/datasources" -X POST -H "X-Tableau-Auth:6fSulU7ET8yjpHteQj56MQ|LrkEdTHcmPkWFcD8wOEy29hlVXm8iPo4" -H "Content-Type: multipart/mixed;" -F "request_payload=@publish-datasource.xml" -F "tableau_datasource=@data-source.tds"

Content of publish-datasource.xml:

<tsRequest>
  <datasource name="datasource1" description="This is a data source named datasource1." >
    <project id="522dc5c5-e1da-47b9-8e07-f02929ff5ceb" />
  </datasource>
</tsRequest>

Response Code

201

Response Body

<tsResponse>
  <datasource
	id="75b71d2f-e8d3-42af-b654-d953659326ee"
	name="Sales"
	contentUrl="mySite"
	description="Sales Data Source"
	useRemoteQueryAgent="True"
	webpageUrl="https://my_server/#/datasources/222"
	type="excel-direct"
	createdAt="2016-02-12T23:36:09Z"
	updatedAt="2020-12-16T15:33:03Z"
	isCertified="False"
	certificationNote="This is a certification note."
	encryptExtracts="True">
	  <project
		id="56c86f04-b834-4a08-a561-86497bb4b2df"
		name="Visualization"/>
	  <owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613"/>
	  <tags/>
  </datasource>
</tsResponse>

{
  "datasource": {
	"id": "75b71d2f-e8d3-42af-b654-d953659326ee",
	"name": "Sales",
	"contentUrl": "mySite",
	"description": "Sales Data Source",
	"useRemoteQueryAgent": "True",
	"webpageUrl": "https://my_server/#/datasources/222",
	"type": "excel-direct",
	"createdAt": "2016-02-12T23:36:09Z",
	"updatedAt": "2020-12-16T15:33:03Z",
	"isCertified": "False",
	"certificationNote": "This is a certification note.",
	"encryptExtracts": "True",
	"project": {
	  "id": "56c86f04-b834-4a08-a561-86497bb4b2df",
	  "name": "Visualization"
	},
	"owner": {
	  "id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
	},
	"tags": []
  }
}

The createdAt and updatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Headers

Location: /api/3.22/sites/site-id/datasources/id-from-server

Errors

HTTP status error Code Condition Details
400 400000 Bad request The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set.
400 400000 Missing data source There is no attachment in the request for the data source.
400 400008 Invalid overwrite value The overwrite parameter must be set to true or false.
400 400008 Invalid append value The append parameter must be set to true or false.
400 400008 Invalid embed value The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false.
400 400010 Invalid data source filename The name of the data source file did not end with the suffix .hyper, .tds, .tdsx, or .tde.
400 400010 Missing or invalid file type The request included an uploadSessionId parameter but no file type, or the file type was something other than hyper, tds, tdsx, or tde.
400 400010 Unexpected attachments The message had both a uploadSessionId parameter and an attachment, or the message contained more than one attachment.
400 400011 Publishing error The data source could not be published for some other reason than those specified earlier.
400 400019 Malformed request body The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set.
400 400055 Incompatible overwrite and append values The overwrite and append parameter cannot both be set to true.
400 400129 Invalid Ask Data enablement The enablement setting in the request body is not valid for the current server configuration.
403 403007 Insufficient publishing permission A non-administrator user attempted to publish a data source, but the caller doesn't have sufficient project permissions.
403 403007 Unlicensed publishing forbidden A non-administrator user who is unlicensed attempted to publish a data source. This is disallowed for all projects (including the default project).
403 403007 Overwrite forbidden A data source with the specified name already exists and the overwrite parameter was not set to true.
403 403007 Problem connecting to data source There was a problem connecting to a data source. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server.
403 403008 Insufficient storage quota The data source could not be published because there is not enough storage remaining on the server to accommodate its size.
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 append parameter is true but the data source name specified in the request body does not correspond to an existing data source.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404015 File upload not found The file upload session ID in the request body doesn't correspond to an existing file upload on the site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

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.

URI

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

POST /api/api-version/sites/site-id/flows?overwrite=overwrite-flag

POST /api/api-version/sites/site-id/flows?overwrite=overwrite-flag&uploadSessionId=upload-session-id&flowType=flow-file-type

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to publish to.
overwrite-flag (Optional) true to overwrite a flow that has the same name, or false to fail if the specified flow already exists. The default is false. If overwrite-flag is set to true but the flow doesn't already exist, the operation succeeds.
upload-session-id If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
flow-file-type tfl or tflx to indicate whether you have uploaded a flow file (tfl) or a packaged flow file (tflx). This value is only necessary and required if you upload a file in multiple parts. In the Publish Flow call after completing file upload, specify the file type.

Publishing a file in the Request Body

 --boundary-stringContent-Disposition:
name="request_payload"
Content-Type: text/xml
<tsRequest>
	<flow name="flow-name" >
		<project id="project-id" />
	</flow>
	<connections>
		<connection id="abc"
			password="connection-password"
			username="connection username"
			embed="embed-flag">
		<connectionCredentials
			name="connection-username"
			password="connection-password"
			embed="embed-flag" />
		</connection>
		</connections>
</tsRequest>

--boundary-string
Content-Disposition: name="tableau_flow"; filename="flow-file-name"
Content-Type: application/octet-stream
content-of-flow-file
--boundary-string--
      

Attribute Values

name The name to assign to the flow when it is saved on the server.
description The description of the flow.
server-address Specify the server address for an input connections.
port-number Specify the port number for input connections.
connection-username (Optional) If the flow input connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection username. If the element is included but is not required, the server ignores the element and its attributes.
connection-password (Optional) If the flow input connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection password. If the element is included but is not required, the server ignores the element and its attributes.
embed-flag (Optional) If the input connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to Trueinstructs the server to save the credentials.
project-id The ID of the project to assign the flow to.
content-of-flow-file The file itself if you are including it in the request body.

Permissions

Users who are not server administrators or site administrators can publish a flow only if the flow belongs to a project that they have permissions to publish to, have a site role that allows publishing and have write permissions on the flow this is an overwrite.

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:flows:create

Response Code

201

Response Body

<tsResponse>
      <flow id="770a1cf8-6abe-4bc3-b0b8-59c4b15ce959"
            name="ShortTermRentalNola222"
            description=""
            webpageUrl="http://localhost/#/flows/3"
            fileType="tflx" createdAt="2018-11-20T19:28:58Z"
            updatedAt="2018-11-20T19:28:58Z">
           <project id="9077e04c-ece4-11e8-aa58-df538c72f42f"
            name="Default" />
           <owner id="5a39de9c-4eb0-47a7-88f7-2e78ddd58c6b" />
      </flow>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Malformed request body The XML content in the MIME multipart request is not empty.
400 400089 Missing flow name Flow name is required and was not specified.
403 403007 Invalid permissions The caller does not have the necessary permissions to publish the flow. 
400 400090 Missing flow payload The flow information (the structure containing the flow description, flow project) was not included in the request body.
400 400086 Invalid flow attachment The name of the flow doesn't end in .tfl or .tflx.
400 400087 Generic flow publishing error The flow could not be published for some other reason than those specified earlier.
409 409041 Flow already found in destination The flow name should be unique, or the overwrite flag parameter should be set to true.
403 403008 Insufficient storage quota The flow could not be published because there is not enough storage remaining on the server to accommodate its size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not POST.

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.

URI

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

POST /api/api-version/sites/site-id/workbooks?overwrite=overwrite-flag

POST /api/api-version/sites/site-id/workbooks?skipConnectionCheck=skip-connection-check-flag

POST /api/api-version/sites/site-id/workbooks?uploadSessionId=upload-session-id&workbookType=workbook-file-type&overwrite=bool&asJob=asJob-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to publish to.
overwrite-flag (Optional) true to overwrite a workbook that has the same name, or false to fail if the specified workbook already exists. The default is false. If overwrite-flag is set to true but the workbook doesn't already exist, the operation succeeds.
asJob-value (Optional, boolean) If false, the workbook publishing process runs as a synchronous process. If a workbook is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job. Default value is false.
skip-connection-check-flag (Optional, boolean) If true, then the Tableau server will not check if a non-published connection of a workbook is reachable. Publishing will succeed but unchecked connection issues may result in a non-functioning workbook. If you encounter this issue, follow Keep Data Fresh guidelines(Link opens in a new window). Default value is false.
upload-session-id If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
workbook-file-type twb or twbx to indicate whether you have uploaded a workbook file (twb) or a packaged workbook file (twbx). This value is required if you are calling Publish Workbook in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request.

Request Body

The content type in the header of requests to publish a workbook must use the mixed multipart content type with a boundary string definition, in the form of: Content-Type: multipart/mixed; boundary=boundary-string.

Publishing a file in the request body

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" thumbnailsUserId="user-luid">
    <connections>
    <connection serverAddress="server-address" serverPort="port-number">
    <connectionCredentials name="connection-username" password="connection-password"
          embed="embed-flag" />
    </connection>
    </connections>
    <project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_workbook"; filename="workbook-file-name"
Content-Type: application/octet-stream
content-of-workbook-file
--boundary-string--
        

Committing a file previously uploaded

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" thumbnailsUserId="user-luid" >
    <connections>
    <connection serverAddress="server-address" serverPort="port-number">
    <connectionCredentials name="connection-username" password="connection-password"
          embed="embed-flag" oAuth="oauth-flag" />
    </connection>
    </connections>
    <project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string--
        

Hiding a view when publishing a workbook

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" thumbnailsUserId="user-luid" >
    <connections>
      <connection serverAddress="server-address" serverPort="port-number">
        <connectionCredentials name="connection-username" password="connection-password"
           embed="embed-flag" oAuth="oauth-flag" />
	  </connection>
	</connections>
	<views>
      <view name="view-name" hidden="hide-view-flag" />
	</views>
	<project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string--
      

Attribute Values

boundary-string A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string

workbook-name The name to assign to the workbook when it is saved on the server.
show-tabs-flag (Optional) Specify true to have the published workbook show views in tabs; otherwise, false. The default is false.
user-luid (Optional) The LUID of the user to generate thumbnails as. You can get the user LUID by calling Get Users on Site.
server-address (Optional) Specify the server address for a data source connection if that data source does not use OAuth.
port-number (Optional) Specify the port number for a data source connection if that data source does not use OAuth.
connection-username

(Optional) If the workbook's data source connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection username. If the element is included but is not required (for example, if the data source uses OAuth), the server ignores the element and its attributes.

Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to a data source that requires credentials, unless that data source uses OAuth.

connection-password

(Optional) If the workbook's data source connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection password. If the element is included but is not required (for example, if the data source uses OAuth), the server ignores the element and its attributes.

Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to a data source that requires credentials, unless that data source uses OAuth.

embed-flag (Optional) If the workbook's data source connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to true instructs the server to save the credentials for when the data source is used.
oauth-flag (Optional) If the workbook's data source connection is configured to use OAuth, set this to true to specify that the value of the name attribute in the <connectionCredentials> element is an OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the workbook, and the server address and port number are not required. For more information, see OAuth Connections(Link opens in a new window) in the Tableau Server documentation.
hide-view-flag Setting this flag to true will cause the named view to be hidden in the published workbook. The default value is false. You can specify any number of views to hide. If all views in a workbook are hidden the server will not perform a publish.
project-id The ID of the project to assign the workbook to. If the project is not specified, the workbook will be published to the default project.
workbook-file-name The file name (including extension) of the workbook file to upload. This attribute is used in the request body only if the request also includes the content of the workbook file; it is not used if you are committing a file uploaded using previous requests.
content-of-workbook-file The content of the workbook file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.
encryptExtracts (Optional) true to encrypt the extracts or false to not encrypt extracts. For more information, see Extract and Encryption Methods.

Permissions

Users who are not server administrators or site administrators can publish a workbook only if the workbook belongs to a project that they have permissions to publish to.

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:workbooks:create

Response Code

201

Response Body

<tsResponse>
  <workbook
    id="workbook-id"
	  name="workbook-name"
	  contentUrl="site-content-url"
	  webpageUrl="server-address"
	  showTabs="show-tabs-flag"
	  size="num-size"
	  createdAt="workbook-publish-date-time"
	  updatedAt="workbook-update-date-time"
	  encryptExtracts="encryptExtracts" >
 	    <project id="project-id" name="project-name"/>
	    <owner id="workbook-owner-id"/>
	    <tags/>
	    <views>
	      <view
	        id="view-id"
	     	name="view-name"
	        contentUrl="view-content-url"
	        createdAt="view-publish-date-time"
	        updatedAt="view-update-date-time" >
	          <tags/>
	 	  </view>
	  <materializedViewsEnablementConfig materializedViewsEnabled="materialized-views-enabled-flag"/>
  </workbook>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Headers

Location: /api/3.22/sites/site-id/workbooks/workbook-id

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Malformed request body The XML content in the MIME multipart request is not empty.
400 400000 Missing workbook There is no attachment in the request and no uploadSessionID parameter.
400 400000 Unexpected attachments The message had both an uploadSessionId parameter and an attachment, or the request body contained more than one attachment.
400 400008 Invalid embed value The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false.
400 400008 Invalid overwrite value The overwrite parameter must be true or false.
400 400011 Publishing error The workbook could not be published for some other reason than those specified earlier.
400 400020 Invalid workbook file name The name of the workbook doesn't end in .twb or .twbx.
400 400035 Missing or invalid file type The request included an uploadSessionId parameter but no file type, or the file type was something other than .twb or .twbx.
403 403007 Insufficient publishing permission A non-administrator user attempted to publish a workbook, but the caller doesn't have sufficient project permissions.
403 403007 Unlicensed publishing forbidden A non-administrator user attempted to publish a workbook. This is disallowed for all projects (including the default project).
403 403007 Overwrite forbidden A workbook with the specified name already exists and the overwrite parameter was not set to true.
403 403007 Problem connecting to data source There was a problem connecting to a data source used by the workbook. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server.
403 403008 Insufficient storage quota The workbook could not be published because there is not enough storage remaining on the server to accommodate its size.
403 403130 Publishing overwrite A workbook with the same name already exists.
403 403131 Concurrent update The workbook is already being published in another process.
403 403132 Failed connection check One or more data sources used by the workbook could not be reached.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404006 Workbook not found The user specified overwrite as true but no workbook with the specified name exists on the site.
404 404015 File upload not found The file upload session ID in the uploadSessionId parameter doesn't correspond to an existing file upload on the site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY_SERVER/api/3.4/sites/ff2a8360-3c2b-4b05-a793-7607c602e1fb/workbooks" -X POST -H "X-Tableau-Auth:7T_33sOfS8Ks_0cht4tYxw|8tsTYQyyOZXfOgxZEHWQ4jUTCQ08GhRr" -H "Content-Type: multipart/mixed;" -F "request_payload=@publish-workbook.xml" -F "tableau_workbook=@MY_WORKBOOK.twbx"

Content of publish-workbook.xml (publish the Test1 workbook, hide the Test Sheet 1 view):

<tsRequest>
	<workbook name="test1" showTabs="true" >
	<project id=""/>
	<views>
	<view name="Test Sheet 1" hidden="true" />
	</views>
	</workbook>
</tsRequest>

Example response:

<tsResponse>
	<workbook
		id="1e40f015-ac41-4377-8238-544f70d36150"
		name="test1" contentUrl="test1"
		webpageUrl="http://MY_SERVER/#/workbooks/3"
		showTabs="true"
		size="1"
		createdAt="2019-04-03T21:24:58Z"
		updatedAt="2019-04-03T21:25:02Z"
		encryptExtracts="false">
		  <project id="e6e94e18-349f-11e9-a794-13e5e0f21c22" name="Default"/>
		  <owner id="1473347e-b0c6-4f1f-bcac-7927ee1a690e"/>
	 	  <tags/>
		  <views>
			<view
			  id="0f0d33ac-027d-42a7-94bf-4f0b13e07652"
			  name="Sheet 1"
			  contentUrl="test1/sheets/Sheet1"
			  createdAt="2019-04-03T21:25:02Z"
		      updatedAt="2019-04-03T21:25:02Z">
			  <tags/>
			</view>
		 <materializedViewsEnablementConfig materializedViewsEnabled="false"/>
	</workbook>
</tsResponse>

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

URI

GET /api/api-version/sites/site-id/datasources/datasource-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The site that contains the data source.
datasource-id The ID of the data source to get.

Request Body

None

Permissions

Users who are not server administrators or site administrators can view a data source only if they have Connect permission for the data source (either explicitly or implicitly).

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:content:read

Response Code

200

Response Body

<tsResponse>
  <datasource id="datasource-id"
	certificationNote="certification-note"
	name="datasource-name"
	description="data-source-description"
	type="datasource-type"
    contentUrl="datasource-content-url"
    createdAt="datetime-created"
    updatedAt="datetime-updated"
    encryptExtracts="encryptExtracts"
	hasExtracts="has-extracts-flag"
 	isCertified="is-certified-flag"
	useRemoteQueryAgent="use-remote-query-agent-flag"
	webpageUrl="web-page-url" >
      <project id="project-id" name="project-name" />
      <owner id="datasource-owner-id"  />
      <tags>
        <tag label="tag"/>
        ... additional tags ...
      </tags>
      <askData enablement="enablement-setting"/>
  </datasource>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query a data source, but the caller doesn't have Connect 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 ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" name="Activity rates and healthy living"
    certificationNote="This is a note about the datasource certification."
	contentUrl="activity-dates-and-healthy-living"
	encryptExtracts="true"
	description="The Activity and Health data source."
	isCertified="true"
	type="excel-direct"
	createdAt="2011-03-30T22:32:35Z"
	updatedAt="2016-01-13T01:00:02Z">
	useRemoteQueryAgent="false"
	webpageUrl="https://MYSERVER/#/datasources/4414"
      <project id="1f2f3e4e5-d6d7-c8c9-b0b1-a2a3f4f5e6e" name="default"/>
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
      <tags>
      </tags>
	  <askData enablement="Enabled"/>
  </datasource>
</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.

Query Data Source Connections

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

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/connections

Parameter Values

api-version The version of the API to use, such as 3.22. 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 return connection information about.

Request Body

None

Permissions

Users who are not server administrators or site administrators can query a data source only if they have Read (view) permission for the data source (either explicitly or implicitly). queryTaggingEnabled is returned only for administrator users.

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:content:read

Response Code

200

Response Body

<tsResponse>
  <connections>
    <connection id="connection-id" type="connection-type"
      serverAddress="server-address" serverPort="port"
	  userName="connection-user-name"
	  queryTaggingEnabled="query-tagging-enabled" />
	< ... additional connections ... >
  </connections>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
403 403021 Read forbidden A user who is not a server administrator user attempted to query the data source connections, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404011 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 GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <connections>
    <connection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" type="dataengine" />
    <connection id="374371c0-ffe9-4e16-b48e-6b868e3026ca" type="dataengine" />
    <connection id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" type="dataengine" />
  </connections>
</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.

Query Data Source Permissions

Returns a list of permissions for a specific data source.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. 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 get permissions for.

Request Body

None

Permissions

Users who are not server administrators or site administrators can view a data source only if they have Read (view) permission for the data source (either explicitly or implicitly).

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:permissions:read

Response Code

200

Response Body

<tsResponse>
  <permissions>
   <parent type="Project" id="project-id"
   <datasource id="datasource-id"
     owner="owner-user-id" />
   <granteeCapabilities>
     <user id="user-id" />
     <capabilities>
       <capability name="capability-name" mode="capability-mode" />
       ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
        ... additional capabilities ...
       </capabilities>
     </granteeCapabilities>
     ... additional grantee capability sets ...
  </permissions>
</tsResponse>
        

Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are 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).

Version

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

Errors

HTTP status error Code Condition Details
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 GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <parent type="Project" id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
  <permissions>
    <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" name="USPS-rates">
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    </datasource>
    <granteeCapabilities>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" />
      <capabilities>
        <capability name="Connect" mode="Allow"/>
        <capability name="Read" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

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.

URI

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

GET /api/api-version/sites/site-id/datasources?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/datasources?filter=filter-expression

GET /api/api-version/sites/site-id/datasources?sort=sort-expression

GET /api/api-version/sites/site-id/datasources?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data sources.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name and updatedAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the data sources or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the Rest API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can view a data source only if they have Connect permission for the data source (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
    totalAvailable="total-available" />
  <datasources>
    <datasource id="datasource1-id"
      description="data-source-description"
      name="datasource-name"
      size="datasource-size"
      type="datasource-type"
      contentUrl="datasource-content-url"
      createdAt="datetime-created"
      updatedAt="datetime-updated"
      encryptExtracts="encrypt-extracts-flag"
      hasExtracts="has-extracts-flag"
      isCertified="is-certified-flag"
      useRemoteQueryAgent="use-remote-query-agent-flag"
      webpageUrl="datasource-webpage-url"  >
	    <project id="project-id" name="project-name" />
        <owner id="datasource-owner-id" />
        <tags>
          <tag label="tag"/>
          ... additional tags ...
        </tags>
    </datasource>
    ... additional data sources ...
  </datasources>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
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.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <datasources>
    <datasource id="1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b"
      name="Sample - Coffee Chain (Access)"
	  contentUrl="coffee-chain"
	  description="The Sample - Coffee Chain data source."
	  type="msaccess"
	  createdAt="2011-03-30T22:32:35Z"
	  updatedAt="2016-01-13T01:00:02Z"
	  encryptExtracts="false"
	  isCertified="false"
      useRemoteQueryAgent="false"
      webpageUrl="https://my-server.com/#/site/my-site/datasources/1275708" >
        <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Default"/>
        <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
        <tags>
	  	  <tag label="test"/>
        </tags>
    </datasource>
  </datasources>
</tsResponse>

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

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

Query Default Permissions

Returns details of default permission rules granted to users and groups for workbook, data source, data role, lens, flow, or metric 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.

URI

GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks

GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources

GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles

GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses

GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows

GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics

GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases

GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the project.
project-luid The LUID of the project to get default permissions for.

Request Body

None

Permissions

Users who are not server administrators can query default permissions for a project only if they have the ProjectLeader permission for that project (either explicitly or implicitly).

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.

Note: The following scope applies to data sources, workbooks, and metrics only.

tableau:permissions:read

Response Code

200

Response Body

<tsResponse>
  <permissions>
	<project id="project-luid" name="project-name" />
	<granteeCapabilities>
      <user id="user-luid" />
	  <capabilities>
	    <capability name="capability" mode="capability-mode" />
	    <capability name="capability" mode="capability-mode" />
	    <... additional capabilities ...>
	  </capabilities>
	</granteeCapabilities>
	<... additional grantee capabilities ...>
  </permissions>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
403 403035 Querying data source permissions forbidden The caller doesn't have permissions to query the project's default permissions for data sources.
403 403036 Querying workbook permissions forbidden The caller doesn't have permissions to query the project's default permissions for workbooks.
403 403035 Querying flow permissions forbidden The caller doesn't have permissions to query the project's default permissions for flows.
404 404000 Site not found The site LUID in the URI doesn't correspond to an existing site.
404 404005 Project not found The project LUID in the URI doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

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.

URI

GET /api/api-version/sites/site-id/flows/flow-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-id The ID of the flow to return information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a flow only if they have Read(view) permission for the flow (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
   <flowOutputSteps>
     <flowOutputStep id = "flow-output-step id"
      name = "flow-name">
        ...additional output steps...
    </flowOutputSteps>
    <flow id = "flow-id">
      <project id = "project-id">
      <owner id = "owner-id">
      <tags/>
      <parameters>
	 <parameter id="parameter-id" type="data type" name="parameter name" description=" parameter description" value="current value" isRequired="true/false">
	   <domain xsi:type="flowParameterDomainType" domainType="domain type">
	   </domain>
        <parameter>
	 ...additional parameters...
      <parameters>
    </flow>
</tsResponse>
        

Note: Parameters is only shown in the response if parameters are enabled on the site and the flow contains parameters.

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query the flow, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not GET.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/ d00700fe-28a0-4ece-a7af-5543ddf38a82" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
    <flowOutputSteps>
        <flowOutputStep id="5e4c9a74-d29a-4f62-baa5-97c443440dfc" name="CoffeeChainOutputCSV"/>
        <flowOutputStep id="baa85bce-6aab-434a-8070-72625ded8cb6" name="CoffeeChainOutputHyper"/>
        <flowOutputStep id="2f5da1ba-4a40-44a4-9201-7db6ce089811" name="CoffeeChainOutputTDE"/>
    </flowOutputSteps>
    <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good" description="" webpageUrl="http://tpqawin01/#/flows/3" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z">
        <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
        <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	 <tags/>
	<parameters>
		<parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String test parameter" value="string 2" isRequired="false">
		  <domain xsi:type="flowParameterListDomainType" domainType="all">
		</parameter>
	</parameters>
    </flow>
</tsResponse>  

Query Flow Connections

Returns a list of data connections for the specific flow.

URI

GET /api/api-version/sites/site-id/flows/flow-id/connections

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-id The ID of the flow to return connection information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a flow only if they have Read(view) permission for the flow (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse >
    <connections>
        <connection id="connection-id"
           type="connection-type"
           serverAddress="server-address"
           userName="user-name"
           embedPassword="true-or-false"/>
        ... additional connections ...
    </connections>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
403 403092 Read forbidden A user who is not a server administrator user attempted to query the flow connections, but the caller doesn't have Readpermission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
    <connections>
        <connection id="5fd1c1db-572f-4ebd-94e7-a09e212bc147" type="sqlserver" serverAddress="mySQLServer" userName="test" embedPassword="true"/>
        <connection id="ed358ca5-f25b-43b4-8791-2dbf34631df6" type="tableau-server-site" serverAddress="http://testserver01" userName="" embedPassword="false"/>
       </connections>
</tsResponse>
        

Query Flow Permissions

Returns a list of permissions for the specific flow.

URI

GET /api/api-version/sites/site-id/flows/flow-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-id The ID of the flow to get permissions for.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse >
    <permissions>
        <flow id="flow-id" name="flow-name">
            <owner id="owner-id"/>
        </flow>
        <granteeCapabilities>
            <group id="group-id"/>
            <capabilities>
                <capability name="Read" mode="Allow"/>
                <capability name="Write" mode="Allow"/>
                ... additional capabilities ...
            </capabilities>
        </granteeCapabilities>
    </permissions>
</tsResponse>
        

Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project(Link opens in a new window) or for an existing project by calling Update Project(Link opens in a new window). For more information, see Lock Content Permissions to the Project(Link opens in a new window).

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse xmlns= version-and-namespace-settings>
    <permissions>
        <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good">
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
        </flow>
        <granteeCapabilities>
            <group id="6fd1dea0-e173-11e8-ae75-832f6a4756f0"/>
            <capabilities>
                <capability name="Read" mode="Allow"/>
                <capability name="Write" mode="Allow"/>
            </capabilities>
        </granteeCapabilities>
    </permissions>
</tsResponse>
        

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.

URI

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

GET /api/api-version/sites/site-id/flows?filter=filter-expression

GET /api/api-version/sites/site-id/flows?sort=sort-expression

GET /api/api-version/sites/site-id/flows?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flows.
filter-expression (Optional) An expression that lets you specify a subset of flows to return. You can filter on predefined fields such as name, tags, and createdAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which flow information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Note: The filter and sort parameters can be combined with each other and with paging parameters using an ampersand (&).

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can get flows that they have Read (view) permissions for (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="page-number"
    pageSize="page-size"
    totalAvailable="total-available"/>
     <flows>
       <flow id="flow-id"
        name="flow-name"
        description="flow-description"
        webpageUrl="web-page-url"
        fileType="file-type"
        createdAt="datetime-created"
        updatedAt="datetime-updated">
         <project id="project-id" name="project-name"/>
         <owner id="owner-id"/>
	  <tags/>
	  <parameters>
           <parameter id="parameter-id" type="data type" name="parameter name" description="parameter description" value="current value" isRequired="false">
	      <domain xsi:type="flowParameterListDomainType" domainType="all">
	      </domain>
	      </parameter>
	    <parameters>
         </flow>
        ... additional flows ...
     </flows>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403101 Read forbidden A non-administrator user attempted to query flows for the site, but the caller doesn't have Read permission.
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.

Example

curl "http://MY-SERVER/api/3.22/sites/9954070a-581d-40fa-ae73-e815ce8b0562/flows" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="7"/> <flows> <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good" description="" webpageUrl="http://tpqawin01/#/flows/3" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters/> </flow> <flow id="c1e82fe3-e7cf-4bd5-afd3-799b1e8aac27" name="broken_loom_doc_2" description="" webpageUrl="http://tpqawin01/#/flows/26" fileType="tflx" createdAt="2018-11-06T18:19:54Z" updatedAt="2018-11-06T18:19:54Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters> <parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String parameter test" value="string 2" isRequired="false"> <domain xsi:type="flowParameterListDomainType" domainType="all"> </parameter> </parameters> </flow> <flow id="d4eccc71-5cbd-4753-a807-d3ea9256aee1" name="Partner Influence" description="configured by ibeekun" webpageUrl="http://tpqawin01/#/flows/34" fileType="tflx" createdAt="2018-11-06T22:46:57Z" updatedAt="2018-11-06T22:46:57Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters/> </flow> <flow id="82aefd39-ae37-4ad8-a44c-391563f12e18" name="Omniture logs" description="configured by testuser" webpageUrl="http://mytestServer/#/flows/35" fileType="tflx" createdAt="2018-11-06T22:47:18Z" updatedAt="2018-11-06T22:47:18Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags> <parameters/> </flow> <flow id="b527d896-b71e-4953-b085-2afecccea427" name="NY Parking Tickets" description="configured by ibeekun" webpageUrl="http://tpqawin01/#/flows/37" fileType="tflx" createdAt="2018-11-07T00:19:48Z" updatedAt="2018-11-07T00:19:48Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters/> </flow> <flow id="ddcd4f53-76b6-4af7-a050-fe3eef702317" name="Flow1" description="" webpageUrl="http://tpqawin01/#/flows/40" fileType="tfl" createdAt="2018-11-07T00:38:48Z" updatedAt="2018-11-07T00:38:48Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> </flow> <flow id="868eab1a-2b60-448a-9913-82e4522ab952" name="local-postgres-bad-pw" description="" webpageUrl="http://tpqawin01/#/flows/78" fileType="tflx" createdAt="2018-11-07T22:18:04Z" updatedAt="2018-11-07T22:18:04Z"> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> <tags/> <parameters/> </flow> </flows> </tsResponse>

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.

URI

GET /api/api-version/sites/site-id/users/user-id/flows

GET /api/api-version/sites/site-id/users/user-id/flows?ownedBy=isOwner&pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to get flows for.
isOwner (Optional) trueto return only flows that the specified user owns, or falseto return all flows that the specified user has at least read access to. The default is false.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

All users can call this method, but the results of the call depend on the user's permissions. Server and site administrators see all flows for the specified user. If the isOwnerparameter is true, users who are not server or site administrators see the flows that they own on the site. If isOwnerparameter is false, users who are not server administrators see the flows that they have Read (view) permissions for.

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="page-number"
    pageSize="page-size"
    totalAvailable="total-available"/>
    <flows>
      <flow id="flow-id"
       name="flow-name" description="flow-description"
       webpageUrl="URL"
       fileType="flow-file-type"
       createdAt="Datetime-created"
       updatedAt="Datetime-updated">
        <project id="project-id" name="project-name"/>
        <owner id="owner-id"/>
	 <tags/>
	 <parameters>
          <parameter id="parameter-id" type="data type" name="parameter name" description="parameter description" value="current value" isRequired="false">
            <domain xsi:type="flowParameterListDomainType" domainType="all">
	     </domain>
	   </parameter>
	 <parameters>
      </flow>
        ... additional flows...
    </flows>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

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 flows at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size exceeds upper limit The page size parameter exceeds the system-wide upper limit of 1000.
403 403101 Read forbidden A non-administrator user attempted to query flows for the user, but the caller doesn't have Read permission.
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 GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/flows" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
    <pagination pageNumber="1" pageSize="100" totalAvailable="41"/>
    <flows>
        <flow id="00795e57-0c0b-43c9-843f-6635d6577dec" name="several_excel_input_union2" description="" webpageUrl="http://tpqawin01/#/flows/263" fileType="tflx" createdAt="2018-11-09T20:01:04Z" updatedAt="2018-11-09T20:01:04Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="303379e9-3b66-419c-a022-7179bc13892c"/>
        </flow>
        <flow id="467242c7-3d5a-4ba8-b4c3-58b5aecc084d" name="Superstore_Test_ER" description="testing direct connection" webpageUrl="http://tpqawin01/#/flows/124" fileType="tfl" createdAt="2018-11-08T21:30:44Z" updatedAt="2018-11-08T21:30:44Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	     <tags/>
	     <parameters>
		<parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String parameter test" value="string 2" isRequired="false">
		  <domain xsi:type="flowParameterListDomainType" domainType="all">
		</parameter>
	     </parameters>
        </flow>
   </flows>
</tsResponse>

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

Version: Available in API 3.22 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:read     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

GET /api/api-version/sites/site-id/groupsets&[resultlevel=[members,local]

GET /api/api-version/sites/site-id/groupsets?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/groupsets?filter=filter-expression

GET /api/api-version/sites/site-id/groupsets?sort=sort-expression

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group sets.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of group sets to return. You can filter on predefined fields such as name. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which group set information is returned. If you don’t specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.

Request Body

None

cURL Request Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets&[resultlevel=[members,local]]" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy
<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="3"/>
  <groupSets>
    <groupSet id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="All Users" groupCount="1">
      <group id="gs-1" name="group-one"/>
    </groupSet>
    <groupSet id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="active-directory-group-import">
      <group id="gs21" name="group-two"
    </groupSet>
    <groupSet id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="local-group-license-on-login">
      <group id="gs-3" name="group-three"
    </groupSet>
  </groupSets>
</tsResponse>
Copy
{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "3"
  },
  "groupSets": [
    {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "All Users",
      "groupCount": "1",
      "group": {
        "id": "gs-1",
        "name": "group-one"
      }
    },
    {
      "id": "9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b",
      "name": "active-directory-group-import",
      "group": {
        "id": "gs21",
        "name": "group-two"
      }
    },
    {
      "id": "7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6",
      "name": "local-group-license-on-login",
      "group": {
        "id": "gs-3",
        "name": "group-three"
      }
    }
  ]
}

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter isn’t an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter isn’t an integer, or is less than one.
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 The request type wasn’t GET.
409 409120 Group set not found The group set ID in the URI doesn't correspond with an existing group set.

For more information, see Handling Errors.

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.

URI

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

GET /api/api-version/sites/site-id/groups?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/groups?filter=filter-expression

GET /api/api-version/sites/site-id/groups?sort=sort-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the groups.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of groups to return. You can filter on predefined fields such as name. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.

Request Body

None

Permissions

This method can only be called by server administrators and site 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:groups:read

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
  <groups>
    <group id="group-id"
      name="group-name">
        <domain name="domain-for-group" />
    </group>
    <group id="group-id"
      name="group-name">
        <domain name="domain-for-group" />
		<import source="import-source"
		  domainName="active-directory-domain-name"
		  siteRole="minimum-site-role"
		  grantLicenseMode="license-mode" />
    </group>
    ... additional groups ...
  </groups>
</tsResponse>
        

If the group was imported from Active Directory, the name attribute of the <domain> element contains the group's Active Directory domain. For a group that uses local authentication, the value of that attribute is local.

The response body for a local group that has enabled onLogin for its grant license mode will have an import element with a domain name of local. Local groups with grant license mode unset, have no import element in their response.

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
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.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X GET -H "X-Tableau-Auth:e35Z608JMPHgZfVyJncnedlUeXSX8bmb"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="3"/>
  <groups>
    <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="All Users">
      <domain name="local"/>
    </group>
    <group id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="active-directory-group-import">
      <domain name="MYDOMAIN.net"/>
	  <import domainName="MYDOMAIN.net" siteRole="ExplorerCanPublish" grantLicenseMode="onLogin"/>
    </group>
    <group id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="local-group-license-on-login">
      <domain name="local"/>
      <import domainName="local" siteRole="ExplorerCanPublish" grantLicenseMode="onLogin"/>
    </group>
  </groups>
</tsResponse>

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:

URI

GET /api/api-version/sites/site-id/jobs/job-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site where the job is running.
job-id The ID of the job to get status information for.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
    <job id="job-id"
     mode="job-mode"
     type="job-type"
     progress="percent-completed"
     createdAt="time-job-created"
     updatedAt="time-job-last-updated"
     completedAt="time-job-completed"
     finishCode="status-code">
        <extractRefreshJob>
            <notes> ... view, workbook, or datasource id and name ... </notes>
        </extractRefreshJob>
        <statusNotes>
            <statusNote type="classifier"
             value="value"
             text="note" /> ... additional job notes ...
        </statusNotes>
    </job>
</tsResponse> 

The createdAt, updatedAt, and CompletedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Note: When using this method to query the progress of asynchronous workbook publishing, progress will switch from 0 when the job is in-progress to 100 when it is complete, finishCode will switch from 1 when the job is in-progress to 0 when it is complete, and no <statusNotes> elements are provided.

The finishCode indicates the status of the job: 0 for success, 1 for error, or 2 for canceled.

The <statusNotes> element contains one or more notes that provide details about the status of a job in a format that can be used for logging, auditing, and error recovery. Each status note contains three attributes:

  • type. An enumerated value (a string) that indicates the classification of the note.
  • value. A value that indicates the number of records reported by the current status, such as the count of records processed.
  • text. A description of the status that can be displayed to users. If you are working with a localized (translated) version of Tableau Server, this text is also localized. You should not rely on this text for any application logic. If you need to take action based on a specific status, test the value of the type attribute.

The following table lists job status types. Some values are returned only when the job is synchronizing groups (Update Group).

Type Value Text
CountOfUsersAddedToGroup Integer Description of how many users were added to the group during the import.
CountOfUsersAddedToSite Integer Description of how many users were added to the site during the import.
CountOfUsersWithInsufficientLicenses Integer Description of how many users could not have their site role updated due to server lacking sufficient licenses for them.
CountOfUsersInActiveDirectoryGroup Integer Description of the total number of users in the Active Directory group being imported or synchronized
CountOfUsersProcessed Integer Description of the total number of users processed during the import or synchronization process.
CountOfUsersSkipped Integer Description of the total number of users skipped during the import or synchronization process
CountOfUsersInformationUpdated Integer Description of the total number of users whose information was updated during the import or synchronization process.
CountOfUsersSiteRoleUpdated Integer Description of the total number of users whose site role was updated during the import or synchronization process.
CountOfUsersRemovedFromGroup Integer (Synchronization process only) Description of the number of users removed from the group during the synchronization process.
CountOfUsersUnlicensed Integer (Synchronization process only) Description of the number of users who were unlicensed during the synchronization process.
SiteDelete Integer Description of the site deletion progress. Can include a general error or errorCode=9 when a site can't be deleted.

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404018 Job not found The job ID in the URI doesn't correspond to an existing job.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

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.

URI

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

GET /api/api-version/sites/site-id/jobs?filter=progress:lte:0

GET /api/api-version/sites/site-id/jobs?filter=jobType:eq:refresh_extracts

GET /api/api-version/sites/site-id/jobs?filter=createdAt:gt:2018-04-18T11:00:56z

GET /api/api-version/sites/site-id/jobs?filter=title:has:Superstore

GET /api/api-version/sites/site-id/jobs?filter=notes:has:nightly

GET /api/api-version/sites/site-id/jobs?filter=jobType:eq:run_flow

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site where the job is running.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="page-number" pageSize="page-size"/>
  <backgroundJobs>
    <backgroundJob id="job-id" status="status-value" createdAt="date-time" startedAt="date-time" endedAt="date-time" priority="priority-value" jobType="type-value"/>
	<!-- . . . more backgroundJobs . . . -->
  </backgroundJobs>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
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.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/jobs" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="48999"/>
  <backgroundJobs>
	<backgroundJob id="919055e5-25db-4a2b-9611-1408dd06632d" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:15Z" endedAt="2018-04-17T23:00:15Z" priority="50" jobType="increment_extracts"/>
	<backgroundJob id="b5cadda9-2b32-447a-acb6-1c1b8c06caf9" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:15Z" endedAt="2018-04-17T23:00:15Z" priority="50" jobType="increment_extracts"/>
	<backgroundJob id="d281297b-9834-44a1-b71a-a2cab6060df6" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:24Z" endedAt="2018-04-17T23:00:32Z" priority="50" jobType="refresh_extracts"/>
  </backgroundJobs>
</tsResponse>

Query Project Permissions

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

URI

GET /api/api-version/sites/site-id/projects/project-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
project-id The project to get permissions for.

Request Body

None

Permissions

This method can only be called by server administrators and site 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:permissions:read

Response Code

200

Response Body

<tsResponse>
  <permissions>
    <project id="project-id" name="project-name" />
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
        <capability name="capability" mode="capability-mode" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capabilities ...
  </permissions>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <permissions>
    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="default">
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    </project>
    <granteeCapabilities>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"/>
      <capabilities>
        <capability name="Read" mode="Allow"/>
        <capability name="Write" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

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.

URI

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

GET /api/api-version/sites/site-id/projects?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/projects?filter=filter-expression

GET /api/api-version/sites/site-id/projects?sort=sort-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the projects.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name, ownerName, and parentProjectId. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.

Request Body

None

Permissions

Users who are not server administrators or site administrators can call this method only if they have Read (view) permission for the project (either implicitly or explicitly).

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:content:read

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
    pageSize="page-size"
    totalAvailable="total-available" />
  <projects>
    <project id="project-id"
      name="project-name"
      description="project-description"
      topLevelProject="top-level-project-flag"
      writeable="writeable-flag"
      controllingPermissionsProjectId="controlling-permissions-project-id"
      createdAt="created-date-and-time"
      updatedAt="updated-date-and-time"
      contentPermissions="content-permissions"
      parentProjectId="parent-project-id">
        <owner email="owner-email"
          fullName="owner-full-name"
          id="owner-id"
          lastLogin="owner-last-login-date"
          name="owner-username"
          siteRole="owner-site-role"/>
        <contentCounts projectCount="number-of-projects"
          workbookCount="number-of-workbooks"
          viewCount="number-of-views"
          datasourceCount="number-of-data-sources"/>
    </project>
    <project id="project-id"
      name="project-name"
      description="project-description"
	  contentPermissions="content-permissions"
	  controllingPermissionsProjectId="controlling-permissions-project-id" />
	... additional attributes and projects ...
  </projects>
</tsResponse>
        

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
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.

Example: Filter query by project ID

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?filter=parentProjectId:eq:711d4c5d-60b7-4f77-a9a6-bbf05021b6ec" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
	<pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
    <projects>
        <project id="fae56e51-fbee-4eab-a9af-d8283cc0ed77" name="TestNestProject" description="" createdAt="2018-11-15T17:14:45Z" updatedAt="2018-11-15T17:14:45Z" contentPermissions="LockedToProject" parentProjectId="711d4c5d-60b7-4f77-a9a6-bbf05021b6ec">
            <owner id="4d8308f7-ec47-4eb1-a383-429374a8d9cb"/>
        </project>
    </projects>
</tsResponse>

Example: Show all fields in the first ten query results

curl "https://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?pageSize=10&fields=_all_" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
    <pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
    <projects>
        <project id="fae56e51-fbee-4eab-a9af-d8283cc0ed77"
            name="TestNestProject"
            description="A project."
            topLevelProject="false"
            writeable="true"
            createdAt="2018-11-15T17:14:45Z"
            updatedAt="2018-13-15T17:12:30Z"
            contentPermissions="ManagedByOwner"
            parentProjectId="711d4c5d-60b7-4f77-a9a6-bbf05021b6ec"
            controllingPermissionsProjectId="57646e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
        <owner id="4d8308f7-ec47-4eb1-a383-429374a8d9cb" email="rkawal@tableau.com" fullName="Reena Kawal" lastLogin="2020-06-02T16:23:49Z" name="rkawal" siteRole="SiteAdministratorCreator"/>
        <contentCounts projectCount="2" workbookCount="3" viewCount="10" datasourceCount="2" />
        </project>
    </projects>
</tsResponse>

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

URI

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

GET /api/api-version/sites/site-name?key=name

GET /api/api-version/sites/content-url?key=contentUrl

GET /api/api-version/sites/site-id?includeUsage=include-usage-flag

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site to get information for.
site-name The name of the site to get information for. If you specify a site name, you must also include the parameter key=name.
content-url The URL of the site to get information for. If you specify a content URL, you must also include the parameter key=contentUrl.
include-usage-flag The boolean flag to include site usage metrics in the response body. If true, then the site element of the response will contain a usage node with the attributes numUsers (number of users) and storage (storage in megabytes).

To set the flag to include usage in the response, append includeUsage=true as a querystring element any valid query site URI.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <site id="site-id"
	name="site-name"
	contentUrl="content-url"
	adminMode="admin-mode"
	disableSubscriptions="new-disable-subscriptions"
	state="active-or-suspended
	revisionHistoryEnabled="revision-history-enabled-flag"
	revisionLimit="revision-limit"
	subscribeOthersEnabled="subscribe-others-enabled-flag"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	userQuota="num-users"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	commentingEnabled="commenting-enabled-flag"
	storageQuota="limit-in-megabytes"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	extractEncryptionMode="encryption-mode"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	requestAccessEnabled="request-access-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	usage numUsers="number-of-users"
	storage="storage-in-megabytes"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	isDataAlertsEnabled="data-alerts-enabled-flag"
    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"/>
  </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.
  • attributeCaptureEnabled attribute is only present in the response body for Tableau Cloud starting from API version 3.19 (March 2023).

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

Command:

curl "http://MY-SERVER/api/3.22/sites/1234abcd-12ab-12ab-12ab-1234abcd1234?includeUsage=true" -X GET \
-H "X-Tableau-Auth:ABCD1234abcdABCD|ABCD1234abcdABCDABCD1234abcd-1"

Example response:

<tsResponse>
  <site id="1234abcd-12ab-12ab-12ab-1234abcd1234"
    	name="new_site_name"
    	contentUrl="new_site_url"
    	adminMode="ContentAndUsers"
    	storageQuota="100"
    	disableSubscriptions="true"
    	state="Active"
    	revisionHistoryEnabled="true"
    	revisionLimit="25"
    	subscribeOthersEnabled="false"
    	allowSubscriptionAttachments="true"
    	guestAccessEnabled="false"
    	cacheWarmupEnabled="true"
    	commentingEnabled="true"
        editingFlowsEnabled="false"
        schedulingFlowsEnabled="false"
	extractEncryptionMode="enabled"
	catalogingEnabled="true"
    	derivedPermissionsEnabled="false"
    	requestAccessEnabled ="false"
    	runNowEnabled="true"
    	usage numUsers="0" storage="0"
	userQuota="4"
	tierCreatorCapacity="2"
	tierExplorerCapacity="1"
	tierViewerCapacity="1"
    	isDataAlertsEnabled="true"
    	askDataMode="DisabledByDefault"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles"
	explainDataEnabled="true"
	dqwSubscriptionsEnabled="false"
	attributeCaptureEnabled="false" />
  </site>
</tsResponse>
          

Command:

curl "http://MY-SERVER/api/3.22/sites/Default?key=name" -X GET \
-H "X-Tableau-Auth:ABCD1234abcdABCD|ABCD1234abcdABCDABCD1234abcd-1"

Example response:

<tsResponse>
  <site id="1234abcd-12ab-12ab-12ab-1234abcd1234"
	name="new_site_name"
	contentUrl=""
	adminMode="ContentAndUsers"
	storageQuota="100"
	disableSubscriptions="true"
	state="Active"
	revisionHistoryEnabled="true"
	revisionLimit="25"
	subscribeOthersEnabled="false"
    allowSubscriptionAttachments="true"
	guestAccessEnabled="false"
	cacheWarmupEnabled="true"
	commentingEnabled="true"
    editingFlowsEnabled="false"
    schedulingFlowsEnabled="false"
	extractEncryptionMode="enabled"
	catalogingEnabled="true"
	derivedPermissionsEnabled="false"
	requestAccessEnabled ="false"
 	runNowEnabled="true"/>
	userQuota="4"
	tierCreatorCapacity="2"
	tierExplorerCapacity="1"
	tierViewerCapacity="1"
    askDataMode="DisabledByDefault"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles" />
  </site>
</tsResponse>
          

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.

URI

GET /api/api-version/sites

GET /api/api-version/sites?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

This method can be called by all users. The method only returns the sites that the user has access to.

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:sites:read

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber"
	pageSize="page-size"
	totalAvailable="total-available" />
  <sites>
	<site id="site-id"
	  name="site-name"
	  contentUrl="content-url"
	  adminMode="admin-mode"
	  disableSubscriptions="disable-subscriptions-flag"
	  userQuota="num-users"
	  storageQuota="limit-in-megabytes"
	  state="active-or-suspended"
	  statusReason="reason-for-state"
	  revisionHistoryEnabled="revision-history-flag"
	  revisionLimit="num-revisions"
	  subscribeOthersEnabled="subscribe-others-flag"
      allowSubscriptionAttachments="allow-subcription-attachments-flag"
	  guestAccessEnabled="guest-access-enabled-flag"
	  cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	  commentingEnabled="enable-commenting-flag"
      editingFlowsEnabled="editing-flows-enabled-flag"
      schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	  extractEncryptionMode="extract-encryption-mode"
	  catalogingEnabled="enable-cataloging-flag"
	  derivedPermissionsEnabled="derived-permissions-enabled-flag
	  requestAccessEnabled ="false"
	  runNowEnabled="true"
	  isDataAlertsEnabled="data-alerts-enabled-flag"
	  askDataMode="ask-data-mode"
	useDefaultTimeZone="default-time-zone-flag"
	  timeZone="time-zone"
	  explainDataEnabled="explain-data-enabled"
	  dqwSubscriptionsEnabled="dqw-subscriptions-enabled" />
	<!--   ... additional sites ... -->
  </sites>
</tsResponse>
        

The response for users without administrative permissions contains only the site id, name, and content-url attributes.

Version

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

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 the sites at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites?pageSize=1&pageNumber=1" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <pagination pageNumber="1"
    pageSize="1"
    totalAvailable="2"/>
  <sites>
    <site id="abcd1234-ab12-ab12-ab12-abcd1234abcd"
    name="Default"
    contentUrl=""
	adminMode="ContentAndUsers"
	disableSubscriptions="true"
	state="Active"
    revisionHistoryEnabled="true"
	revisionLimit="25"
	subscribeOthersEnabled="false"
	allowSubscriptionAttachments="true"
	guestAccessEnabled="true"
	cacheWarmupEnabled="true" [REMOVED IN API 3.19]
	commentingEnabled="true"
    editingFlowsEnabled="false"
    schedulingFlowsEnabled="false"
	extractEncryptionMode="enabled"
	catalogingEnabled="true"
	derivedPermissionsEnabled="false"
	requestAccessEnabled ="false"
    runNowEnabled="true"
	isDataAlertsEnabled="true"
	askDataMode="DisabledByDefault"
	useDefaultTimeZone="false"
	timeZone="America/Los_Angeles"
	explainDataEnabled="true"
	dqwSubscriptionsEnabled="false" />
  </sites>
</tsResponse>
        

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

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

URI

GET /api/api-version/sites/site-id/users/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to get information for.

Request Body

None

Permissions

Using this method server administrators and site administrators can view user information directly or through the various ways that data is used throughout Tableau. Use of this method by non-administrator users to view their own information depends on the visibility settings of a site. Using the Visibility Setting in the server UI, or the Create Site or Update Site methods, you can change user visibility settings of a Site. For more information, see Manage Site User Visibility(Link opens in a new window).

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:users:read

Response Code

200

Response Body

<tsResponse>
  <user id="user-id"
        name="user-name"
        siteRole="site-role"
        lastLogin="last-login-date"
        externalAuthUserId="authentication-id-from-external-provider"
		fullName="user-full-name"
		authSetting="auth-setting"
		language="language-code"
        locale="locale-code" />
  <domain name="user-domain" />
</tsResponse>
        

The lastLogin attribute value is returned as a date in UTC format (YYYY-MM-DDTHH:MM:SSZ).

The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.

The externalAuthUserId value represents an ID for the user for single sign-on (SSO) with an external identity provider. If the user is not configured to use external authentication, this value is an empty string.

(Tableau Server version 9.0.1/schema version 2.0.1 and later). If SAML is enabled, and the user was imported from Active Directory, the name attribute of the <domain> element contains the user's Active Directory domain.

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
403 403133 Query user permissions forbidden The user does not have permissions to query user information for other users.
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 GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" name="Alan"
    siteRole="ExplorerCanPublish"
    fullName="Alan Wang"
    authSetting="ServerDefault"
    lastLogin="2015-01-05T03:24:36Z"
	language="en-GB"
	locale="GB" />
</tsResponse>

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.

URI

GET /api/api-version/sites/site-id/views/view-id/data

GET /api/api-version/sites/site-id/views/view-id/data?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/views/view-id/data?vf_<fieldname>=filter-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
view-id The ID of the view to render as data.
max-age-minutes (Optional) The maximum number of minutes view data will be cached before being refreshed. To prevent multiple view data requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
filter-value The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter /data?vf_year=2017 would only display data from the year 2017. To learn more, see View filter queries.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

The response body contains data in CSV format.

Version

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

Errors

HTTP status error Code Condition Details
400 400080 Bad Request The view ID in the URI doesn't correspond to a view available on the specified site.
401 401002 Unauthorized The authentication token provided in the request header was invalid or has expired.
403 403032 Read forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
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.
429 429000 Concurrent request limit exceeded

For Tableau Cloud, the cumulative number of concurrent requests has exceeded the limit of 20. This limit applies to long-running jobs such as exports and downloads for view data, images, .pdf or .pptx files, datasources, and crosstabs, Retry this request at a later time.

Introduced September 2021.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/views/2474164d-8d37-4a4c-abc7-c2070fd25fd5/data?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

The returned view data will be no more than 60 minutes old.

Month of Date,Year of Date,Above Median?,Avg. Median
January,1893,below median,-1.0
January,1864,below median,-0.9
January,1861,below median,-0.9
December,1862,below median,-0.9
March,1917,below median,-0.8
December,1892,below median,-0.8
February,1862,below median,-0.8
February,1911,below median,-0.8
February,1917,below median,-0.8
May,1861,below median,-0.8
November,1862,below median,-0.8
March,1898,below median,-0.8
December,1860,below median,-0.8
January,1862,below median,-0.7
March,1850,below median,-0.7
February,1893,below median,-0.7
December,1870,below median,-0.7

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.

URI

GET /api/api-version/sites/site-id/views/view-id/image

GET /api/api-version/sites/site-id/views/view-id/image?resolution=image-resolution

GET /api/api-version/sites/site-id/views/view-id/image?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/views/view-id/image?vf_<fieldname>=filter-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
view-id The ID of the view to return an image for.
image-resolution (Optional) The resolution of the image. Image width and actual pixel density are determined by the display context of the image. Aspect ratio is always preserved. Set the value to high to ensure maximum pixel density.
max-age-minutes (Optional) The maximum number of minutes a view image will be cached before being refreshed. To prevent multiple image requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
filter-value The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter /data?vf_year=2017 would only display data from the year 2017. To learn more, see View filter queries.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

The view's image in PNG format (MIME media type image/png).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query a view preview image, but the caller doesn't have Read permission.
403 403068 Forbidden The endpoint has been disabled on the server. To enable the endpoint, a server administrator must use tsm to configure the sheet_image.enabled setting. For more information, see tsm configuration set Options in the Tableau Server help.
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 the URI doesn't correspond to an existing workbook.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view in the specified workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/image?resolution=high&maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

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.

URI

GET /api/api-version/sites/site-id/views/view-id/pdf

GET /api/api-version/sites/site-id/views/view-id/pdf?vizHeight=viz-height&vizWidth=viz-width

GET /api/api-version/sites/site-id/views/view-id/pdf?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/views/view-id/pdf?type=page-type&orientation=page-orientation

GET /api/api-version/sites/site-id/views/view-id/pdf?vf_<fieldname>=filter-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
view-id The ID of the view to render as a .pdf file.
filter-value The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter /data?vf_year=2017 would only display data from the year 2017. To learn more, see View filter queries.
viz-height (Optional) The height of the rendered pdf image in pixels that, along with the value of vizWidth determine its resolution and aspect ratio.
viz-width (Optional) The width of the rendered pdf image in pixels that, along with the value of vizHeight determine its resolution and aspect ratio.
max-age-minutes (Optional) The maximum number of minutes a view PDF will be cached before being refreshed. To prevent multiple PDF requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
page-orientation (Optional) The orientation of the pages in the .pdf file produced. The value can be Portrait or Landscape. If this parameter is not present the page orientation will default to Portrait.
page-type

(Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be: A3, A4, A5, B5, Executive, Folio, Ledger, Legal, Letter, Note, Quarto, or Tabloid.

If this parameter is not present the page type will default to Legal.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .pdf file. The response header content will have Content-Type:application/pdf.

Version

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

Errors

HTTP status error Code Condition Details
400 400080 Bad Request The view ID in the URI doesn't correspond to a view available on the specified site.
401 401002 Unauthorized The authentication token provided in the request header was invalid or has expired.
403 403032 Read forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
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.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/views/2474164d-8d37-4a4c-abc7-c2070fd25fd5/pdf/maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response is a file that contains the view, whose data is no older than 60 minutes, saved as a pdf.

Query View Permissions

Returns a list of permissions for the specific view.

URI

GET /api/api-version/sites/site-id/views/view-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
view-id The ID of the view to get permissions for.

Request Body

None

Permissions

This method can only be called by server and site administrators, and users who have Read (view) permission for the specific view.

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:permissions:read

Response Code

200

Response Body

<tsResponse>
  <parent type="Project" id="project-id" />
  <permissions>
    <view id="view-id"/>
      <owner id="owner-id"/>
    </view>
    <granteeCapabilities>
      <user id="user-id"/>
      <capabilities>
        <capability name="capability-name" mode="capability-mode"/>
        <capability name="capability-name" mode="capability-mode"/>
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <user id="user-id"/>
      <capabilities>
        <capability name="capability-name" mode="capability-mode"/>
        <capability name="capability-name" mode="capability-mode"/>
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id"/>
      <capabilities>
        <capability name="capability-name" mode="capability-mode"/>
        ... additional capabilities ...
      </capabilities>
      </granteeCapabilities>
  </permissions>
</tsResponse>
          

Note: The parent element is included in the response only if the view's permissions are determined by project-level default permissions and project permissions are 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).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the view.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/0524c7ce-250b-45b1-adf2-d08f1648643c/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <permissions>
    <view id="0524c7ce-250b-45b1-adf2-d08f1648643c"/>
      <owner id="1a5dffe8-2439-4862-9eb0-46d055ef7379"/>
    </view>
    <granteeCapabilities>
      <group id="9e617a5c-a733-11e8-8ec3-b748ab3bf3d6"/>
      <capabilities>
        <capability name="ViewComments" mode=mode="Allow"/>
        <capability name="ExportData" mode=mode="Allow"/>
        <capability name="AddComment" mode=mode="Allow"/>
        <capability name="Filter" mode=mode="Allow"/>
        <capability name="ViewUnderlyingData" mode=mode="Allow"/>
        <capability name="Read" mode=mode="Allow"/>
        <capability name="ShareView" mode=mode="Allow"/>
        <capability name="ExportImage" mode=mode="Allow"/>
      </capabilities>
      </granteeCapabilities>
    <granteeCapabilities>
      <user id="1a5dffe8-2439-4862-9eb0-46d055ef7379"/>
      <capabilities>
        <capability name="ExportImage" mode=mode="Allow"/>
        <capability name="AddComment" mode=mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <user id="ff43cb47-f208-4d2f-9a22-0fbb6d29f7f1"/>
      <capabilities>
        <capability name="AddComment" mode=mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

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.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/views/view-id/previewImage

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
workbook-id The ID of the workbook that contains the view to return a thumbnail image for.
view-id The ID of the view to return a thumbnail image for.

Request Body

None

Permissions

Users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

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:views:download

Response Code

200

Response Body

The view's preview image in PNG format (MIME media type image/png).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query a view preview image, but the caller doesn't have Read permission.
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 the URI doesn't correspond to an existing workbook.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view in the specified workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

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.

URI

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

GET /api/api-version/sites/site-id/views?includeUsageStatistics=get-usage-information

GET /api/api-version/sites/site-id/views?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/views?includeUsageStatistics=get-usage-information&pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/views?filter=filter-expression

GET /api/api-version/sites/site-id/views?sort=sort-expression

GET /api/api-version/sites/site-id/views?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 2.2. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the views.
get-usage-information (Optional) true to return usage statistics. The default is false.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the workbooks or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

For users who are not server administrators or site administrators, the method returns only the views that the user owns or has Read permissions for (either explicitly or implicitly).

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:content:read

Response Code

200

Response Body

<tsResponse>
  <views>
    <view id="view-id"
        name="view-name"
        contentUrl="content-url" >
      <workbook id="workbook-id" />
      <owner id="owner-id" />
      <usage totalViewCount="total-count" />
    </view>
     ... additional views ...
  </views>
</tsResponse>
        

The <usage> element is included in the response only if the method has includeUsageStatistics=true in the URI.

Version

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

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 data sources 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 The includeUsageStatistics was provided with a value other than true or false.
403 403004 Read forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
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.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views" -X GET -H "X-Tableau-Auth:1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2" />
  <views>
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" name="Economic Indicators"
         contentUrl="Finance/sheets/EconomicIndicators">
      <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" />
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
    </view>
    <view id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="Investing in the Dow"
          contentUrl="Finance/sheets/InvestingintheDow">
      <workbook id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" />
      <owner id="9f8e7d6c5-b4a3-f2e1-d0c9-b8a7f6e5d4c" />
  </view>
</tsResponse>

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.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/views

GET /api/api-version/sites/site-id/workbooks/workbook-id/views?includeUsageStatistics=get-usage-information

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to get the views for.
(Optional) get-usage-information true to return usage statistics. The default is false.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <views>
    <view id="view-id" name="view-name"
        contentUrl="content-url" >
      <usage totalViewCount="total-count" />
    </view>
     ... additional views ...
  </views>
</tsResponse>
        

The <usage> element is included in the response only if the method has includeUsageStatistics=true in the URI.

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 parameter value The includeUsageStatistics was provided with a value other than true or false.
403 403004 Read forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/views" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <views>
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" name="Tale of 100 Start-ups"
          contentUrl="Finance/sheets/Taleof100Start-ups"/>
    <view id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="Economic Indicators"
          contentUrl="Finance/sheets/EconomicIndicators"/>
    <view id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="Investing in the Dow"
          contentUrl="Finance/sheets/InvestingintheDow"/>
  </views>
</tsResponse>

Query Workbook Connections

Returns a list of data connections for the specific workbook.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/connections

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to return connection information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a workbook only if they have Read (view) permission for the workbook (either explicitly or implicitly). queryTaggingEnabled is returned only for administrator users.

Response Code

200

Response Body

<tsResponse>
  <connections>
    <connection id="connection-id" type="connection-type"
      serverAddress="server-address" serverPort="port"
	  userName="connection-user-name"
	  queryTaggingEnabled="query-tagging-enabled" />
    < ... additional connections ... >
  </connections>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
403 403021 Read forbidden A user who is not a server administrator user attempted to query the workbook connections, but the caller doesn't have Read permission.
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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <connections>
    <connection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" type="dataengine" />
    <connection id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" type="dataengine" />
    <connection id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" type="dataengine" />
    <connection id="374371c0-ffe9-4e16-b48e-6b868e3026ca" type="dataengine" />
    <connection id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" type="dataengine" />
  </connections>
</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.

Query Workbook Permissions

Returns a list of permissions for the specific workbook.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to get permissions for.

Request Body

None

Permissions

This method can only be called by server administrators and site 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:permissions:read

Response Code

200

Response Body

<tsResponse>
  <parent type="Project" id="project-id" />
  <permissions>
    <workbook id="workbook-id" name="workbook-name >
      <owner="owner-user-id" />
    </workbook>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
         ... additional capabilities for users ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability" mode="capability-mode" />
         ... additional capabilities for groups ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsResponse>
        

Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are 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).

Version

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

Errors

HTTP status error Code Condition Details
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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <parent type="Project" id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
  <permissions>
    <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" name="Finance">
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    </workbook>
    <granteeCapabilities>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"/>
      <capabilities>
        <capability name="Read" mode="Allow"/>
        <capability name="Filter" mode="Allow"/>
        <capability name="ViewUnderlyingData" mode="Allow"/>
        <capability name="ExportImage" mode="Allow"/>
        <capability name="ExportData" mode="Allow"/>
        <capability name="AddComment" mode="Allow"/>
        <capability name="ViewComments" mode="Allow"/>
        <capability name="ShareView" mode="Allow"/>
      </capabilities>
    </granteeCapabilities>
  </permissions>
</tsResponse>

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.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/previewImage

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to return the thumbnail image for.

Request Body

None

Permissions

Users who are not server administrators or site administrators can query a workbook preview image only if they have Read (view) permission for the workbook (either explicitly or implicitly) and also have Read (view) permission for the view that is used as the preview image. If the user doesn't have Read permissions to that view, the preview image for another view might be used. If the user doesn't have Read permissions to any views in the workbook, the user is not allowed to query a workbook query image.

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:workbooks:download

Response Code

200

Response Body

The workbook's preview image in PNG format (MIME media type image/png).

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query the workbook preview image, but the caller doesn't have Read permission for the workbook.
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 the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/previewImage" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > workbook-preview.png

The response is a graphics file in PNG format.

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.

URI

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

GET /api/api-version/sites/site-id/workbooks?filter=filter-expression

GET /api/api-version/sites/site-id/workbooks?sort=sort-expression

GET /api/api-version/sites/site-id/workbooks?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/workbooks?fields=field-expression

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbooks.
filter-expression (Optional) An expression that lets you specify a subset of workbooks to return. You can filter on predefined fields such as name, tags, and createdAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which workbook information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression (Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the workbooks or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

Users who are not server administrators or site administrators can get workbooks that they have Read (view) permissions for (either explicitly or implicitly).

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:content:read

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="page-number"
     pageSize="page-size"
     totalAvailable="total-available" />
  <workbooks>
    <workbook id="workbook-id"
		name="name"
		description ="workbook-description"
		webpageurl="workbook-webpageurl"
		contentUrl="content-url"
        showTabs="show-tabs-flag"
        size="size-in-megabytes"
        createdAt="datetime-created"
	    updatedAt="datetime-updated"
	    defaultViewId="default-view-id" >
	      <project id="project-id" name="project-name" />
	      <owner id="user-id" />
	      <tags>
	        <tag label="tag"/>
	        ... additional tags ...
	     </tags>
	<dataAccelerationConfig accelerationEnabled="accelerationEnabled" lastUpdatedAt="update-date-time" accelerationStatus="accelerationStatus" />
   </workbook>
   ... additional workbooks ...
  </workbooks>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Attribute Values

accelerationEnabled true if data acceleration is enabled, otherwise false. 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).)
accelerationStatus The status can be:
  • accelerated: The acceleration job succeeded.
  • failed: The acceleration job failed.
  • inProgress: The acceleration job is running.
  • notUseful: The acceleration job completed but none of the queries in the workbook were supported for acceleration.
  • waiting: The workbook is enabled for acceleration but no background job has been submitted yet to accelerate it.
(Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)

Version

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

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size exceeds upper limit The page size parameter exceeds the system-wide upper limit of 1000.
403 403018 Read forbidden A non-administrator user attempted to query workbooks for the site, but the caller doesn't have Read permission.
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.

Example: Get workbooks without filter

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="27"/>
  <workbooks>
    <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
		name="Finance"
        description="The finance workbook."
		contentUrl="Finance" showTabs="true"
		webpageUrl="http://MY_SERVER/#/worbooks/1" size="2"
		createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
		defaultViewId="abcd1234-fa4a-4e3f-85fe-db746f44bf4c" >
	      <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
	      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	      <tags/>
    </workbook>
    <workbook id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="World Indicators"
		description="The world indicators workbook."
		contentUrl="WorldIndicators" showTabs="true"
		webpageUrl="http://MY_SERVER/#/worbooks/2" size="1"
        createdAt="2014-02-19T10:19:23Z" updatedAt="2015-12-29T013:23:45Z"
		defaultViewId="edd01d90-fa4a-4e3f-85fe-db746f44bf4c" >
	      <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="default"/>
	      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	      <tags>
          <tag label="training" ></tags>
    </workbook>
  </workbooks>
  ...more workbooks ...
  </tsResponse>
        

Example: Get workbooks with date/time filter

The following example includes a filter to return the workbooks that were updated on 1 May 2016 at 6:00 AM or later and specifies that the results should be sorted by the workbook name.

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks?filter=updatedAt:gte:2016-05-01T06:00:00Z&sort=name:asc" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

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.

URI

GET /api/api-version/sites/site-id/users/user-id/workbooks

GET /api/api-version/sites/site-id/users/user-id/workbooks?ownedBy=isOwner&pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to get workbooks for.
isOwner (Optional) true to return only workbooks that the specified user owns, or false to return all workbooks that the specified user has at least read access to. The default is false.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

All users can call this method, but the results of the call depend on the user's permissions. Server and site administrators see all workbooks for the specified user. If the isOwner parameter is true, users who are not server or site administrators see the workbooks that they own on the site. If isOwner parameter is false, users who are not server administrators see the workbooks that they have Read (view) permissions for.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
         totalAvailable="total-available" />
  <workbooks>
    <workbook id="workbook-id"
	  name="name"
	  description ="workbook-description"
	  webpageurl="workbook-webpageurl"
	  contentUrl="content-url"
      showTabs="show-tabs-flag"
      size="size-in-megabytes"
      createdAt="datetime-created"
      updatedAt="datetime-updated"
      defaultViewId="default-view-id" >
	    <project id="project-id" name="project-name" />
	    <owner id="user-id" />
	    <tags>
	      <tag label="tag"/>
	        ... additional tags ...
	      </tags>
   </workbook>
   ... additional workbooks ...
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

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 data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size exceeds upper limit The page size parameter exceeds the system-wide upper limit of 1000.
403 403018 Read forbidden A non-administrator user attempted to query workbooks for the user, but the caller doesn't have Read permission.
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 GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/workbooks" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <workbooks>
    <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" name="Finance"
	  webpageUrl="https://MY_SERVER/#/worbooks/1"
      contentUrl="Finance" showTabs="true" size="2" description="The Finance workbook."
      createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
      defaultViewId="edd01d90-fa4a-4e3f-85fe-db746f44bf4c" >
	    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
	    <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	    <tags></tags>
    </workbook>
    <workbook id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="World Indicators"
	  webpageUrl="https://MY_SERVER/#/worbooks/2"
	  contentUrl="WorldIndicators" showTabs="true" size="1"  description="The World Indicators workbook."
	  createdAt="2014-02-19T10:19:23Z" updatedAt="2015-12-29T013:23:45Z"
	  defaultViewId="edd01d90-fa4a-4e3f-85fe-db746f44bf4c" >
        <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="default"/>
        <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
        <tags></tags>
    </workbook>
  </workbooks>
</tsResponse>

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.

URI

POST /api/api-version/sites/site-id/reencrypt-extracts

Parameter Values

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

Request Body

None

Permissions

Tableau Server administrators can call this method.

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 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

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

Beginning in February 2024 (Tableau 2024.1), you can register multiple EAS per site.

For more information, see Configure Connected Apps with OAuth 2.0 Trust(Link opens in a new window).

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

Introduced in Tableau Cloud June 2022 (API 3.16). Currently not available for Tableau Server.

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

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: This method can be called by users that have permissions Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
datasource-id The ID of the data source to remove the revision for.
revision-number The revision number of the data source to remove. To determine what versions are available, call Get Data Source Revisions.

Request Body

None

Permissions

Tableau Server users who are site administrators can remove data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can remove data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user attempted to remove a data source revision, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403055 Cannot delete head revision The head (first) version cannot be deleted. To remove the data source, call Delete Data Source.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404024 Data source revision not found The revision number in the URI doesn't correspond to an existing data source revision.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Remove Database

Permanently remove the database asset.

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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.

Version: Available in API 3.22 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

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

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group set.
group-set-id The ID of the group set to remove the group from.
group-id The ID of the group to remove.

Request Body

None

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/groups/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Body

None

Errors

HTTP status error Code Condition Details
400 400032 Deletion failed A problem arose that prevented the group from being removed from the group set.
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 URI doesn't correspond to an existing group.
405 405000 Invalid request method Request type wasn’t DELETE.
409 409120 Group set not found The group set ID in the URI doesn't correspond to an existing user.

For more information, see Handling Errors.

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.

Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Cloud site admins only.

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/disable-oidc-configuration

URI Parameter Values

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

Request Body

None

cURL Request Example

curl "https://us-west-2a.online.tableau.com/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/disable-oidc-configuration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

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.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.

For more information, see Handling Errors.

Remove Table

Permanently remove the table asset.

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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.

URI

Remove a single user from a group

DELETE /api/api-version/sites/site-id/groups/group-id/users/user-id

Bulk remove users from a group (beginning in API 3.21)

PUT /api/api-version/sites/site-id/groups/group-id/users/remove

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to remove the user from.
user-id The ID of the user to remove.

Request Body

Remove a single user from a group

None

Bulk remove users from a group (beginning in API 3.21)

<tsRequest>
  <users>
	<user id="user-id1" />
	<user id="user-id2" />
	<user id="user-id2" />
  </users>
</tsRequest>

Attribute Values (bulk remove users only)

user-id

The ID (not name) of the user to add. You can get the user ID by calling Get Users on Site .

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

Permissions

This method can only be called by server administrators and site 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:groups:update

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400032 Deletion failed A problem arose that prevented the user from being removed from the site.
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 name in the URI doesn't correspond to an existing user.
404 404012 Group not found The group name in the URI doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

Remove a single user from a group

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Bulk remove users from a group (beginning in API 3.21)

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @bulk-remove-users-from-group.xml

Content of bulk-remove-users-from-group.xml:

<tsRequest>
  <users>
	<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
	<user id="1z4e8n7q-6t8t-8f8e-7d7c-1b1a2f2d2e2d" />
  </users>
</tsRequest>

Example response:

The response contains no body (data) if the user (or users) is successfully removed from the group. The HTTP response code is 204 if the delete operation succeeded.

Remove User from Identity Pool

Remove a user from a specified identity pool.

This method is not available for Tableau Cloud.

Version: Available in API 3.19 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Server administrators only. Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available. Access Scopes Overview: Server(Link opens in a new window)

URI

DELETE /api/api-version/sites/site-id/users/user-id/identityPool/idpool-uuid

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that is associated with the user you want to remove from the identity pool.
user-id The ID of the user to remove from the identity pool.
idpool-uuid The ID of the identity pool to remove the user from. You can get the identity pool ID by calling the List Identity Pools(Link opens in a new window) endpoint in the Tableau REST OpenAPI.

Request Body

None

cURL Request Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/7ad8f89e-c2a1-44b4-9413-ac8a62286a7a/identityPool/" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

  • MY-SERVER is the name or IP address of your server.
  • 9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d is the ID of the site, as returned by a previous call to Sign In.
  • 7ad8f89e-c2a1-44b4-9413-ac8a62286a7a is the ID of the user to remove.
  • df47cf24-5ed3-11ed-9b6a-0242ac12000 is the ID of the identity pool.
  • 12ab34cd56ef78ab90cd12ef34ab56cd is the credentials token returned by a previous call to Sign In.

The response contains no body (data) if the user is successfully removed from the identity pool. The HTTP response code is 204 if the delete operation succeeded.

Permissions

This method can only be called by Tableau Server administrators.

Response Code

204

Response Body

None

Version

Version 3.19 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.
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 DELETE.
429 429003 Can't remove user There was a problem and the user couldn't be removed from the identity pool.

For more information, see Handling Errors.

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.

URI

DELETE /api/api-version/sites/site-id/users/user-id

DELETE /api/api-version/sites/site-id/users/user-id?mapAssetsTo=new-user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to remove.
mapAssetsTo Optional. When included in the URI path, the contents owned by the user being removed are transferred to another user. If the user owns subscriptions and no mapAssetsTo is provided, the value of the owner is changed to unknown user. If a user owns only subscriptions, you can delete them from either server or site without having to set mapAssetsTo a different user.

If a user owns only subscriptions, you can delete the user from the server or site without setting this value.

Note: Even though both server administrators and site administrators can call this method, only server administrators can use the mapAssetsTo parameter to reassign content ownership. Site administrators can't use this parameter value. You must be a server administrator to remove a user who still owns content on Tableau Server.

new-user-id The ID of a user that receives ownership of contents of the user being remove.

Request Body

None

Permissions

This method can only be called by server administrators and site 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:users:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Deletion failed Some other problem arose that prevented the user from being removed from the site.
403 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 DELETE.
409 409003 User asset conflict The specified user still owns content on Tableau Server and cannot be deleted.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) if the user is successfully removed from the site. The HTTP response code is 204 if the delete operation succeeded.

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.

URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
workbook-id The ID of the workbook to remove the revision for.
revision-number The revision number of the workbook to remove. To determine what versions are available, call Get Workbook Revisions.

Request Body

None

Permissions

Tableau Server users who are site administrators can remove workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can remove workbook revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified workbook.
  • Save (write) permissions for the project that contains the workbook.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user attempted to remove a data source revision, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403055 Cannot delete head revision The head (first) version cannot be deleted. To remove the workbook, call Delete Workbook.
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 the URI doesn't correspond to an existing workbook.
404 404024 Workbook revision not found The revision number in the URI doesn't correspond to an existing workbook revision.
405 405000 Invalid request method Request type was not DELETE.

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.

URI

DELETE /api/api-version/auth/serverAdminAccessTokens

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

Only Tableau Server users with server administrator permissions can use this method.

Response Code

204

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
403 403004 Revoke server admin tokens forbidden, The user does not have the server administrator permissions required to call this method.
404 404000 Server not found The Tableau Server in the URI doesn't correspond to an existing server.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

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.

Version: Available in API 3.21 (Tableau Cloud October 2023) and later.Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Any Tableau Cloud user. If you're a Tableau Cloud site admin, you can revoke the PAT of a user when you are the site admin on all sites that the PAT owner is a member of. Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

DELETE /api/api-version/sites/site-luid/users/user-luid/personal-access-tokens/pat-name

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
user-luid The LUID of the user. The user LUID is returned after you successfully authenticate to the Tableau REST API.
pat-name The name of the PAT you want to revoke.

Request Body

None

cURL Request Example

curl "http://myco/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/d5704762-603a-42b2-a9a7-f9cd2b2c4253/personal-access-tokens/my_pat" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

204

Response Body

None

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.

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.

URI

POST /api/api-version/sites/site-id/tasks/extractRefreshes/task-id/runNow

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
task-id The ID of the extract refresh task that you want to run.

JWT Access Scope

tableau:tasks:run (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

You must include a valid request with the POST operation. Currently, the request body can be empty. In the future, you might be able to set options for the task.

<tsRequest>
</tsRequest>

Permissions

Tableau Server users who are not server administrators or site administrators can only run the extract refresh tasks that they own.

Response Code

200

Response Body

<tsResponse>
  <job id="JOB_ID" mode="MODE" type="RefreshExtract" />
</tsResponse>
        

Version

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

Errors

403 403004 Operation unauthorized The user is not authorized to get the task.
403 403047 Extract refresh error The task specified is not an extract refresh task.
404 404026 Task not found The task ID in the URI doesn't correspond to an existing task.
405 40500 Invalid requests method Request type was not POST.
409 409093 Operation already in Queue The extract refresh job is already in the queue.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/extractRefreshes/9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c/runNow" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @empty_request.xml

Example response:


<tsResponse version-and-namespace-settings>
  <job id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" mode="Asynchronous" type="RefreshExtract" />
</tsResponse>
          

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

 

URI

POST /api/api-version/sites/site-id/flows/flow-id/run

POST /api/api-version/sites/site-id/flows/flow-id/run?flowOutputStepIds=flow-outputstep-id&flowRunMode=flow-run-mode

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-id The ID of the flow to update.

Request Body

<tsRequest>
  <flowRunSpec
   flowId="flow id"
   runMode="run mode">
    <flowParameterSpecs>
      <flowParameterSpec
	   parameterId="parameter id"
       overrideValue="override value" />
    </flowParameterSpecs>
    <flowOutputSteps>
      <flowOutputStep
       id="flow output step id" />
    </flowOutputSteps>
  </flowRunSpec>
</tsRequest>

A request body with for running a flow with no parameters:

<tsRequest>
  <flowRunSpec
   flowId="flow id"
   runMode="run mode">
    <flowOutputSteps>
      <flowOutputStep
	   id="flow output step id" />
    </flowOutputSteps>
  </flowRunSpec>
</tsRequest>

A request body for running a flow but not specifying output step (effectively running all output steps):

<tsRequest>
  <flowRunSpec
   flowId="flow id"
   runMode="run mode">
    <flowParameterSpecs>
      <flowParameterSpec
	   parameterId="parameter id"
       overrideValue="override value" />
    </flowParameterSpecs>
  </flowRunSpec>
</tsRequest>

Attribute Values

flow-id

The ID of the flow to add to the schedule. This will include all the output steps in the flow and any output steps created in the future.

flow-outputstep-id

The ID of the output steps you want to run. This parameter is optional. If you don't specify the output steps, all the output steps in the flow will be included. You can specify one or more output steps. Use the List Metrics for Site - Retired in API 3.22 method to get the list of flow-outputstep-ids.

flow-run-mode

The mode to use for running this flow, either full or incremental. This parameter is optional. If you don't specify an option the run mode will be full. The flow must be configured with incremental options on the input nodes to refresh incrementally.

parameter-id

The ID of the flow parameter. Use the List Metrics for Site - Retired in API 3.22 method to get the flow parameter ID. A parameter is a global placeholder value such as a number, text value, or boolean value that can replace a constant value in a flow.

Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled.

For more information, see Run flows with parameters.

overrideValue

The run-time value for the flow parameter. You must specify this if the parameter is required. Use the List Metrics for Site - Retired in API 3.22 method to see if the parameter is required and to get a list of allowed values if the parameter is expecting a value from an enumerated list.

Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled.

For more information, see Run flows with parameters.

Note: You must specify the flow-id value in the URI. If you are using a request body to specify the attributes, you must also include the flow-id in the request body in addition to providing it in the URI.

Permissions

In addition to the owner of a flow, Tableau server administrators, site administrators, and project leaders can run flows within their scope. Users with a creator or explorer license that have been granted permissions by an administrator, leader or owner for a flow may also run it.

Response Code

200

Response Body

<tsResponse>
   <job id="job-id"
    mode="Asynchronous"
    type="RunFlow"
    createdAt="DateTime-CreatedAt">
   <runFlowJobType flowRunId="flow-run-id">
     <flow id="flow-id" name="flow-name"/>

   </runFlowJobType>
   </job>
</tsResponse>
        

Version

Version 3.3 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 400132 Invalid flow run mode The specified flow run mode is not valid.
400 400148 Invalid parameter override value The run-time value specified is not valid.
400 400149 Parameter override value missing The run-time value for the parameter was not specified and is required.
403 403149 Flow cannot be run The flow parameter setting is disabled on the site preventing the flow run.
403 403150 Flow cannot be run The flow cannot be run because flow parameters contain parameter domain type "any" but the Allow parameters that can accept any input setting is disabled on the site.
404 404000 Site not found The site ID in the URI is unknown.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
404 404043 Flow parameter not found The parameter ID specified in the request body does not match any of the existing parameters for this flow.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/flows/ d00700fe-28a0-4ece-a7af-5543ddf38a82/run?flowRunMode=incremental" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"

Content of empty-tsrequest.xml:

<tsrequest>
</tsrequest>

Example response:

<tsResponse version-and-namespace-settings>
    <job id="57a8d2f6-899c-4c0f-9b25-fe0d007c5ad0" mode="Asynchronous" type="RunFlow" createdAt="2018-11-12T19:14:08Z">
        <runFlowJobType flowRunId="34b9f6d3-222a-2f2f-6a22-dd2f228a6ff2">
            <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good"/>
        </runFlowJobType>
    </job>
</tsResponse>
        

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.

URI

POST /api/api-version/sites/site-id/tasks/runFlow/task-id/runNow

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
task-id The ID of the flow run task that you want to run.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can only run the flow run tasks that they own.

Response Code

200

Response Body

<tsResponse >
    <job id="job-id"
         mode="Asynchronous"
         type="RunFlow"
         createdAt="Datetime-CreatedAt">
        <runFlowJobType flowRunId="flow-run-id">
            <flow id="flow-id" name="flow-name"/>
        </runFlowJobType>
    </job>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400084 Flow run task error The task specified is not a flow run task.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/runFlow/9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c/runNow" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @empty-tsrequest.xml

Content of empty-tsrequest.xml:

<tsrequest>
</tsrequest>

Example response:

<tsResponse version-and-namespace-settings>
    <job id="50afe58f-b719-4858-8b4b-e31700685c12" mode="Asynchronous" type="RunFlow" createdAt="2018-11-12T19:43:00Z">
        <runFlowJobType flowRunId="34b9f6d3-222a-2f2f-6a22-dd2f228a6ff2">
            <flow id="6f4bc5a1-3905-45a7-abbc-cdb735d0b79f" name="allUseCaseTFLX"/>
        </runFlowJobType>
    </job>
</tsResponse> 

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

URI

POST /api/api-version/sites/site-id/tasks/linked-task-id/runNow

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
linked-task-id The ID of the linked task to run.

Request Body

none

Permissions

In addition to the owner of a linked task, Tableau server administrators, site administrators, and project leaders can run linked tasks within their scope. Tableau users can run a linked task if they have permissions to run all the flows included in it.

Response Code

200

Response Body

<tsResponse>
   <linkedTaskJob id="linked-task-job-id"
    linkedTaskId="linked-task-id"
    status="status"
    createdAt="DateTime-CreatedAt"/>
  </tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
400 400153 Generic error Unable to run the linked task for some reason other than the ones specified below.
403 403155 Linked task cannot be run The linked task setting is disabled on the site.
404 404045 Linked task not found The linked task ID in the URI doesn't correspond to an existing linked task.
405 405000 Invalid request method Request type was not POST.
409 409082 Run now forbidden Run now setting has been disabled.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/tasks/linked/d00700fe-28a0-4ece-a7af-5543ddf38a82/runNow -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"

Content of empty-tsrequest.xml:

<tsrequest>
</tsrequest>

Example response:

<tsResponse>
   <linkedTaskJob id="765dfdfc-26ec-47ea-b53b-54419c8f6b61"
    linkedTaskId="cde24429-6217-48e5-8ff5-f5dcd6a7006b"
    status="InProgress"
    createdAt="2022-02-15T00:22:22Z"/>
</tsResponse>

Server Info

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

URI

GET /api/api-version/serverinfo

Parameter Values

api-version

The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

This method can be called by all users and does not require authentication.

Response Code

200

Response Body

<tsResponse>
    <serverInfo>
        <productVersion build="build-number">product-version</productVersion>
        <restApiVersion>api-version</restApiVersion>
    </serverInfo>
</tsResponse>
        

The response contains the following information:

  • build-number. The build number of your installation of Tableau Server.
  • product-version. The product version of your installation of Tableau Server.
  • api-version. The REST API version that is compatible with your version of Tableau Server.

Version

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

Errors

HTTP status error Code Condition Details
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

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.

Version: Preview release available in some regions API 3.21 (Tableau Cloud October 2023 / Server 2023.3) and later. Version Overview

License: No additional license required.

Permissions: Only Tableau administrators can set a custom view as the default view for users.  Permissions Overview

JWT Access Scope: tableau:views:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

POST /api/api-version/sites/site-luid/customviews/custom-view-luid/default/users

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
custom-view-luid The LUID for the custom view being updated.

Request Body

Copy
<tsRequest>
  <users >
    <user id="5c9a81df-7ec0-4752-a057-82cd2bb22c44"/>
  </users>
</tsRequest>
Copy
{
  "users": {
    "user": {
      "id": "5c9a81df-7ec0-4752-a057-82cd2bb22c44"
    }
  }
}

cURL Request Example

curl --location 'https://qa-near.tsi.lan/api/3.21/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/3321cb71-6606-4d78-8a0c-e69a7e7d2261/default/users' --header 'Accept: application/xml' --header 'X-Tableau-Auth: X4fzaa75SJqSiCjq6EI9ow|uTR4NKykLGob3VustCzOq1htrchwo0ga|a946d998-2ead-4894-bb50-1054a91dcab3' --header 'Content-Type: text/plain' --data ''

Response Code

200

Response Body

Copy
<tsResponse>
  <customViewAsUserDefaultResults>
    <customViewAsUserDefaultViewResult success="true">
      <user id="5c9a81df-7ec0-4752-a057-82cd2bb22c44"/>
    </customViewAsUserDefaultViewResult>
  </customViewAsUserDefaultResults>
</tsResponse>
Copy
{
  "customViewAsUserDefaultResults": {
    "customViewAsUserDefaultViewResult": {
      "success": "true",
      "user": {
        "id": "5c9a81df-7ec0-4752-a057-82cd2bb22c44"
      }
    }
  }
}

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

Notes:

  • SAML single sign on(Link opens in a new window) (SSO) authentication does not validate REST API requests. For a scenario where you want to integrate Tableau authentication into a SSO environment you will need to incorporate a REST sign in request, and then use the credentials token from its response in the header of subsequent requests.

  • The credentials token is valid for REST API calls and Tableau Metadata API (GraphQL) queries. You cannot use the credentials token as authentication for other operations with Tableau Server. In addition, the credentials token is good only for operations in the site that you're signed in to. You cannot sign in to one site and then use the credentials token you get back to send requests to a different site. If you do, the server returns an HTTP 403 (Forbidden) error.

  • (Tableau Cloud only) If multi-factor authentication (MFA) is enabled with Tableau authentication, PATs are required. You must use a PAT, instead of user name and password, to make a REST API sign in request to Tableau Cloud.

URI

POST /api/api-version/auth/signin

Note: For Tableau Cloud, the server address in the URI must contain the pod name, such as 10az, 10ay, or us-east-1. For example, the URI to sign in to a site in the 10ay pod would be:

https://10ay.online.tableau.com/api/api-version/auth/signin

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

PAT

Signing in with a user's personal access token (PAT): 

<tsRequest>
  <credentials personalAccessTokenName="personal-access-token-name"
    personalAccessTokenSecret="personal-access-token-secret" >
      <site contentUrl="content-url" />
  </credentials>
</tsRequest>
        

User name and password

Signing in with a user's user name and password:

<tsRequest>
  <credentials name="username" password="password" >
    <site contentUrl="content-url" />
  </credentials>
</tsRequest>
        

Impersonating user using username and password

Signing in with server administrator's username and password to impersonate a user (not available for Tableau Cloud):

<tsRequest>
  <credentials name="username" password="password" >
	<site contentUrl="content-url" />
	<user id="user-to-impersonate" />
  </credentials>
</tsRequest>

Impersonating user using PAT

Signing in with server administrator's personal access token(Link opens in a new window) (PAT) to impersonate a user (not available for Tableau Cloud):

<tsRequest>
  <credentials personalAccessTokenName="personal-access-token-name"
    personalAccessTokenSecret="personal-access-token-secret" >
	  <site contentUrl="content-url" />
	  <user id="user-to-impersonate" />
  </credentials>
</tsRequest>     

JWT

Signing in with a JSON Web Token (JWT), from a connected app(Link opens in a new window) (Introduced in Tableau Cloud June 2022 (API 3.16); Tableau Server 2022.3 (API 3.17)):

<tsRequest>
  <credentials jwt="json-web-token"
  <site contentUrl="content-url" />
  </credentials>
</tsRequest>			

When a JWT sign-in is used, the JWT must be configured with the scopes of the REST API methods the connected app can access. You can find the scope for a JWT-supported method in a method's properties block or references details under the Access scope section. These sections show the scope declaration to use in the JWT that calls that method. You can also see a full list of JWT-supported scopes in REST API methods that support JWT authorization(Link opens in a new window) (Tableau Cloud Help) or REST API methods that support JWT authorization(Link opens in a new window) (Tableau Server Help).

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

If you encounter issues with signing in with a JWT, the response body is appended with an additional error code that you can reference in Troubleshoot scopes(Link opens in a new window) (Tableau Cloud Help) or Troubleshoot scopes(Link opens in a new window) (Tableau Server Help). For example, in the following response body, you can reference “10084” to help troubleshoot issues with signing in to Tableau Cloud or Tableau Server using a JWT for REST API authorization.

<error code="401001">
  "summary": "Signin Error",
  "detail": "Error signing in to Tableau Cloud (10084)"
</error>

Attribute Values

personal-access-token-name

The name of the personal access token when signing in with a personal access token. The token name is available on a user’s account page on Tableau server or online.

personal-access-token-secret

The secret value of the personal access token when signing in with a personal access token. The value of the secret is available only in the dialog that appears when a user creates a personal access token(Link opens in a new window) as described in the Tableau Help.

username The name of the user when signing in with username and password. The name and password in the <credentials> element can represent any user in the specified site. If the user is not an administrator, they might have limited permissions to perform subsequent operations.

Note: If the server is configured to use Active Directory authentication, and if the user name is not unique across domains, you must include the domain as part of the user name (for example, domain_name\Adam).

password The password when signing in with username and password.
json-web-token

A JSON Web Token (JWT), uses a shared secret provided by the Tableau connected app(Link opens in a new window) and signed by your external application. Depending on the method used to create the connected app, a JWT can be generated by the connected app as part of the external app's call to sign in to Tableau. The JWT must include access scopes(Link opens in a new window) that determine which REST methods the external app can call.

content-url

The permanent name of the site to sign in to. The content URL appears in the URL path of Tableau content in your browser address bar after the Tableau Server URL.

mySite is the content URL in the following example:

http://<server or cloud URL>/#/site/mySite/explore

For Tableau Server, to specify the default site, omit contentUrl from the site element, or make the contentUrl value an empty string (contentUrl="").

For Tableau Cloud, a sign-in request must have a site element containing a contentUrl with the value of an existing site. If these are missing, the sign-in request will fail.

user-to-impersonate The LUID of a user to sign in as. For impersonation when a system administrator signs in with user name and password.

Permissions

Any Tableau user can sign in through the REST API. A user that does not have administrator permissions will have limited permissions to perform subsequent operations. Only server administrators can sign in with username and password in order to impersonate other Tableau Server users.

Response Code

200

Response Body

<tsResponse>
  <credentials token="authentication-token"
	  estimatedTimeToExpiration="time-to-expiration" >
	    <site id="site-id" contentUrl="content-url" />
	    <user id="user-id-of-signed-in-user"
  </credentials>
</tsResponse>
        

An estimatedTimeToExpiration value is returned when you sign in using a PAT. The value represents the approximate time until the token returned from the PAT sign in will expire and need to be refreshed. The estimated time is based on regular usage of the token for authenticating calls, but actual time may be shorter if the token is unused for an extended length of time.

Version

Version 1.0 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 both username/password and a personal access token, or contains malformed XML.
401 401001 Login error The credentials (name or password, or personal access token name or secret) are invalid for the specified site, or the site contentURL is invalid.
401 401001 Login error Login is blocked because several requests with invalid credentials were made.
401 401001 Login error The Administrator requires the user to update their password.
401 401001 Login error The password has expired.
401 401009 Login error The request body is missing or empty.
405 405000 Invalid request method Request type was not POST.

If you are signing in to a Tableau Cloud site, this error may be caused by leaving the pod name out of the server address in the URI.

The error can also be caused by attempting to make a request to a SSL-protected server using HTTP, rather than HTTPS.

For more information, see Handling Errors.

Example

curl "https://MY-SERVER/api/3.22/auth/signin" -X POST -d @signin.xml

Content of signin.xml:

<tsRequest>
  <credentials personalAccessTokenName="MY_PAT_NAME"
	personalAccessTokenSecret="vFel4qtGTZ2+Po0ZWT7YWg==:nMmSHnQ5kJBP17ZtsBgPtuVWdYJFAbBG"  >
      <site contentUrl="MarketingSite" />
  </credentials>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <credentials token="HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3">
    <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
          contentUrl="MarketingSite"/>
  </credentials>
</tsResponse>

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.

URI

POST /api/api-version/auth/signout

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

None

Permissions

Any user can call this method.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/auth/signout" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

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.

URI

POST /api/api-version/auth/switchSite

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

<tsRequest>
   <site contentUrl="content-url" />
</tsRequest>
          

Attribute Values

content-url

The permanent name of the site to sign in to. The content URL appears in the URL path of Tableau content in your browser address bar after the Tableau Server URL.

mySite is the content URL in the following example:

http://<server or cloud URL>/#/site/mySite/explore

For Tableau Server, to specify the default site, omit contentUrl from the site element, or make the contentUrl value an empty string (contentUrl="").

For Tableau Cloud, a sign-in request must have a site element containing a contentUrl with the value of an existing site. If these are missing, the sign-in request will fail.

Permissions

Tableau Server users who are not server administrators can switch sites, provided that they have access to the destination site.

Response Code

200

Response Body

<tsResponse>
  <credentials token="authentication-token" >
    <site id="site-id" contentUrl="content-url" />
    <user id="user-id-of-signed-in-user" />
  </credentials>
</tsResponse>
        

Version

Version 2.6 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 authentication credentials were provided.
401 401002 Unauthorized access Invalid authentication credentials were provided.
401 401003 Switch site error There was a problem switching sites. The site might be unavailable or is not found.
403 403070 Cannot switch to the same site The site specified as the destination site is also the current site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "https://MY-SERVER/api/3.22/auth/switchSite" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"-d @switch_site.xml

Content of switch_site.xml:

<tsRequest>
   <site contentUrl="MarketingSite" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <credentials token="HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3">
    <site id="9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
          contentUrl="MarketingSite"/>
  </credentials>
</tsResponse>

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.

URI

GET /api/3.6/sites/<site-id>/webhooks/<webhook-id>/test

Parameter Values

site-id The ID of the site that contains the webhook.  
webhook-id The ID of the webhook.  

Request Body

None.

Permissions

This method can only be called by server and site administrators.

Response Code

200

Response Body

<tsResponse>
  <webhookTestResult id="9f9bcaf8-8c4c-403c-b7e1-10dd85620f00" status="200">
    <body></body>
  </webhookTestResult>
</tsResponse>

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.


Deletes a specific extension from the block list of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

DELETE /api/api-version/sites/site-id/recommendations/dismissals/?type=view&id=view-luid

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
view-luid The LUID of the view to be removed from the list of views hidden from recommendation for a user.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The content ID in the URI doesn't correspond to an existing content of the requested type.
404 404035 Recommendation not found A hidden recommendation for the given content ID was not found.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dismissals/?type=view&id=1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

No response body. Response code is 204.

Update a Webhook

Modify the properties of an existing webhook.

URI

PUT /api/3.8/sites/<site-id>/webhooks/<webhook-id>

Parameter Values

site-id The ID of the site that contains the webhook to be updated.  
webhook-id The ID of the webhook.  

Request Body

<tsRequest>
  <webhook name="webhook-name"
    isEnabled="webhook-enabled-flag"
    statusChangeReason="reason-for-disablement"
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url" />
      </webhook-destination>
  </webhook>
</tsRequest>

Attribute Values

webhook-name This is required. A name for the webhook.
api-event-name | webhook-source-api-event-name

You must specify one of these attribute values. The name of the Tableau event that triggers your webhook. The event name must be one of the supported events listed in the Trigger Events table. The event and webhook-source use different name values for the same event. 

Recommended: Use the event attribute of the webhook to specify the triggering API event for the webhook. The webhook-source element serves the same purpose but is being deprecated in future versions of Tableau webhooks. If both events and webhook-source are specified, their events specified must match. If either are specified, with the other being NULL, then the specified event becomes the webhook trigger, whether the element containing the event name is event or webhook-source.

url (Optional) The destination URL for the webhook. The webhook destination URL must be https and have a valid certificate.
webhook-enabled-flag (Optional) Boolean. If true (default), the newly created webhook is enabled. If false then the webhook will be disabled.  
reason-for-disablement

The reason a webhook is disabled.

  • If isEnabled set to true, omit this parameter from your request to create a webhook, or set the value of statusChangeReason to an empty string. Providing a reason value when creating an enabled webhook will result in an error (400127).
  • If isEnabled set to false, then unless you provide a value for statusChangeReason it will default to "Webhook disabled by user".

Permissions

This method can only be called by server and site administrators.

Response Code

201 Success.

Response Body

<tsResponse>
  <webhook
    id="webhook-id"
    name="webhook-name"
    isEnabled="true"
    statusChangeReason=""
    event="api-event-name">
      <webhook-source>
        <webhook-source-api-event-name />
      </webhook-source>
      <webhook-destination>
        <webhook-destination-http method="POST" url="url"/>
      </webhook-destination>
      <owner id="webhook_owner_luid" name="webhook_owner_name"/>
  </webhook>
</tsResponse>

Errors

HTTP status error Code Condition Details
400 400127 Bad request statusChangeReason was provided with isEnabled = true

For more information, see Handling Errors.

Response Headers

Location: /api/3.22/sites/site-id/webhooks/new-webhook-id

Update analytics extension connection of site

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

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: Can only be called by users with site or server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can be called by users that have permissions Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Update Authentication Configuration

Update an authentication instance.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Administrators and the owner of a custom schedule for an extract refresh task can update the schedule.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:task:update (this scope is included in the scope: tableau:tasks)
    Access Scopes Overview: Cloud(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/tasks/extractRefreshes/task-luid

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
task-luid The LUID of the extract refresh task. Use Get extract refresh tasks on site to find tasks by name.

Request Body

Copy
<tsRequest>
  <extractRefresh type="FullRefresh">
    <workbook id="13237fd-6365-44d5-925b-644e5281b605" />
  </extractRefresh>
  <schedule frequency="Daily">
    <frequencyDetails start="18:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Sunday"/>
        <interval weekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Copy
{
  "extractRefresh": {
    "type": "FullRefresh",
    "workbook": {
      "id": "13237fd-6365-44d5-925b-644e5281b605"
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}

Request Attributes

All request attributes are optional to update a custom schedule for a subscription.

extractRefresh type enumeration: The type of extract refresh being scheduled. Valid values include:
  • FullRefresh
  • IncrementalRefresh
workbook id
or datasource id
LUID: The LUID of the workbook or datasource that is the target of the custom schedule.
schedule frequency enumeration: The scheduled frequency for triggering the extract refresh. Valid values include:
  • Hourly
  • Daily
  • Weekly
  • Monthly
frequencyDetails start time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.
frequencyDetails end

time: If the schedule frequency is Hourly, or Daily with an interval of hours less than 24, then end is the time of day on which scheduled jobs should stop being run. The valid format is HH:MM:SS. Time should be specified in 5 minute increments and the difference between start and end times should be increments of 60 minutes. For example, a valid frequencyDetail would be:

<frequencyDetail start="20:45:00" end="21:45:00">
    . . . 
</frequencyDetail>
interval {interval type} string: Defines when and how often a scheduled job executes within the time parameters set in the start and end values of the frequencyDetails of the schedule. The type and valid values for an interval expression depend on the declared frequency of the schedule as follows:

FrequencyValid interval values
Hourly The value of an interval for an Hourly schedule can be only one of either:
  • hours=“1" The number of hours between jobs. 1 is the only valid value.
  • minutes=“60" The number of minutes between jobs. 60 is the only valid value.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday.

    For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="1"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
     <intervals>
Daily The value of Daily can have multiple weekday elements, but only one hours declaration. An hours interval is required.
  • hours=“interval" The interval between execution of jobs on the weekday(s) specified. Valid values are 2, 4, 6, 8, 12, or 24. Note that if the interval value of a daily schedule is less than 24, a frequencyDetail end time must be supplied.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

    For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="4"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
    <intervals>
WeeklyweekDay=“weekday" The day of the week the schedule should run on. Multiple days can be specified for a Weekly schedule. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.
Monthly

The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval:

Specify the day(s) using the number of the day in the month;

  • monthDay=“day" The number of the day of the month. Valid values are the whole numbers 1 to 31 or LastDay. If you specify monthDay by day number then you can use multiple interval instances to choose for the job to run on multiple days in the month. If you use LastDay then only one instance of interval can be used in the schedule to specify the last day of the month. For example, to make a schedule that that would run a job on the first and fifteenth of each month, you would use:
    Copy
    <intervals/>
      <interval monthDay="1"/>
      <interval monthDay="15"/>
    </intervals/>

Specify the day by describing which occurrence of a weekday within the month.

  • monthDay=“occurrence_of_weekday" Weekday=“weekday" The occurrence of the specified weekday within the month when a job should be run. Valid values for occurrencee_of_weekday are First, Second, Third, Fourth, Fifth, or LastDay. Valid values for weekday are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday. If the value is lastDay then the job will run on the last occurrence of the specified weekday in the month.

    For example, to make a schedule that that would run a job on the third Thursday of each month, you would use:
    Copy
    <interval monthDay="Third" weekDay="Thursday"/>

cURL Request Example

curl --location --request PUT "qa-near.tsi.lan/api/3.22/sites/a946d998-2ead-4894-bb50-1054a91dcab3/tasks/extractRefreshes/r2345998-2ead-4894-bb50-1054a9109876" --header "Content-Type: application/xml" --data "<tsRequest> <extractRefresh type='FullRefresh'> <workbook id='0057ccac-872a-11e5-bb51-f763326b1350' /> </extractRefresh> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> </intervals> <intervals> <interval weekDay='Sunday'/> </intervals> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"

Response Code

200

Response Body

Copy
<tsResponse>
  <extractRefresh 
    id="13237fd-6365-44d5-925b-644e5281b605"
    consecutiveFailedCount="0"
    type="IncrementalRefresh" >
      <datasource id="0057ccac-872a-11e5-bb51-f763326b1350" />
  </extractRefresh>
  <schedule id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
    createdAt="2023-04-06T23:43:12-0700"
    updatedAt="2023-04-06T23:43:12-0700"
    frequency="Daily"
    nextRunAt="2023-04-06T23:43:12-0700">
        <frequencyDetails start="18:30:00" end="23:30:00">
        <intervals>
          <interval hours="4"/>
          <interval weekDay="Sunday"/>
          <interval weekDay="Wednesday"/>
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
Copy
{
  "extractRefresh": {
    "id": "13237fd-6365-44d5-925b-644e5281b605",
    "consecutiveFailedCount": "0",
    "type": "IncrementalRefresh",
    "datasource": {
      "id": "0057ccac-872a-11e5-bb51-f763326b1350"
    }
  },
  "schedule": {
    "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
    "createdAt": "2023-04-06T23:43:12-0700",
    "updatedAt": "2023-04-06T23:43:12-0700",
    "frequency": "Daily",
    "nextRunAt": "2023-04-06T23:43:12-0700",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}
    

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.22. 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: Deprecated in API 3.17 - the following resource is no longer supported and will be retired in future releases: 

URI PUT api/api-version/sites/site-id/connected-applications/client-id

Parameter Values

api-version The version of the API to use, such as 3.22. 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

<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 REST 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, 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 REST API 3.21 (or earlier)), specify the projectId attribute and its value.

  • Multiple projects: For Tableau Cloud only, beginning with REST API version 3.22 (February 2024), 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, specify the projectIds attribute and do not specify values. For example, <projectIds></projectIds>.

    • For Tableau Server (or Tableau Cloud using REST API 3.21 (or earlier)), specify the projectId attribute and leave its value empty. For example projectId="".

    Note: If the projectIds(Tableau Cloud only) or projectId(Tableau Server or Tableau Cloud) is not included in the request, the connected apps' access level is not updated.

Note: For Tableau Cloud, 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.

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

Version: Available in API 3.18 (Tableau Cloud December 2024) and later. Not available for Tableau Server. Version Overview

License: No additional license required.

Permissions: Tableau administrators can update the owner and name of a custom view. Other users can update those attributes of any custom view that they own.  Permissions Overview

JWT Access Scope: tableau:views:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/customviews/custom-view-luid

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
custom-view-luid The LUID for the custom view being updated.

Request Body

<tsRequest>
  <customView name="new-name" >
	  <owner id="cdfe8548-84c8-418e-9b33-2c0728b2398a" />
  <customView>
</tsRequest>

{
  "customView": {
    "name": "new-name",
	"owner": {
	  "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a"
	}
  }
}

Request Attributes

customView name (Optional) string The new name of the custom view that replaces the existing one.
owner id (Optional) LUID The LUID of the new owner of custom view that replaces the existing one.

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:views:update

cURL Request Example

curl -L -X PUT "https://qa-near/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/37d015c6-bc28-4c88-989c-72c0a171f7aa" -H "X-Tableau-Auth: njR9EGn0QSCpbDrUOh0IKg"wamRRyVFFUHTVwFL6OWEyOggxCwWYXuq"a946d998-2ead-4894-bb50-1054a91dcab3" -H "Content-Type: application/xml" --data-raw "<tsRequest> <customView name='new-name'> <owner id='cdfe8548-84c8-418e-9b33-2c0728b2398a' /> </customView> </tsRequest>"

Response Code

200

Response Body

<tsRequest>
  <customView
    id="37d015c6-bc28-4c88-989c-72c0a171f7aa"
    name="new-name_2514e471-95ed-4d22-92c0-da648c23891b"
    createdAt="2016-02-03T23:35:09Z"
    updatedAt="2022-10-21T04:41:27Z"
    shared="false">
      <view id="8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f" name="circle"/>
      <workbook id="2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5" name="my workbook"/>
      <owner id="cdfe8548-84c8-418e-9b33-2c0728b2398a" name="workgroupuser"/>
  </customView>
</tsRequest>

{
  "customView": {
    "id": "37d015c6-bc28-4c88-989c-72c0a171f7aa",
    "name": "New name 3_2514e471-95ed-4d22-92c0-da648c23891b",
    "createdAt": "2016-02-03T23:35:09Z",
    "updatedAt": "2022-10-21T04:41:27Z",
    "shared": "false",
    "view": {
 	  "id": "8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f",
	  "name": "circle"
    },
    "workbook": {
      "id": "2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5",
      "name": "marks and viz types 2"
    },
    "owner": {
      "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
      "name": "workgroupuser"
    }
  }
}

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.


Updates the settings for dashboard extensions for the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: This method can only be called by users with server or Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.


Updates the settings for dashboard extensions of a server

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

This method requires server or site administrator permissions.

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

This method requires server or site administrator permissions.

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

A custom message to accompany the data quality warning. The message is optional in Tableau Cloud, but required in Tableau Server.

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.

Version: Available in API Version 2.0 and later. Version Overview

License:No additional license required.

Permissions: You can update data source details if you are a Tableau administrator. Specific properties can be updated by other users depending on the type of update action and the permissions granted to the user . . . learn more  | Permissions Overview

JWT Access Scope: tableau:datasources:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

URI

PUT /api/api-version/sites/site-id/datasources/datasource-id

Starting in 2021.2, you can also modify (insert, update, upsert, replace and delete) data in a published data source that is a live-to-Hyper connection. To do this, use the Update Data in Hyper Data Source method, or for data sources with multiple connections, use the Update Data in Hyper Connection method. For more information, see UpdateData in Published Live-to-Hyper Data Sources.

Path Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the data source.
datasource-luid The LUID of the data source to update.

Request Body

<tsRequest>
  <datasource name="Sales"
    isCertified="true"
    certificationNote="This is a certification note."
    encryptExtracts="false">
      <project id="56c86f04-b834-4a08-a561-86497bb4b2df"/>
      <owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613"/>
      <askData enablement="true [REMOVED IN API 3.12]"/>
  </datasource>
</tsRequest>

{
  "datasource": {
    "name": "Sales",
    "isCertified": "true",
    "certificationNote": "This is a certification note.",
    "encryptExtracts": "false",
    "project": {
    "id": "56c86f04-b834-4a08-a561-86497bb4b2df"
    },
	"owner": {
      "id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
	  },
	 "askData": {
	   "enablement": "true [REMOVED IN API 3.12]"
	 }
  }
}

Request Attributes

datasource name (Optional) The new name of a the data source.
project (Optional) The LUID of a project to add the data source to.
owner (Optional) The LUID of a user to assign the data source to as owner.
datasource certification-status (Optional) A Boolean value that indicates whether the data source is certified. To learn more about data source certification, see Use Certified and Recommended Data Sources and Tables.
datasource certification-note (Optional) A note that provides more information on the certification of the data source, if applicable.
datasource encryptExtracts (Optional) true to encrypt the extracts or false to not encrypt extracts. For more information, see Extract and Encryption Methods.
askDataEnablement

This attribute is removed in API 3.12 and later (Tableau Cloud September 2021 / Server 2021.3).

(Optional) Determines if a data source allows use of Ask Data. The value can be Enabled, Disabled, or SiteDefault.

If enablement is not specified, Ask Data availability for the data source is unchanged during this update. If the askData element is included, it must contain an enablement attribute. Setting the value of enablement to SiteDefault for a data source will cause its enablement to follow the site's settings for Availability of Ask Data. A value of Enabled or Disabled will override a site's settings for the data source unless the setting Always disable Ask Data is selected. In that case, Ask Data will not be available for the data source regardless of the value of enablement.

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

If the <project> element is included, the id attribute must be included, and any other attributes of the <project> element are ignored.

If the <owner> element is included, the id attribute must be included, and any other attributes of the owner are ignored.

Permissions Details

Users who are server administrators or site administrators can change the owner for a data source.

Users who are not server administrators can move a data source from one project to another if they own the data source or the current (source) project, or are a project leader for the current project, and they have Write permission for the destination project.

Users can change certification status and the certification note if they are server administrators, site administrators, or project leaders for the current project.

Users can modify the name of the data source if: they have server or site administrator permissions, or the site role of Creator or higher and access to the data source with the overwrite capability.

cURL Example

curl --location --request GET "https://MY_SERVER/api/3.16/sites/a946d998-2ead-4894-bb50-1054a91dcab3/datasources" \ --header "X-Tableau-Auth: b09KVmT7QxuLVLv1En7iMg"oxKwSGTYT0WKRes5xk3dgI4gIkG3TM8W"a946d998-2ead-4894-bb50-1054a91dcvv8" \ --header "Content-Type: application/xml" \ --data-raw "<tsRequest/> <datasource name='Sales'/> >datasource/> >tsRequest/>"

Response Code

200

Response Body

<tsResponse>
  <datasource name="Sales" id="75b71d2f-e8d3-42af-b654-d953659326ee"
    contentUrl="mySite" type="excel-direct"
    createdAt="2016-02-12T23:36:09Z" updatedAt="2020-12-16T15:33:03Z"
    isCertified="false"
    certificationNote="This is a certification note."
    encryptExtracts="false">
      <project id="56c86f04-b834-4a08-a561-86497bb4b2df" />
      <owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613" />
      <job id="65348c74-7818-4eb8-b2a1-9f3f5f588870" />
      <askData enablement="true [REMOVED IN API 3.12]" />
  </datasource>
</tsResponse>

{
  "datasource": {
    "name": "Sales",
    "id": "75b71d2f-e8d3-42af-b654-d953659326ee",
    "contentUrl": "mySite",
	"type": "excel-direct",
	"createdAt": "2016-02-12T23:36:09Z",
	"updatedAt": "2020-12-16T15:33:03Z",
	"isCertified": "false",
	"certificationNote": "This is a certification note.",
	"encryptExtracts": "false",
	"project": {
	"id": "56c86f04-b834-4a08-a561-86497bb4b2df"
    },
    "owner": {
      "id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
    },
    "job": {
      "id": "65348c74-7818-4eb8-b2a1-9f3f5f588870"
    },
    "askData": {
	  "enablement": "true [REMOVED IN API 3.12]"
    }
  }
}

The createdAt and updatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

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 400008 Invalid parameter value A user attempted to rename a datasource to a name containing only spaces, or to a name with more 255 characters.
400 400129 Invalid Ask Data enablement The requested enablement setting in the request body does not correspond to the site configuration.
403 403027 Owner update forbidden A non-administrator user tried to change the owner for the data source.
403 403030 Project update forbidden A non-administrator user tried to change the project for the data source, but the caller doesn't have Write permission for the project.
403 403032 Update forbidden A non-administrator user tried to update a data source, but the caller doesn't have Write permission.
403 403141 Update forbidden A user attempted to update a data source that they do not have permissions to update.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 Owner not found The owner ID in the request body doesn't correspond to an existing owner.
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 request body doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not PUT or 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.

For more information, see Handling Errors.

Update Data Source Connection

Updates the server address, port, username, or password for the specified data source connection.

Version: Available in API Version 2.3 . . . learn more | Version Overview

License: Available for Tableau Server and Tableau Cloud.

Permissions: Users who are server administrators or site administrators can change the connection for a data source or enable query tagging(Link opens in a new window). Users who are not server administrators can update a data source only. . . learn more |  Permissions overview

JWT Access Scope:     tableau:datasources:update access scope details

URI

PUT /api/api-version/sites/site-id/datasources/datasource-id/connections/connection-id

Path Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the data source.
datasource-luid The LUID of the data source to update.
connection-luid The LUID of the connection to update. To determine what connections are available for a data source, call Query Data Source Connections.

Request Body

<tsRequest>
  <connection
	serverAddress="newAddress"
	serverPort="newPort"
	userName="Jane Doe"
	password="xxxxxx"
	embedPassword="false"
	queryTaggingEnabled="false" />
</tsRequest>

{
  "connection": {
	"serverAddress": "newAddress",
	"serverPort": "newPort",
	"userName": "Jane Doe",
	"password": "xxxxxx",
	"embedPassword": "false",
	"queryTaggingEnabled": "false"
  }
}

Request Attributes

connection serverAddress (Required) The new server for the connection.
connection serverPort (Required) The new port for the connection
connection userName (Required) The new username for the connection.
connection password (Required) The new password for the connection.
embedPassword True to embed the password; otherwise, False.
queryTaggingEnabled

In API 3.23 (Tableau Cloud June 2024 / Server 2024.2) and later: using queryTaggingEnabeld to enable query tagging for individual connections is deprecated, will no longer be supported, and may be retired in future releases. Instead:

- For Tableau Cloud, query tagging will be enabled for all content on a site by default.

- For Tableau Server 2023.3 and later, you can use TSM to enable query tagging for all content on a server by setting native_api.UserInfoInGeneratedSQLEnabled(Link opens in a new window) to true.

For API 3.22 or earlier: true to enable query tagging that associates a specific server log query event with the Tableau resource that made the query. False, which disables query tagging, is the default.

Any combination of the attributes inside the <connection> element is valid. If no attributes are included, no update is made.

Permissions Details

Users who are server administrators or site administrators can change the connection for a data source or enable query tagging(Link opens in a new window). Users who are not server administrators can update a data source only. If they have Write (save) permission for the data source and if they have write permission for the project.

Version Details

Version 2.3 and later. (A different version of this method was available in earlier versions of the REST API. For details, see Update Data Source Connection(Link opens in a new window) in the REST API version 9.3 documentation.) For more information, see REST API and Resource Versions.

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:datasources:update

Response Code

200

Response Body

<tsResponse>
  <connection id="90365b4d-978f-425b-bb53-66a984bab34v"
	serverAddress="newAddress"
	serverPort="newPort"
	userName="Jane Doe"
	queryTaggingEnabled="false" />
</tsResponse>

{
  "connection": {
	"id": "90365b4d-978f-425b-bb53-66a984bab34v",
	"serverAddress": "newAddress",
	"serverPort": "newPort",
	"userName": "Jane Doe",
	"queryTaggingEnabled": "false"
  }
}

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 403023 Update forbidden A non-administrator user tried to update a data source, but the caller doesn't have Write permission.
403 403027 Owner update forbidden A non-administrator user tried to change connection information, but the caller doesn't have Write permission.
403 403062 Unsupported operation The data source contains multiple connections, but the URI did not include /connections/connection-id to indicate which connection should be updated.
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.

Example

curl --location --request PUT "https://MY_SERVER/api/3.16/sites/a946d998-2ead-4894-bb50-1054a91dcab3/datasources/75b71d2f-e8d3-42af-b654-d953659326ee/connections/90365b4d-978f-425b-bb53-66a984bab10c" \ --header "X-Tableau-Auth: TimrTnJ3QqSzqA7bg65WMQ"3F3Gfr186RJTCovRpYyyw5KuNU3saxuu"a946d998-2ead-4894-bb50-1054a91dcab3" \ --header "Content-Type: application/xml" \ --data-raw "<tsRequest> <connection queryTaggingEnabled='true' /> </tsRequest>"

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.

URI

POST /api/api-version/sites/site-id/datasources/datasource-id/refresh

Parameter Values

api-version The version of the API to use, such as 3.22. 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 refresh.

Request Body

<tsRequest>
</tsRequest>        

Permissions

Users who are not server administrators or site administrators can only refresh extracts for data sources if they own the data source, or if they are the project leader for the project.

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:tasks:run

Response Code

202

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="RefreshExtract" createdAt="date-time">
    <extractRefreshJob>
      <datasource id="datasource-id" name="datasource-name" />
    </extractRefreshJob>
</tsResponse>

        

Version

Version 2.8 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 The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user attempted to update a data source, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404004 Data source not found The data source ID in the URI is unknown.
405 405000 Invalid request method Request type was not POST.
409 409093 Operation already in Queue The extract refresh job is already in the queue.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/datasources/89a82d78-664f-45a1-8256-d4d2961a070b/refresh" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"

Content of empty-tsrequest.xml:

<tsRequest>
</tsRequest>

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-2.8.xsd">
  <job id="20cf4ddc-6d73-4733-89ec-8d336669bd56" mode="Asynchronous" type="RefreshExtract" createdAt="2017-12-06T22:58:52Z">
    <extractRefreshJob>
      <datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" name="World Indicators Extract" />
    </extractRefreshJob>
  </job>
</tsResponse>

Update Data-Driven Alert

Update one or more settings for the specified data-driven alert; including the alert subject, frequency, and owner.

URI

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

Parameter Values

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

Version: Available in API 3.2 (Tableau Cloud / Tableau Server 2018.3) and later. Version Overview(Link opens in a new window)

License: No additional license required.>

Permissions: This method can only be called by server administrators and site administrators, and by users who are owners of the specified alert.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:data_driven_alerts:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Request Body

<tsRequest>
    <dataAlert subject="data-alert-subject"
        frequency="data-alert-frequency" public="is-public-flag">
            <owner id="data-alert-owner-id"/>
    </dataAlert>
 </tsRequest>
        

Attribute Values

data-alert-subject (Optional) The string to set as the new subject of the alert.
data-alert-frequency (Optional) The frequency of the data-driven alert: once, frequently, hourly, daily, or weekly.
data-alert-owner-id (Optional) The ID of the user to assign as owner of the data-driven alert.
is-public-flag (Optional) Determines the visibility of the data-driven alert. If the flag is true, users with access to the view containing the alert can see the alert and add themselves as recipients. If the flag is false, then the alert is only visible to the owner, site or server administrators, and specific users they add as recipients. (Optional) Determines the visibility of the data-driven alert. If the flag is true, users with access to the view containing the alert can see the alert and add themselves as recipients. If the flag is false, then the alert is only visible to the owner, site or server administrators, and specific users they add as recipients.

Response Code

200

Response Body

<tsResponse>
  <dataAlert id="data-alert-id" subject="data-alert-subject" creatorId="user-id"
    createdAt="created-date" updatedAt="updated-date" frequency="data-alert-frequency" public="is-public-flag">
    <owner id="user-id" name="user-name" />
    <view id="view-id" name="view-name" >
      <workbook id="workbook-id" name="workbook-name" />
      <project id="project-id" name="project-name" />
    </view>
  </dataAlert>
</tsResponse>
        

The createdAt and updatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Errors

HTTP status error Code Condition Details
403 403004 Write forbidden A user called this method who does not have the required permissions.
403 409030 Updating data-driven alert forbidden The user is not authorized to update the data-driven alert.
404 409023 Resource Not Found The data-driven alert ID specified in the URI is invalid.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 Resource Not Found The user ID specified in the request body is invalid.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dataAlerts/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-alert.xml

Content of update-alert.xml:

<tsRequest>
    <dataAlert subject="Data alert - Shipping" frequency="daily" public="true">
        <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
    </dataAlert>
</tsRequest>

Example response:

<tsResponse>
  <dataAlert id="c60bbd4e-dd98-469f-bf71-83c42378f427" subject="Data alert - Shipping"
    creatorId="8eda27d9-5ad2-42cd-a39a-61bc01a423af" createdAt="2018-08-22T23:16:41Z"
    updatedAt="2018-08-24T20:27:14Z" frequency="daily" public="true">
    <owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" name="admin"/>
    <view id="defbf126-5e8b-4c12-9c55-6e772c91bf62" name="Shipping">
      <workbook id="4c384398-085c-4236-91a0-4f92bee1c9ba" name="Superstore"/>
      <project id="291de556-9f2b-11e8-a25f-631b5eb7ad77" name="Default"/>
    </view>
  </dataAlert>
</tsResponse>

Update Database

Update the database description, certify a database, set content permissions, or assign a contact (must be a Tableau Server or Tableau Cloud user) to the database 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/databases/database-luid

Parameter Values

api-version The version of the API to use, such as 3.22. 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.22. 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 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

Introduced in Tableau Cloud June 2022 (API 3.16). Currently not available for Tableau Server.

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

You can use wild cards 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.22/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.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Update Flow

Updates the owner, project, of the specified flow.

URI

PUT /api/api-version/sites/site-id/flows/flow-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
task-id The ID of the flow to update.

Request Body

<tsRequest> <flow> <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3"/> <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/> </flow> </tsRequest>

Attribute Values

new-project-id (Optional) The ID of a project to add the flow to.
new-owner-id (Optional) The ID of a user to assign the flow to as owner.

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

If the <project> element is included, the id attribute must be included, and any other attributes of the <project> element are ignored.

If the <owner> element is included, the id attribute must be included, and any other attributes of the owner are ignored.

Permissions

Tableau Server users who are server administrators or site administrators can change the owner for a flow. Users who are not server administrators can move a flow from one project to another if they own the flow or the current (source) project, or are a project leader for the current project, and they have Writepermission for the destination project.

Response Code

200

Response Body

<tsResponse >
    <flow id="flow-id"
      name="flow-name"
      description="flow-description"
      webpageUrl="flow-url"
      fileType="flow-file-type"
      createdAt="Datetime-created"
      updatedAt="Datetime-updated">
        <project id="project-id" name="project-name"/>
        <owner id="owner-id"/>
    </flow>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.3 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 403098 Owner update forbidden A non-administrator user tried to change the owner for the flow.
403 403030 Project update forbidden A non-administrator user tried to change the project for the flow, but the caller doesn't have Write permission for the project. 
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 Owner not found The owner ID in the request body doesn't correspond to an existing owner. 
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project. 
409 409041 Flow name conflict The flow name in the request already belongs to the specified site. For the purpose of uniqueness checks, flow names are case-insensitive.

For more information, see Handling Errors.

Example

Example response:

<tsResponse version-and-namespace-settings>
    <flow id="flow-id" name="flow-name" description="flow-description" webpageUrl="http://my-server01" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z">
        <project id="6f8a1234-e173-456892f-ffd84c19d7f3" name="testproject"/>
        <owner id="711e45tr-d1c0-554j-be48-3498ae067f7b"/>
    </flow>
</tsResponse>
        

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.

URI

PUT /api/api-version/sites/site-id/flows/flow-id/connections/connection-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the flow.
flow-id The ID of the flow to update.
connection-id The ID of the connection to update. To determine what connections are available for a flow, call Query Flow Connections.

Request Body

<tsRequest>
  <connection
    serverAddress="server-address" serverPort="port"
    userName="connection-username" password="connection-password"
    embedPassword="embed-password" />
</tsRequest>
        

Attribute Values

server-address The new server for the connection.
port The new port for the connection.
connection-username The new username for the connection.
connection-password The new password for the connection.
embed-password trueto embed the password; otherwise, false.

Any combination of the attributes inside the <connection> element is valid. You will need to provide at least one attribute. If no attributes are included, this will result in an error.

Permissions

Only Tableau Server users who are server administrators or site administrators can change the connection for a flow. Users who are not server administrators can update a flow only if they have Write(save) permission for the flow and if they have write permission for the project.

Response Code

200

Response Body

<tsResponse>
  <connection id="connection-id"
    serverAddress="serverAddress" serverPort="port"
    userName="connection-user-name" />
</tsResponse>
        

Version

Version 3.3 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 403103 Update forbidden A non-administrator user tried to update a flow, but the caller doesn't have Write permission.
403 403098 Owner update forbidden A non-administrator user tried to change connection information for the flow, 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 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

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

URI

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

PUT /api/api-version/sites/site-id/groups/group-id?asJob=asJob-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-id The ID of the group to update.
AsJob-value A Boolean value that is used if you are importing from Active Directory. Set this value to true to synchronize with Active Directory as a background task, or set this value to false to synchronize immediately (synchronously). The default is false.

Note: This parameter has no effect if the server is configured to use local authentication.

This attribute is available for Tableau Server only.

Request Body

Updating a local group

<tsRequest>
  <group name="new-group-name"
    minimumSiteRole="minimum-site-role"
    ephemeralUsersEnabled="on-demand-access" />
</tsRequest>
        

When the request is to update a local group and minimumSiteRole is specified, users are granted a license using the grant license on-login mode by default.

Updating an Active Directory group (Tableau Server only)

<tsRequest>
  <group name="AD-group-name">
    <import source="ActiveDirectory" domainName="AD-domain"
      siteRole="minimum-site-role"
      grantLicenseMode="license-mode" />
  </group>
</tsRequest>
        

When the request body contains an <import> element, and if Tableau Server or Tableau Cloud site is configured to authenticate via Active Directory, the Update Group method synchronizes with Active Directory. If Tableau Server is configured to use local authentication, including an <import> element has no effect.

Attribute Values

new-group-name The new name for the group.
AD-group-name

The name of the Active Directory group to synchronize with.

This attribute is available for Tableau Server only.

AD-domain

The domain for the Active Directory group.

This attribute is available for Tableau Server only.

minimum-site-role

Required if an import element or grantLicenseMode attribute are present in the request. The site role assigned to users who are imported from Active Directory (Tableau Server only) or granted a license automatically using the grant license on-sync or on-login mode.

If the requested user name matches an existing user in the group, the user either retains their existing role or are granted the one specified in the request, based on the role that enables the most capabilities. This is true whether the group the user belongs to is imported from Active Directory (Tableau Server only) or local.

Site roles that can be assigned, listed from the one enabling the least capabilities to the most, are as follows.

  1. Unlicensed
  2. Viewer
  3. Explorer
  4. ExplorerCanPublish
  5. Creator
  6. SiteAdministratorExplorer
  7. SiteAdministratorCreator

Note: You cannot use the REST API to set a user to be a Tableau Server administrator (ServerAdministrator site role).

license-mode

Optional. The mode for automatically applying licenses for group members. When the mode is onLogin, a license is granted for each group member when they log in to a site.

For local groups, the mode can be either onLogin or unset. If the attribute is omitted during an update, the group will use the license grant mode configured prior to the update. A local group configured to use onLogin can switch the mode to unset by updating the group using:

minimumSiteRole="UNLICENSED"

For groups that import an Active Directory domain (Tableau Server only), the grantLicenseMode can be updated to either onSync or onLogin. If the attribute is omitted during an update, the group will use the license grant mode configured prior to the update.

The minimum role granted to users through grantLicenseMode is specified in the siteRole attribute of the import element. If that role has less permissions than an existing role assigned to the user, then the user's permissions remain unchanged.

on-demand-access

Optional. A boolean value that is used to enable on-demand access for embedded Tableau content when the Tableau Cloud site is licensed with Embedded Analytics(Link opens in a new window) usage-based model. Set to true to enable the capability for the group or set to false to disable the capability for the group. For more information about on-demand access, see one of the following topics in the Tableau Cloud Help: On-demand access using connected apps with direct trust(Link opens in a new window) or On-demand access using connected apps with OAuth 2.0 trust(Link opens in a new window).

This attribute is available for Tableau Cloud only starting from API version 3.21 (October 2023).

Permissions

This method can only be called by Tableau Server administrators or Tableau Cloud site admins.

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:groups:update

Response Code

200 (immediate update)

202 (background update)

Response Body

Updating a local group:

<tsResponse>
  <group id="new-group-id"
	name="group-name"
	ephemeralUsersEnabled="true"
	minimumSiteRole="minimum-site-role">
         <import domainName="local" siteRole="default-site-role" grantLicenseMode="license-mode"/>
</tsResponse>
      

Updating an Active Directory group (Tableau Server only):

<tsResponse>
  <group id="new-group-id"
	name="group-name">
 	  <import domainName="active-directory-domain-name”
           grantLicenseMode="license-mode"
	    minimumSiteRole="default-site-role" />
  </group>
</tsResponse>
      

Background update:

<tsResponse>
  <job id="job-id"
    mode="Asynchronous"
    type="GroupSync"
    progress="0"
    createdAt="time-job-created" />
</tsResponse>
      

If the operation is performed asynchronously, the response body contains a <job> element that includes a job ID. You can check the status of the operation by using the Query Job method, which returns status information about the job. A typical approach is to periodically call Query Job method and get the value of the progress attribute from the response body; when this value returns 100, the import process is complete.

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 400013 Invalid site role

The value of the minimumSiteRole or siteRole attribute must be Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

403 400019 Malformed import element If the body includes an <import> element, it must contain a source, domainName, and siteRole attribute. If any of these attributes are missing, the element is malformed. In addition, the source attribute must have a value of ActiveDirectory; otherwise the element is malformed.
403 403011 Active Directory not configured The request body contains an <import> element is included, but Tableau Server is configured for local authentication.
403 403020 Imported group name update forbidden The request body contains an <import> element and the value of the name attribute of the <group> element in the request body is different from the name of the group imported into Tableau Server as referenced by the group-id value in the URI.
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 URI doesn't correspond to an existing site.
404 404016 Domain not found The request body includes an <import> element, but the specified domain name doesn't exist in Active Directory.
404 404017 Active Directory group not found The request body includes an <import> element, but no group with the name specified in the <group> element exists in Active Directory.
405 405000 Invalid request method Request type was not PUT.
409 409009 Group name conflict The group name in the request is already in use in the specified site. For the purpose of uniqueness checks, group names are case-insensitive.

For more information, see Handling Errors.

Update Group Set

Updates a group set name on a Tableau Server or Tableau Cloud site.

If a 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 aren’t in the group on Tableau Server are added to the group, and users that aren’t 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 many users, 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).

Version: Available in API 3.22 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:groupsets:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
group-set-id The ID of the group set to update.

Request Body

Copy
<tsRequest>
  <groupSet name="Researchers-one" />
</tsRequest>
Copy
{
  "groupSet": {
    "@name": "Researchers-one"
  }
}

Attribute Values

name The new name for the group set.

Response Code

200 (update)

Response Body

Copy
<tsResponse>
  <groupSet id="group-set-id"
    name="Researchers-one"
    groupCount="2"/>
      <group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
        name="Internal"/>
      <group id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b"
        name="External"/>
  </groupSet>
</tsResponse>
Copy
{
  "groupSet": {
    "id": "group-set-id",
    "name": "Researchers-one",
    "groupCount": "2",
    "group": [
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "name": "Internal"
      },
      {
        "id": "9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b",
        "name": "External"
      }
    ]
  }
}

Updating a local group:

<tsResponse>
  <groupSet id="new-group-set-id"
	name="group-set-name"
	ephemeralUsersEnabled="true"
	minimumSiteRole="minimum-site-role">
         <import domainName="local" siteRole="default-site-role" grantLicenseMode="license-mode"/>
</tsResponse>
      

Updating an Active Directory group set (Tableau Server only):

<tsResponse>
  <groupSet id="new-group-id"
	name="group-set-name">
 	  <import domainName="active-directory-domain-name”
           grantLicenseMode="license-mode"
	    minimumSiteRole="default-site-role" />
  </groupSet>
</tsResponse>
      

Background update:

<tsResponse>
  <job id="job-id"
    mode="Asynchronous"
    type="GroupSync"
    progress="0"
    createdAt="time-job-created" />
</tsResponse>
      

If the operation is performed asynchronously, the response body contains a <job> element that includes a job ID. You can check the status of the operation by using the Query Job method, which returns status information about the job. A typical approach is to periodically call Query Job method and get the value of the progress attribute from the response body; when this value returns 100, the import process is complete.

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 400013 Invalid site role

The value of the minimumSiteRole or siteRole attribute must be Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer.

403 400019 Malformed import element If the body includes an <import> element, it must contain a source, domainName, and siteRole attribute. If any of these attributes are missing, the element is malformed. In addition, the source attribute must have a value of ActiveDirectory; otherwise the element is malformed.
403 403011 Active Directory not configured The request body contains an <import> element is included, but Tableau Server is configured for local authentication.
403 403020 Imported group name update forbidden The request body contains an <import> element and the value of the name attribute of the <group> element in the request body is different from the name of the group imported into Tableau Server as referenced by the group-id value in the URI.
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 URI doesn't correspond to an existing site.
404 404016 Domain not found The request body includes an <import> element, but the specified domain name doesn't exist in Active Directory.
404 404017 Active Directory group not found The request body includes an <import> element, but no group with the name specified in the <group> element exists in Active Directory.
405 405000 Invalid request method The request type wasn’t PUT.
409 409009 Group name conflict

The group name in the request is already in use in the specified site. For the purpose of uniqueness checks, group names are case-insensitive.

409 409120 Group set not found. The group set ID in the request body doesn't correspond to an existing group set.

For more information, see Handling Errors.

Update Identity Pool

Update information about an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

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.22. 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 Cloud. Must be 1-24 characters long in Tableau Server.
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 category 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 Cloud.
  • The category name must be 1-24 characters long in Tableau Server.
  • 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. (An asset can be Tableau content or an external asset.) Each asset listed in the request body is updated to have a label with the specified value, message, active flag, and elevated flag.

On Tableau Cloud: 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.

On Tableau Server: 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: The ability for an asset to have more than one label with the same category was introduced in Tableau Cloud February 2024, and doesn't yet exist in Tableau Server.

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

On Tableau Cloud: 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.

On Tableau Server: 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

The message text for the label. In the web interface, this is reflected as a certification note or a data quality warning message. The message is optional in Tableau Cloud, but required in Tableau Server.

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.

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

Must be 1-128 characters long in Tableau Cloud. Must be 1-24 characters long in Tableau Server.

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 Cloud.
  • The updated label value name must be 1-24 characters long in Tableau Server.
  • 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.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can create a metric in a definition as long as the user has write or publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:update
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.

URI

PUT /api/api-version/sites/site-id/metrics/metric-luid

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
metric-luid The unique ID of the data source to update.

Request Body

                    <tsRequest>
  <metric
	description="updated-metric-description"
    name="updated-name"
	suspended="updated-suspended-flag" >
      <project id="updated-project-id"/>
      <owner id="updated-owner-id"/>
  </metric>
</tsRequest>
        

Attribute Values

updated-metric-description (Optional) The description to use for the updated metric.
updated-metric-name (Optional) The name to use for the updated metric.
updated-suspended-flag (Optional) Boolean. If true the metric is suspended. The default is false.
updated-project-id (Optional) The ID of a project to add the metric to.
updated-owner-id (Optional) The ID of a user to assign the metric to as owner.

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

If the <project> element is included, the id attribute must be included, and any other attributes of the <project> element are ignored.

If the <owner> element is included, the id attribute must be included, and any other attributes of the owner are ignored.

Permissions

Tableau users who are server or site administrators can change the owner for a metric. Users who are not administrators can move a metric from one project to another if they have permissions to the metric. The user must also have permissions to the current (source) project or are a project leader for the current project, and have Write permission for the destination project.

tableau:metrics:update

Response Code

200

Response Body

                    <tsResponse>
  <metric id="metric-id"
	name="metric-name"
	description="metric-description"
	webpageUrl="webpageUrl-url"
	createdAt="datetime-created"
	updatedAt="datetime-updated"
	suspended="suspended-flag"">
	  <project id="new-project-id" />
	  <owner id="new-owner-id" />
	  <tags>
	    <tag label="tag"/>
	    <!--  ... additional tags ... -->
	  </tags>
	</metric>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 2.0 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 400123 Unkown error The metric could not be updated for an unknown reason.
403 403119 Owner update forbidden The user does not have administrator permissions to change the owner for the metric.
403 403120 Project update forbidden The user doesn't have Write permission for the project they are trying to move the metric to.
403 403118 Name update forbidden The user does not have administrator permissions to change the name for the metric.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 Owner not found The owner ID in the request body doesn't correspond to an existing owner.
404 404004 Metric not found The metrice ID in the URI doesn't correspond to an existing metric.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not PUT.
409 409015 Metric name conflict The metric name in the request already belongs to the specified site. For the purpose of uniqueness checks, metric names are case-insensitive.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics/6561daa3-20e8-407f-ba09-709b178c0b4a" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-metric.xml

Content of update-metric.xml

                        <tsRequest>
   <metric
    name="New Name"
    description="New Description"
    suspended="true">
	  <project id="49b4cce3-771f-4ee3-a932-5d42fa8c0e9d"/>
	 <owner id="f1539d08-114c-4de9-a830-c9a0674ec026"/>
  </metric>
</tsRequest>
          

Example response body:

                    <tsResponse >
  <metric id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
    name="my first metric"
    description="Description of my_first_metric."
    webpageUrl="https://MY-SERVER/#/site/site-name/metrics/site-num"
    createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
    suspended="false" >
 	    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
    	<owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
   	  <tags/>
      underlyingView="29dae0cd-1862-4a20-a638-e2c2dfa682d4"
  </metric>
</tsResponse>
        

Update metric definition

Updates a metric definition.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview

Permissions: Any user can create a metric definition as long as the user has write or publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions:update
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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

view details

Update Mobile Security Settings for Site

Updates the mobile security sections for a specified site.

Version: Available in API 3.18 (Tableau Cloud December 2022) and later. Not available for Tableau Server. Version Overview

License: No additional license required.

Permissions: Only Tableau server administrators can update mobile security settings for the server.  Permissions Overview

JWT Access Scope: Not available.     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

PUT /api/api-version/settings/mobilesecuritysettings

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Copy
{
    "mobileSecuritySettingsList": {
        "mobileSecuritySettings": [
            {
                "name": "mobile.security.jailbroken_device",
                "enabled": true,
                "iosConfig": {
                    "valueList": [
                        "true"
                    ],
                    "severity": "warn"
                },
                "androidConfig": {
                    "valueList": [
                        "false"
                    ],
                    "severity": "critical"
                }
            },
            {
                "name": "mobile.security.malware_detection",
                "enabled": true,
                "iosConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                    },
                "androidConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                }
            },
            {
                "name": "mobile.security.max_offline",
                "enabled": true
                "iosConfig": {
                    "valueList": [
                        "14"
                    ],
                    "enabled": true,
                    "severity": "critical"
                },
                "androidConfig": {
                    "valueList": [
                        "14"
                    ],
                    "enabled": true,
                    "severity": "critical"
                },
            },        
            {
                "name": "mobile.security.screenshot",
                "enabled": false,
                "androidConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                }
            }
        ]
    }
}

Request Attributes

mobileSecuritySettings name

(Optional)Enum. The device condition addressed by a security setting element. Supported values are:

  • mobile.security.jailbreak_detection
  • mobile.security.malware_detection
  • mobile.security.max_offline
    Available in API 3.19 (Tableau Cloud March 2023 / Server 2023.1) and later.
  • mobile.security.screenshot
mobileSecuritySettings enabled (Optional) Boolean. If true, enables the Tableau mobile client to detect and respond to the condition described in the setting's name. The enabled attribute for the Android or iOS configuration element of the setting must also be true for detection on that type of device. If mobileSecuritySettings enabled = false, the Android and iOS configuration element attribute settings will be ignored.
mobileSecuritySettings androidConfig / iosConfig

(Optional)Element. Security settings specific to the platform of the mobile device hosting the Tableau client for the setting being configured. Required attributes of this element are:

  • valueList -

    In the case of mobile.security.max_offline String - whole number. The number of days a device can be offline without requiring a security policy refresh. Minimum value is 1, default value is 14.

    In other cases String - true or false. Determines if the condition of the setting is detected for the specified platform.

  • severity - Enum. Defines the response of the Tableau mobile client when the condition of the setting is detected.
  • enabled - String -true or false. On the device type being configured, if true, enables detection of the containing setting's security condition, as long as that setting's enabled attribute value is also true.

    Severity level can be set for jailbreak and malware detection settings. The levels and the actions the Tableau client will take are as follows:

    • Warn: If a detection occurs, show a dismissible blocking screen.
    • Error: If a detection occurs, show a blocking screen until the issue is resolved.
    • Critical: If a detection occurs, shows a blocking screen, log the user out, and close the session.

    If screenshot protection is enabled a severity level is required, but regardless of which level you select the behavior of the app will be: If a screenshot is attempted, show a temporary toast without blocking the app.

    Default settings for a Tableau Cloud site are:

    • Jailbreak detection enabled with critical severity.
    • Malware detection enabled with critical severity.
    • Maximum offline time for security policy update set at 14 days with critical severity.
    • Screenshot protection is enabled with warn level.

cURL Request Example

curl -L -X PUT "https://qa-server.tsi.lan/api/3.18/settings/mobilesecuritysettings" -H "Accept: application/json" -H "X-Tableau-Auth: ejET2rVmS2e81XiZ9G4lzQ|Iz71DR2lu3r0zHpcOAH2OoRQZlPfxACC|a905dbfd-6550-4546-908b-3e055fcc026d" --data-raw ""

Response Code

200

Response Body

Copy
<tsResponse>
    <mobileSecuritySettingsList>
        <mobileSecuritySettings name="mobile.security.jailbroken_device" enabled="true">
            <iosConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </iosConfig>
            <androidConfig severity="critical" enabled="false">
                <valueList>false</valueList>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name="mobile.security.malware_detection" enabled="true">
            <iosConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </iosConfig>
            <androidConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name ="mobile.security.max_offline" enabled="true">
            <iosConfig enabled="true" severity="critical">
                <valueList>14</valuelist>
            </iosConfig>
            <androidConfig enabled="true" severity="critical">
                <valueList>14</valuelist>
            </androidConfig>
        </mobileSecuritySettings>
        <mobileSecuritySettings name="mobile.security.screenshot" enabled="false">
            <androidConfig severity="warn" enabled="false">
                <valueList>true</valueList>
            </androidConfig>
        </mobileSecuritySettings>
    </mobileSecuritySettingsList>
</tsResponse>

Copy
{
    "mobileSecuritySettingsList": {
        "mobileSecuritySettings": [
            {
                "name": "mobile.security.jailbroken_device",
                "enabled": true,
                "iosConfig": {
                    "valueList": [
                        "true"
                    ],
                    "severity": "warn"
                },
                "androidConfig": {
                    "valueList": [
                        "false"
                    ],
                    "severity": "critical"
                }
            },
            {
                "name": "mobile.security.malware_detection",
                "enabled": true,
                "iosConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                    },
                "androidConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                }
            },
            {
                "name": "mobile.security.max_offline",
                "enabled": true
                "iosConfig": {
                    "valueList": [
                        "14"
                    ],
                    "enabled": true,
                    "severity": "critical"
                },
                "androidConfig": {
                    "valueList": [
                        "14"
                    ],
                    "enabled": true,
                    "severity": "critical"
                },
            },        
            {
                "name": "mobile.security.screenshot",
                "enabled": false,
                "androidConfig": {
                    "valueList": [
                        "true"
                    ],
                    "enabled": true,
                    "severity": "warn"
                }
            }
        ]
    }
}

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 OpenID Connect Configuration

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

Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server.Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Tableau Cloud site admins only.

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/site-oidc-configuration

URI Parameter Values

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

Request Body

Copy
<tsRequest>
  <siteOIDCConfiguration
    enabled="enabled"
    clientId="clientId"
    clientSecret="clientSecret"
    authorizationEndpoint="authorizationEndpoint"
    tokenEndpoint="tokenEndpoint"
    userinfoEndpoint="userinfoEndpoint"
    jwksUri="jwksUri"
    endSessionEndpoint="endSessionEndpoint"
    allowEmbeddedAuthentication="allowEmbeddedAuthentication"
    prompt="prompt"
    customScope="customScope"
    clientAuthentication="clientAuthentication"
    essentialAcrValues="essentialAcrValues"
    voluntaryAcrValues="voluntaryAcrValues"
    emailMapping="emailMapping"
    firstNameMapping="firstNameMapping"
    lastNameMapping="lastNameMapping"
    fullNameMapping="fullNameMapping"
    useFullName="useFullName" />
</tsRequest>

Copy
{
  "siteOIDCConfiguration": {
    "enabled": "enabled",
    "clientId": "clientId",
    "clientSecret": "clientSecret",
    "authorizationEndpoint": "authorizationEndpoint",
    "tokenEndpoint": "tokenEndpoint",
    "userinfoEndpoint": "userinfoEndpoint",
    "jwksUri": "jwksUri",
    "endSessionEndpoint": "endSessionEndpoint",
    "allowEmbeddedAuthentication": "allowEmbeddedAuthentication",
    "prompt":"prompt",
    "customScope":"customScope",
    "clientAuthentication": "clientAuthentication",
    "essentialAcrValues": "essentialAcrValues",
    "voluntaryAcrValues": "voluntaryAcrValues",
    "emailMapping": "emailMapping",
    "firstNameMapping": "firstNameMapping",
    "lastNameMapping": "lastNameMapping",
    "fullNameMapping": "fullNameMapping",
    "useFullName": "useFullName"
    }
}

Request Attributes

Note: Because partial updates are not supported therefore, you must include all the needed attributes in your request to ensure the configuration update is completed successfully.

enabled (Required) Controls whether the configuration is enabled or not. Value can be "true" or "false". For example "true".
clientId (Required) The client ID from your IdP. For example, "0oa111usf1gpUkVUt0h1".
clientSecret (Required) The client secret from your IdP.
authorizationEndpoint (Required) Use the authorization endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (authorization_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/authorize".
tokenEndpoint (Required) Use the token endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the token endpoint (token_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/token".
userinfoEndpoint (Required) Use the user information endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (userinfo_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/userinfo".
jwkUri (Required) Use the JWK set URI from your IdP. To find the value, enter the configuration URL in a browser and obtain the JWK set URI endpoint (jwks_uri) from the details that are returned. For example, "https://myidp.com/oauth2/v1/keys".
endSessionEndpoint (Optional) If single logout (SLO) is enabled for the site, which is done through Tableau Cloud site UI, you can specify the configuration URL or the end session endpoint from your IdP. For example, "https://myidp.com/oauth2/v1/logout".
allowEmbeddedAuthentication (Optional) Controls how users authenticate when accessing embedded views. Value can be "true" or "false". Default value is "false", which authenticates users in a separate pop-up window. When set to "true", users authenticate using an inline frame (IFrame), which is less secure.
customScope (Optional) Specifies a custom scope user-related value that you can use to query the IdP. For example, "openid, email, profile".
prompt (Optional) Specifies whether the user is prompted for re-authentication and consent. For example, "login, consent".
clientAuthentication (Optional) Token endpoint authentication method. Value can be "client_secret_basic" or "client_secret_post". Default value is "client_secret_basic".
essentialAcrValues (Optional) List of essential Authentication Context Reference Class values used for authentication. For example, "phr".
voluntaryAcrValues (Optional) List of voluntary Authentication Context Reference Class values used for authentication.
emailMapping (Optional) Claim for retrieving email from the OIDC token. Default value is "email".
firstNameMapping (Optional) Claim for retrieving first name from the OIDC token. Default value is "given_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false".
lastNameMapping (Optional) Claim for retrieving last name from the OIDC token. Default value is "family_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false".
fullNameMapping (Optional) Claim for retrieving name from the OIDC token. Default value is "name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "true".
useFullName (Optional) Controls what is used as the display name. Value can be "true" or "false". Default value is "false", which uses first name (firstNameMapping attribute) and last name (lastNameMapping attribute) as the user display name. When set to "true", full name (fullNameMapping attribute) is used as the user display name.

cURL Request Example

curl "https://us-west-2a.online.tableau.com/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuratioin" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-update-oidc-config.xml

Content of create-update-oidc-config.xml:

Copy
<tsRequest>
  <siteOIDCConfiguration
    enabled="enabled"
    clientId="clientId"
    clientSecret="clientSecret"
    authorizationEndpoint="authorizationEndpoint"
    tokenEndpoint="tokenEndpoint"
    userinfoEndpoint="userinfoEndpoint"
    jwksUri="jwksUri"
    endSessionEndpoint="endSessionEndpoint"
    allowEmbeddedAuthentication="allowEmbeddedAuthentication"
    prompt="prompt"
    customScope="customScope"
    clientAuthentication="clientAuthentication"
    essentialAcrValues="essentialAcrValues"
    voluntaryAcrValues="voluntaryAcrValues"
    emailMapping="emailMapping"
    firstNameMapping="firstNameMapping"
    lastNameMapping="lastNameMapping"
    fullNameMapping="fullNameMapping"
    useFullName="useFullName" />
</tsRequest

Response Code

200

Response Body

Copy
<tsResponse>
  <siteOIDCConfiguration
    enabled="true" 
    testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
    allowEmbeddedAuthentication="false"
    clientId="0oa111usf1gpUkVUt0h1" 
    clientSecret="&lt;omit>"
    authorizationEndpoint="https://myidp.com/oauth2/v1/authorize"
    tokenEndpoint="https://myidp.com/oauth2/v1/token"
    userinfoEndpoint="https://myidp.com/oauth2/v1/userinfo"
    jwksUri="https://myidp.com/oauth2/v1/keys"
    endSessionEndpoint="https://myidp.com/oauth2/v1/logout"
    customScope="openid, email, profile"
    prompt="login,consent"
    clientAuthentication="client_secret_basic"
    essentialAcrValues="phr"
    emailMapping="email"
    firstNameMapping="given_name"
    lastNameMapping="family_name"
    fullNameMapping="name"
    useFullName="false" />
</tsResponse>
Copy
{tsRequest:
}

Notes:

  • The response hides the client secret and replaces it with &lt;omit>.

  • You can use the testloginURL to validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.

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.

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.

Version: Available in API 1.0 and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Only Tableau Administrators can update a project.   Permissions Overview(Link opens in a new window)

JWT Access Scope:      tableau:projects:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

URI

PUT /api/api-version/sites/site-id/projects/project-id

PUT /api/api-version/sites/site-id/projects/project-id?publishSamples=publish-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
project-id The ID of the project to update.
publish-value (Optional) A Boolean value that specifies whether to publish the sample workbooks provided by Tableau to the project when you update the project. When the publish-value is not specified in the request, or the publishSamples parameter is missing, no samples will be published. To publish the sample workbooks, set publishSamples parameter to true. This option is equivalent to the tabcmd command-line utility option, publishsamples. For more information, see tabcmd(Link opens in a new window).

Request Body

Copy
<tsRequest>
  <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
    parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
    name="Update-Project-Name"
    description="This is the new description after the project update"
    contentPermissions="ManagedByOwner"
    controllingPermissionsProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" >
      <owner id="abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"/>
  </project>
</tsRequest>

Copy
{
  "project": {
    "id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
    "parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
    "name": "Update-Project-Name",
    "description": "This is the new description after the project update",
    "contentPermissions": "ManagedByOwner",
    "controllingPermissionsProjectId": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
    "owner": {
      "id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
    }
  }
}

Attribute Values

project id

(Required) The LUID of the project being updated.

For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults Windows(Link opens in a new window) | Linux(Link opens in a new window).

project name (Optional) The new name for the project.
project description (Optional) The new description for the project.
project parentProjectId

(Optional) The new identifier of the parent project. Use this option to create or change project hierarchies.

To update a project without changing its placement in the project hierarchy, omit the parentProjectId attribute. To move a project to the top of the project hierarchy, provide an empty string ("") for the parentProjectId attribute.

For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults.

project contentPermissions

(Optional) This value controls user permissions in a project, however, if the project is nested within a project with more restrictive policies, it will inherit those permissions and these settings will have no effect. The functional permissions of a project, including those it inherits, are available in value of contentPermission in the response body from a request to create, update, or query a project.

  • LockedToProject to lock permissions so that users cannot overwrite the default permissions set for the project
  • ManagedByOwner to allow users to manage permissions for content that they own
  • LockedToProjectWithoutNested to lock the permissions of a parent project, but not those of its child projects.

The default is ManagedByOwner. For more information, see Lock Content Permissions(Link opens in a new window).

project parentProjectId

(Optional) The new identifier of the parent project. Use this option to create or change project hierarchies.

To update a project without changing its placement in the project hierarchy, omit the parentProjectId attribute. To move a project to the top of the project hierarchy, provide an empty string ("") for the parentProjectId attribute.

For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults.

owner id The LUID of the user that owns the project.

cURL Example

curl --request PUT "https://myServer/api/3.21/sites/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/projects/ds2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e70" --header "Content-Type: application/xml" --header "X-Tableau-Auth;" --data "<tsRequest> <project parentProjectId='ab2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5ee0' name='new-name' description='new-description' contentPermissions='ManagedByOwner' /> </tsRequest>"

Response Code

200

Response Body

Copy
<tsResponse>
  <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
    parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
    name="Update-Project-Name"
    description="This is the new description after the project update"
    contentPermissions="ManagedByOwner"
    controllingPermissionsProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" >
      <owner id="abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"/>
  </project>
</tsResponse>

Copy
{
  "project": {
    "id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
    "parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
    "name": "Update-Project-Name",
    "description": "This is the new description after the project update",
    "contentPermissions": "ManagedByOwner",
    "controllingPermissionsProjectId": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
    "owner": {
      "id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
    }
  }
}

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 400008 Bad request The request cannot set content permissions to LockedToProjectWithoutNested for a REST API version lower than 3.8.
403 403005 Update forbidden Attempt to rename the default project, which cannot be renamed.
403 403008 Insufficient storage on site The samples could not be published because there is not enough storage space remaining on the server to accommodate the samples.
403 403004 Update forbidden A non-administrative user tried to update the project, but does not have permissions to update the project.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404009 Project ID mismatch The request body contains a project ID (which is optional) and it doesn't match the ID in the URI.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not PUT.
409 409006 Project name conflict The project name in the request already belongs to the specified site. For the purpose of uniqueness checks, project names are case-insensitive.

For more information, see Handling Errors.

Update Quality Warning Trigger

Update a quality warning trigger.

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

Request Body

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

Attribute Values

Any combination of attributes inside the <dataQualityTrigger> element is valid, however type is required.

type

Type of content to apply the data quality warning trigger. To specify the type, use one of the following values:

  • EXTRACT_REFRESH
  • FLOW_RUNS

These values are case sensitive.

status

(Optional) Status of the trigger. Values can be "true" or "false". If set to "true", the extract data source is monitored for refresh failures. If a refresh failure occurs, an alert is applied to the extract data source. The alert remains there until the next successful refresh. 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 to accompany the trigger.
severity (Optional) Enables high visibility for the trigger. 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 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

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 quality warning trigger 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 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.22. 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.22/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 .

URI

PUT /api/api-version/schedules/schedule-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
schedule-id The ID of the schedule to update. To determine what schedules are available, call List Server Schedules.

Request Body

<tsRequest>
  <schedule
    name="new-schedule-name"
    priority="new-schedule-priority"
    frequency="new-schedule-frequency"
    state="new-state"
    executionOrder="new-schedule-execution-order">
    <frequencyDetails start="start-time" end="end-time">
     <intervals>
        <interval interval-expression />
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>
        

Attribute Values

new-schedule-name The new name to give to the schedule.
new-schedule-priority An integer value between 1 and 100 that determines the default priority of the schedule if multiple tasks are pending in the queue. Lower numbers have higher priority.
new-schedule-execution-order Parallel to allow jobs associated with this schedule to run at the same time, or Serial to require the jobs to run one after the other.
new-schedule-frequency The granularity of the schedule. Valid values are:
  • Hourly. Hourly. Jobs can be scheduled to run one or more times per day at intervals specified in minutes or hours. Valid intervals are 15 and 30 minutes and 2, 4, 6, 8, and 12 hours.
  • Daily. Jobs can be scheduled to run once per day.
  • Weekly. Jobs can be scheduled to run one or more times per week.
  • Monthly. Jobs can be scheduled to run once per month on a specific day.

The value you provide for schedule-frequency determines whether you must include an end-time value, and what is required in the contents of the <intervals> element.

new-state Active to enable the schedule, or Suspended to disable it.
start-time The time of day on which scheduled jobs should run (or if the frequency is hourly, on which they should start being run), in the format HH:MM:SS (for example, 18:30:00). This value is required for all schedule frequencies. The entered time will be applied based on the time zone of your server.
end-time If the schedule frequency is Hourly, the time of day on which scheduled jobs should stop being run, in the format HH:MM:SS (for example, 23:30:00). Hourly jobs will occur at the specified intervals between the start time and the end time. For other schedule frequencies, this value is not required; if the attribute is included, it is ignored. The entered time will be applied based on the time zone of your server.
interval-expression A value that specifies the interval between jobs associated with the schedule. The value you specify here depends on the value of schedule-frequency.

Hourly

The interval expression is only one of the following:

  • hours="interval" where interval is 1, 2, 4, 6, 8, or 12, representing how many hours between jobs.
  • minutes="interval" where interval is 15 or 30, representing how many minutes between jobs.

You can specify an interval in hours or minutes, but not both.

Daily

If the schedule frequency is Daily, no interval is specified. Any information specified in the <intervals> element is ignored.

Weekly

The interval expression is weekDay="weekday", where weekday is Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

You can specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week.

Note: Updating a schedule without specifying days of the week will reset any existing weekly interval to include all 7 days. If you need the job you are updating to remain scheduled on selected days, make sure to include that information in your update request.

Monthly

The interval expression is monthDay="day", where day is either the day of the month (1, 2, etc.) or LastDay.

Note: If you want to specify multiple days in the month, you can do this using the web interface. You cannot create or update such a monthly schedule using REST API.

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

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

<tsResponse>
  <schedule id="schedule-id"
        name="schedule-name"
        state="new-state"
        priority="schedule-priority"
        createdAt="datetime-created"
        updatedAt="datetime-updated"
        type="Extract-or-Subscription"
        frequency="schedule-frequency"
        nextRunAt="datetime-next-run"
        endScheduleAt ="datetime-expiration"
        executionOrder="Parallel-or-Serial">
        <frequencyDetails frequency-expression >
            <intervals>
               <interval interval-expression />
             </intervals>
        </frequencyDetails>
  </schedule>
</tsResponse>
        

Version

Version 2.3 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 400008 Invalid Parameter One of the parameters in the request body is invalid.
400 400071 Error updating schedule The schedule couldn't be updated for an unspecified reason.
404 404023 Schedule not found The specified schedule doesn't correspond to an existing schedule.
405 405000 Invalid request method Request type was not PUT.
409 409021 Schedule name conflict The schedule name in the request already belongs to an existing schedule.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/schedules/4d652179-36bf-47e4-a9dc-e069227c72d0" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-schedule.xml


Content of update-schedule.xml for an hourly schedule

For an hourly schedule, frequencyDetails is set to Hourly. Both start and end values are required. The intervals element is required, and must include 1 interval subelement that contains either an hours or a minutes attribute. Valid values for minutes are 15 or 30. Valid values for hours are 1, 2, 4, 6, 8, or 12.

<tsRequest>
  <schedule name="hourly-schedule-1"
        priority="50"
        type="Extract"
        frequency="Hourly"
        executionOrder="Parallel">
      <frequencyDetails start="18:30:00" end="23:00:00">
        <intervals>
          <interval hours="2" />
        </intervals>
      </frequencyDetails>
   </schedule>
</tsRequest>

Response body

<tsResponse <span class="api-placeholder">version-and-namespace-settings</span>>
  <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0"
       name="hourly-schedule-1"
       state="Active"
       priority="50"
       createdAt="2016-05-07T01:51:19Z"
       updatedAt="2016-05-07T01:51:19Z"
       type="Extract"
       frequency="Hourly"
       nextRunAt="2016-05-07T03:30:00Z"
       endScheduleTime="2016-06-07T12:00:00Z"
       executionOrder="Parallel">
    <frequencyDetails start="18:30:00" end="23:00:00">
      <intervals>
          <interval hours="2" />
      </intervals>
   </frequencyDetails>
  </schedule>
</tsResponse>
        

Note: For additional examples of how to construct the payload for updating schedules, see Create Schedule.

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.


Updates the settings of a specific dashboard extension in the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) Version Overview

Permissions: Can only be called by users with site or server administrator Permissions Overview

License: No additional license required.

Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux

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.22. 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"
	webExtractionEnabled="web-extraction-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" />
</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 does not 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 do not 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 do not 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 possible number of users is set by the licenses activated on that server. For core-based licensing, there is 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 premise 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 premise 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.

web-extraction-enabled-flag

(Optional, boolean) If true, web extraction 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.

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 a 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 are 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" />
  </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 is not 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 was not 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 cannot set both tiered capacity attributes and userQuota. One or the other must be null.
409 409004 License limit exceeded The request cannot 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 cannot set adminMode to ContentOnly and also specify a userQuota value.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/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.

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.

URI

PUT /api/api-version/sites/site-id/subscriptions/subscription-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
subscription-id The ID of the subscription to update.

JWT Access Scope

tableau:tasks:update (this scope is included in the scope: tableau:tasks)

This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

Tableau Server Request

Update the attributes of a subscription task on a server schedule on Tableau Server.
For Tableau Cloud, see Tableau Cloud Request.

Copy
<tsRequest>
  <subscription
    subject="subscription-subject"
    attachImage="attach-image-flag"
    attachPdf="attach-pdf-flag"
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option"
    suspended="suspended-flag">
      <schedule id="new-schedule-id"
      <content sendIfViewEmpty="send-view-if-empty-flag" />
  </subscription>
</tsRequest>
Copy
{
  "subscription": {
    "subject": "subscription-subject",
    "attachImage": "attach-image-flag",
    "attachPdf": "attach-pdf-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "suspended": "suspended-flag",
    "schedule": {
      "id": "new-schedule-id"
    },
    "content": {
      "sendIfViewEmpty": "send-view-if-empty-flag"
    }
  }
}

Attribute Values

>
new-subscription-subject (Optional) A new subject for the subscription.
attach-image-flag

(Optional) Setting this true will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither attachImage or attachPdf are specified.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachImage to false will cause an error.

attach-pdf-flag

(Optional) Setting this true will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachPdf to true will cause an error.

page-orientation (Optional) The orientation of the pages produced when attach-pdf-flag is true. The value can be Portrait or Landscape. If this parameter is not present the page orientation will default to Portrait.
page-size-option (Optional) The type of page produced, which determines the page dimensions when attach-pdf-flag is true. The value can be: A3, A4, A5, B5, Executive, Folio, Ledger, Legal, Letter, Note, Quarto, or Tabloid. If this parameter is not present the page type will default to Letter.
suspended-flag (Optional boolean) Setting suspended to true stops email delivery for the specified subscription. Setting it to false will resume email delivery for the subscription.
new-schedule-id (Optional) The ID of a server schedule to associate this subscription with. To determine what schedules are available, call List Server Schedules. The type of the schedule must be Subscription.
send-view-if-empty-flag(Optional) Applies to views only. If true, an image is sent even if the view specified in a subscription is empty. If false, nothing is sent if the view is empty. The default value is true.

Permissions

Tableau Server users can call this method to update any subscription that they have permission to create. For details, see Create Server Subscription.

Response Code

200

Response Body

XML

Copy
<tsResponse>
  <subscription id="subscription-id"
    subject="subscription-subject"
    suspended="suspended-flag"    
    pageOrientation="page-orientation"
    pageSizeOption="page-size-option" >
      <content id="content-id"
        type="content-type"
        sendIfViewEmpty="send-view-if-empty-flag"/>
      <schedule id="schedule-id" name="schedule-name" />
      <user id="user-id" name="user-name" />
  </subscription>
</tsResponse>

JSON

Copy
{
  "subscription": {
    "id": "subscription-id",
    "subject": "subscription-subject",
    "suspended": "suspended-flag",
    "pageOrientation": "page-orientation",
    "pageSizeOption": "page-size-option",
    "content": {
      "id": "content-id",
      "type": "content-type",
      "sendIfViewEmpty": "send-view-if-empty-flag"
    },
    "schedule": {
      "id": "schedule-id",
      "name": "schedule-name"
    },
    "user": {
      "id": "user-id",
      "name": "user-name"
    }
  }
}

Version

Version 2.3 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 400067 Invalid subscription subject The subscription subject is null or empty.
400 400069 Invalid subscription type The subscription type is not Workbook or View.
400 400069 Invalid schedule type The schedule type is not Subscription.
400 400133 Invalid data condition type The data condition type is invalid for the subscription.
403 403065 No permissions to update subscription. The user does not have permission to update the specified subscription.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404023 Schedule not found The schedule ID in the request body doesn't correspond to an existing schedule.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Tableau Cloud Request

Update the attributes of a subscription task and its frequency on Tableau Cloud.
For Tableau Server, see Tableau Server Request.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Administrators and any user with the creator role can create a custom schedule for a subscription task.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:tasks:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/subscriptions/task-luid

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.
task-luid The LUID of the extract refresh task. Use Query subscriptions to find task IDs by subscription subject or user.

Request Body

Copy
<tsRequest>
  <subscription 
  subject="finance report" 
  attachImage="true" 
  attachPdf="true" 
  pageOrientation="true" 
  pageSizeOption="Folio" 
  message="Daily finance report"> 
    <content id="13237fd-6365-44d5-925b-644e5281b605"
      type="Workbook" 
      sendIfViewEmpty="false"/> 
    <user id="6t543fd-6365-44d5-925b-644e52897y65"/>
  </subscription>
  <schedule frequency="Daily">
    <frequencyDetails start="18:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Sunday"/>
        <interval weekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Copy
{
  "subscription": {
    "subject": "finance report",
    "attachImage": "true",
    "attachPdf": "true",
    "pageOrientation": "true",
    "pageSizeOption": "Folio",
    "message": "daily finance report",
    "content": {
      "id": "13237fd-6365-44d5-925b-644e5281b605",
      "type": "Workbook",
      "sendIfViewEmpty": "false"
    },
    "user": {
      "id": "456"
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]

      }
    }
  }
}

Request Attributes

subject, contentId, userId and all schedule attributes are required to create a custom schedule for a subscription, other attributes are optional with defaults. All attributes are optional when updating a custom schedule for a subscription.

subscription subject (Required to create subscription) string: A description for the subscription. This description is displayed when users list subscriptions for a site in the server environment.
subscription attachImage

boolean: Setting this true will cause the subscriber to receive mail with .png images of workbooks or views attached to it. This is the default behavior if neither attachImage or attachPdf are specified. Default is false.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachImage to false will cause an error.

subscription attachPdf

boolean: Setting this true will cause the subscriber to receive mail with a .pdf file containing images of workbooks or views attached to it. Default is false.

If subscriptions to attachments are disabled in Tableau server or site settings, then making a request that sets attachPdf to true will cause an error.

subscription pageOrientation enumeration: The orientation of the pages produced when attach-pdf-flag is true. The value can be Portrait or Landscape. If this parameter is not present the page orientation will default to Portrait.
subscription pageSizeOption enumeration: The type of page produced, which determines the page dimensions when attach-pdf-flag is true. The value can be: A3, A4, A5, B5, Executive, Folio, Ledger, Legal, Letter, Note, Quarto, or Tabloid. If this parameter is not present the page type will default to Letter.
subscription message string: The text body of the subscription email message.
content id (Required to create subscription) LUID: The LUID of the workbook or view the user should be subscribed to.
content type (Required to create subscription) enumeration: Workbook to create a subscription for a workbook, or View to create a subscription for a view.
content sendIfViewEmpty boolean: Applies to views only. If true, an image is sent even if the view specified in a subscription is empty. If false, nothing is sent if the view is empty. The default value is true.
userId (Required to create subscription) LUID: The LUID of the user to create the subscription for.

Note: The user must have an email address defined in Tableau Server.

schedule frequency (Required to create subscription) enumeration: The scheduled frequency for triggering the extract refresh. Valid values include:
  • Hourly
  • Daily
  • Weekly
  • Monthly
frequencyDetails start (Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.
frequencyDetails end

(Required to create subscription) time: If the schedule frequency is Hourly, or Daily with an interval of hours less than 24, then end is the time of day on which scheduled jobs should stop being run. The valid format is HH:MM:SS. Time should be specified in 5 minute increments and the difference between start and end times should be increments of 60 minutes. For example, a valid frequencyDetail would be:

<frequencyDetail start="20:45:00" end="21:45:00">
  . . . 
</frequencyDetail>
interval {interval type} (Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in the start and end values of the frequencyDetails of the schedule. The type and valid values for an interval expression depend on the declared frequency of the schedule as follows:

FrequencyValid interval values
Hourly The value of an interval for an Hourly schedule can be only one of either:
  • hours=“1" The number of hours between jobs. 1 is the only valid value.
  • minutes=“60" The number of minutes between jobs. 60 is the only valid value.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday.

    For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="1"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
    <intervals>

Daily The value of Daily can have multiple weekday elements, but only one hours declaration. An hours interval is required.
  • hours=“interval" The interval between execution of jobs on the weekday(s) specified. Valid values are 2, 4, 6, 8, 12, or 24. Note that if the interval value of a daily schedule is less than 24, a frequencyDetail end time must be supplied.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

    For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="4"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
    <intervals>
WeeklyweekDay=“weekday" The day of the week the schedule should run on. Multiple days can be specified for a Weekly schedule. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.
Monthly

The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval:

Specify the day(s) using the number of the day in the month;

  • monthDay=“day" The number of the day of the month. Valid values are the whole numbers 1 to 31 or LastDay. If you specify monthDay by day number then you can use multiple interval instances to choose for the job to run on multiple days in the month. If you use LastDay then only one instance of interval can be used in the schedule to specify the last day of the month.

Specify the day by describing which occurrence of a weekday within the month.

  • monthDay=“occurrence_of_weekday" Weekday=“weekday" The occurrence of the specified weekday within the month when a job should be run. Valid values for occurrencee_of_weekday are First, Second, Third, Fourth, Fifth, or LastDay. Valid values for weekday are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday. If the value is lastDay then the job will run on the last occurrence of the specified weekday in the month.

    For example, to make a schedule that that would run a job on the third Thursday of each month, you would use:
    Copy
    <interval monthDay="Third" weekDay="Thursday"/>

cURL Request Example

curl --location --request PUT "qa-near.tsi.lan/api/3.22/sites/a946d998-2ead-4894-bb50-1054a91dcab3/subscriptions/r2345998-2ead-4894-bb50-1054a9109876" --header "Content-Type: application/xml" --data "<tsRequest> > <subscription subject="finance report" attachImage="true" attachPdf="true" pageOrientation="true" pageSizeOption="Folio" message="daily finance report"> <content id="13237fd-6365-44d5-925b-644e5281b605" type="Workbook" sendIfViewEmpty="false"/><user id="6t543fd-6365-44d5-925b-644e52897y65"/> </subscription> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> <interval weekDay='Sunday'/> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"

Response Code

200

Response Body

Copy
<tsResponse>
  <subscription
    id="45678fd-6365-44d5-925b-644e52834567"
    subject="finance report" 
    attachImage="true" 
    attachPdf="true" 
    pageOrientation="true" 
    pageSizeOption="Folio" 
    message="daily finance report"> 
      <content 
        id="13237fd-6365-44d5-925b-644e5281b605"
        type="Workbook" 
        sendIfViewEmpty="false"/> 
      <user id="09876fd-6365-44d5-925b-644e528d5678"/>
  </subscription>
  <schedule id="54321fd-6365-44d5-925b-644e52812345"
    createdAt="2023-04-06T23:43:12-0700"
    updatedAt="2023-04-06T23:43:12-0700"
    frequency="Daily"
    nextRunAt="2023-04-06T23:43:12-0700" />
      <frequencyDetails start="18:30:00" end="23:30:00">
        <intervals>
          <interval hours="4"/>
          <interval weekDay="Sunday"/>
          <interval weekDay="Wednesday"/>
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
Copy
{
  "subscription": {
    "id": "789",
    "subject": "finance report",
    "attachImage": "true",
    "attachPdf": "true",
    "pageOrientation": "true",
    "pageSizeOption": "Folio",
    "message": "daily finance report",
    "content": {
      "id": "13237fd-6365-44d5-925b-644e5281b605",
      "type": "Workbook",
      "sendIfViewEmpty": "false"
    },
    "user": {
      "id": "09876fd-6365-44d5-925b-644e528d5678"
    }
  },
  "schedule": {
    "id": "54321fd-6365-44d5-925b-644e52812345",
    "createdAt": "2023-04-06T23:43:12-0700",
    "updatedAt": "2023-04-06T23:43:12-0700",
    "frequency": "Daily",
    "nextRunAt": "2023-04-06T23:43:12-0700",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}

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 404002 User not found The user specified in the request could not be found.
404 404025 Subscription not found The task for the subscription 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 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.22. 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-descrption-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.

Version: Available in API 3.21 ( Tableau Server 2023.3) and later. Not available for Tableau Cloud. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by users with server administrator permissions.   Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available.

URI

PUT /api/api-version/settings/extensions

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.

Request Body

Copy
<tsRequest>
  <extensionsServerSettings>
    <extensionsGloballyEnabled>true</extensionsGloballyEnabled>
      <blockList>https://test.com</blockList>
  </extensionsServerSettings>
</tsRequest>

Copy
{
  "extensionsServerSettings": {
    "extensionsGloballyEnabled": "true",
    "blockList": "https://test.com"
  }
}

Request Attributes

extensionsEnabled

Required. Boolean. If true extensions are allowed to run on the server. If false all extendions are disabled on the server.

blocklist

(Optional) Array. A list of domains that are not allowed to serve extensions to the Tableau Server. Domains are in the form of https://blocked_example.com

(Optional) String. The URL of the extension you want to from the server.

cURL Request Example

curl --location --request PUT "http://MY-SERVER/api/3.22/settings/extensions" --header "Content-Type: application/xml" --header "X-Tableau-Auth: YqB9_MHoTHO26HGsFBFEBg|bQDOIH4MsqFGvUDYTrRYh633vrZHBt6d|a946d998-2ead-4894-bb50-1054a91dcab3" --data "truehttps://test.com "

Response Code

200

Response Body

Copy
<tsRequest>
  <extensionsServerSettings>
   <extensionsGloballyEnabled>true</extensionsGloballyEnabled>
   <blockList>https://test.com</blockList>
  </extensionsServerSettings>
</tsRequest>
Copy
{
  "extensionsServerSettings": {
    "extensionsGloballyEnabled": "true",
    "blockList": "https://test.com"
  }
}

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.

Version: Available in API 3.21 (Tableau Cloud June 2023 / Tableau Server 2023.3) and later. Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: This method can only be called by users with site or server administrator.   Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available.

URI

PUT /api/api-version/sites/site-luid/settings/extensions

URI Parameter Values

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

Request Body

Copy
<tsRequest>
  <extensionsSiteSettings>
    <extensionsEnabled>true</extensionsEnabled>
    <useDefaultSetting>false</useDefaultSetting>
    <safeList>
      <url>http://localhost:9123/Dynamic.html</url>
      <fullDataAllowed>true</fullDataAllowed>
      <promptNeeded>true</promptNeeded>
    </safeList>
  </extensionsSiteSettings>
</tsRequest>

Copy
{
  "extensionsSiteSettings": {
    "extensionsEnabled": "true",
    "useDefaultSetting": "false",
    "safeList": {
      "url": "http://localhost:9123/Dynamic.html",
      "fullDataAllowed": "true",
      "promptNeeded": "true"
    }
  }
}

Request Attributes

extensionsEnabled

Required. Boolean. If true, extensions are allowed to run on the site. If false, no extensions are aloowed to run on the site even if their URL is in the site safelist.

useDefaultSetting (Optional) Boolean. If extensions are enabled on the server, the default settings allow extensions to run on a site, provided the extension is not specifically blocked on the server.
safeList url

(Optional) Array. The list of URLs of the extensions allow to run on the site. An extension permissions to run an a site are also dependent on the domain of the URL not being present on the server blocklist, and server and site extension enablement being true.

Note that updating the safelist replaces the existing list with the new list. If you want to add a URL to the existing list, you must also include the existing URLs in the new list.

safeList fullDataAllowed (Optional) Boolean. Set to true to allow the extension full access to the underlying data. By default, when you add an extension to the safe list, the extension only has access to the summary (or aggregated) data. Many extensions require full data access to function properly.
safeList promptNeeded (Optional) Boolean. The prompt tells users details about the extension and whether the extension has access to full data. Set to true to give users the ability to allow or deny the extension from running. Set to false to hide this prompt from users, allowing the extension to run immediately.

cURL Request Example

curl --location --request PUT http://MY-SERVER/api/3.22/sites/a946d998-2ead-4894-bb50-1054a91dcab3/settings/extensions " --header "Content-Type: application/xml" --header "X-Tableau-Auth: YqB9_MHoTHO26HGsFBFEBg|bQDOIH4MsqFGvUDYTrRYh633vrZHBt6d|a946d998-2ead-4894-bb50-1054a91dcab3" --data "truefalsehttp://localhost:9123/Dynamic.htmltruetrue "

Response Code

200

Response Body

Copy
<tsResponse>
  <extensionsSiteSettings>
    <extensionsEnabled>true</extensionsEnabled>
    <useDefaultSetting>false</useDefaultSetting>
    <safeList>
      <url>http://localhost:9123/Dynamic.html</url>
      <fullDataAllowed>true</fullDataAllowed>
      <promptNeeded>true</promptNeeded>
    </safeList>
  </extensionsSiteSettings>
</tsResponse>
Copy
{
  "extensionsSiteSettings": {
    "extensionsEnabled": "true",
    "useDefaultSetting": "false",
    "safeList": {
      "url": "http://localhost:9123/Dynamic.html",
      "fullDataAllowed": "true",
      "promptNeeded": "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 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.

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.

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.

URI

PUT /api/api-version/sites/site-id/users/user-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to update.

Request Body

<tsRequest>
 <user fullName="new-full-name"
    email="new-email"
    password="new-password"
    siteRole="new-site-role"
    authSetting="new-auth-setting" />
</tsRequest>
        

Attribute Values

Any combination of the elements inside the <user> element is valid. Only those elements present will result in updates to their values for the user. If no elements are present, the update will not take effect.

new-full-name (Optional) The new name for the user. Users can change names without affecting the groups they belong to. Tableau Server only. Not available in Tableau Cloud.
new-email (Optional) The new email address for the user. Tableau Server only. Not available in Tableau Cloud.
new-password (Optional) The new password for the user. Tableau Server only. Not available in Tableau Cloud.
new-site-role

The new site role to assign to the user. You can assign the following roles: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

Note: Only a user in the ServerAdministrator site role can use the REST API to add or remove another user from the ServerAdministrator site role. Users in the ServerAdministrator site role can only be moved to the Creator site role if one or more Creator licenses have been activated on the server; otherwise these users can only be moved to the Publisher site role. This method only supports the ServerAdministrator site role in version 2.8 and later.

new-auth-setting

(Optional) The authentication type for the user.

(For Tableau Server: This attribute only applies when adding users to sites with site-specific SAML enabled in settings.)

You can assign the following values for this attribute:

Permissions

This method can only be called by server administrators or site administrators. In addition, site administrators have some limitations in what changes they can make to users:

  • Site administrators cannot set the fullName value.
  • On Tableau Server, site administrators can change the email and password values only if the caller is a site administrator for all sites that the user is a member of. On Tableau Cloud, you cannot change a user's email or password.
  • Site administrators can change the siteRole value only if the site is configured to allow site administrators to add and remove site users. Site administrators on Tableau Cloud can change the siteRole value because they have permission to add and remove site users.

Response Code

200

Response Body

<tsResponse>
 <user name="user-name"
    fullName="new-full-name"
    email="new-email"
    siteRole="new-site-role"
    authSetting="new-auth-setting" />
</tsResponse>
        

Version

Version 1.0 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 400000 Invalid email address The email attribute does not contain a valid email address.
400 400003 Bad request The user authentication setting ServerDefault is not supported for you site. Try again using TableauIDWithMFA instead.
400 400012 Bad request The user cannot be assigned the Unlicensed role because they are still a member of a group that has a minimum site role set.
403 403009 Licensing update on self forbidden A user cannot update their own licensing role.
403 403009 Guest update forbidden The Guest user is a special user and cannot be updated.
400 400013 Invalid site role

The value of the siteRole attribute must be Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer.

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.
409 409000 User conflict The user with the specified name is already registered on the site in the same domain.
409 409014 Licensing conflict The request is attempting to update the user to a licensing role that has insufficient capacity.

For more information, see Handling Errors.

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.

URI

PATCH /api/api_version/sites/site-id/settings/notifications

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.

Request Body

<tsRequest>
  <userNotificationsPreferences>
    <userNotificationsPreference
      enabled="enabled-flag"
      channel="channel"
      notificationType="notification-type"/>
    <userNotificationsPreference
      enabled="enabled-flag"
      channel="channel"
      notificationType="notification-type"/>
  <userNotificationsPreferences>
</tsRequest>

Attribute Values

enabled-flag (Required, boolean) If true, the specified site notifications will be on. If false, the specified site notifications will be off.
channel (Required, string) Specifies the channel that the notification preferences are to be updated (turned on or off). Valid channels are: email, in_app, and slack.
notification-type

Specifies the notification type for which the notification preferences are to be updated (turned on or off). Valid notification types are: comments, webhooks, prepflow, share, dataalerts,and extractrefresh.

Permissions

This method can only be called by a Server Administrator, a Site Administrator Creator, or a Site Administrator Explorer.

Response Code

  • 200: The request was successful
  • 207: One or more of the updates in the request resulted in an error. See details in the the response body.

Response Body

<tsResponse>
  <notificationUpdateResult>
    <notificationUpdateStatus>
      <status>Success</status>
        <userNotificationsPreference channel="channel"
          notificationType="notification-type"
          enabled="enabled-flag"/>
        </notificationUpdateStatus>
    <notificationUpdateStatus>
      <status>Success</status>
        <userNotificationsPreference channel="channel"
          notificationType="notification-type"
          enabled="enabled-flag"/>
    </notificationUpdateStatus>
  </notificationUpdateResult>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Invalid Permissions Invalid permission to update site user notification settings.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method The request type was not PATCH.

For more information, see Handling Errors.

Example response

<tsResponse>
  <notificationUpdateResult>
    <notificationUpdateStatus>
      <status>Success</status>
        <userNotificationsPreference channel="slack"
          notificationType="comments"
          enabled="false"/>
      </notificationUpdateStatus>
      <notificationUpdateStatus>
        <status>Success</status>
        <userNotificationsPreference channel="email"
          notificationType="comments"
          enabled="false"/>
      </notificationUpdateStatus>
  </notificationUpdateResult>
</tsResponse>

Update Virtual Connection Database Connections

Updates the server address, port, username, or password for the specified database connection in a virtual connection.

Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1) and later. Version Overview

License: Requires Tableau Data Management(Link opens in a new window).

Permissions: Users who are administrators or have the site role of Creator or higher can update a database connection.  Permissions Overview

JWT Access Scope: Not available.

URI

PUT /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/connections/connection-id/modify

URI Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site that contains the virtual connection.
virtual-connection-luid The LUID for the virtual connection that includes the database connections.
connection-id The ID of the database connection. To determine what connections are in a virtual connection, call List Virtual Connection Database Connections(Link opens in a new window).

Request Body

<tsRequest>
 <connection
   serverAddress="server-address"
   serverPort="port-number"
   userName="test"
   password="password" />
</tsRequest>
{
  "connection": {
    "serverAddress": "server-address",
    "serverPort": "port-number",
    "userName": "test",
    "password": "password"
  }
}

 

Request Attributes

connection serverAddress The new server for the database connection.
connection serverPort The new port for the database connection
connection userName The new username for the database connection.
connection password The new password for the database connection.

cURL Request Example

curl --location --request PUT "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections/26bc30d8-90d6-4af1-922d-ac285e7b08fb/connections/26bc30d8-90d6-4af1-922d-ac285e7b08fb"

Response Code

200

Response Body

Copy
<tsResponse>
  <virtualConnectionConnections>
    <connection 
      id="connection-id" 
      serverAddress="server-address" 
      serverPort="port-number"
      userName="connection-user-name"
      password="password"/>
  </virtualConnectionConnections>
</tsResponse>

Copy
{
  "virtualConnectionConnections": {
    "connection": {
      "id": "connection-id",
      "serverAddress": "server-address",
      "serverPort": "port-number",
      "userName": "connection-user-name",
      "password": "password"
    }
  }
}

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.

Version: Available in API 2.0 (Tableau Cloud and later). Data acceleration and data freshness policy setting update are added in API 3.22 (Tableau Cloud February 2024 / Server 2024.2). Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Users who are Tableau administrators can change a workbook's owner. Users who are not server administrators can update a workbook only if they have Write permission for the workbook and for the project. Tableau server and site administrators can change the dataAccelerationConfig accelerationEnable setting for a workbook. Workbook owners can change the setting if the site is configured to enable acceleration by owners(Link opens in a new window). Both administrators and workbook owners can change dataFreshnessPolicy settings.   Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:workbooks:update     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

PUT /api/api-version/sites/site-id/workbooks/workbook-id

PUT /api/api-version/sites/site-id/workbooks/workbook-id?includeViewAccelerationStatus=include-view-acceleration-status-flag

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to update.
include-view-acceleration-status-flag Query parameter is optional. Boolean: If includeViewAccelerationStatus=true then the list of views and the acceleration status of each view will be returned.

Request Body

Copy
<tsRequest> 
  <workbook 
    name="Finance"
    showTabs="false"
    recentlyViewed="false"
    encryptExtracts="false" 
    description="The finance workbook.">
      <project id="3d6e8174-8cdf-43ec-94dd-0a1fd3662e47" />
      <owner id="ca6b9ee-1d85-465b-abc2-f200ae2443b9" />
      <views>
          <view id="22e48174-8cdf-43ec-94dd-0a1fd366gh78"/>
        </views>
      <dataAccelerationConfig 
        accelerationEnabled="false" 
        accelerateNow="false" />
      <dataFreshnessPolicy option="FreshAt">
        <freshAtSchedule frequency="weekly" time="08:15:00" timezone="America/Los_Angeles">
          <intervals>
            <interval weekDay="Monday" />
          </intervals>
        </freshAtSchedule>  
      </dataFreshnessPolicy>
  </workbook> 
</tsRequest>

Copy
{
  "workbook": {
    "name": "Finance",
    "showTabs": "false",
    "recentlyViewed": "false",
    "encryptExtracts": "false",
    "description": "The finance workbook.",
    "project": {
      "id": "3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"
    },
    "owner": {
      "id": "ca6b9ee-1d85-465b-abc2-f200ae2443b9"
    },
    "views": {
      "view": {
        "id": "22e48174-8cdf-43ec-94dd-0a1fd366gh78"
      }
    },
    "dataAccelerationConfig": {
      "accelerationEnabled": "false",
      "accelerateNow": "false"
    },
    "dataFreshnessPolicy": {
      "option": "FreshAt",
      "freshAtSchedule": {
        "frequency": "weekly",
        "time": "08:15:00",
        "timezone": "America/Los_Angeles",
        "intervals": {
          "interval": {
            "weekDay": "Monday"
          }
        }
      }
    }
  }
}

Notes on Data Freshness Policy(Link opens in a new window) and View Acceleration(Link opens in a new window):

  • Data Freshness Policy and View Acceleration are independent features.
  • If a policy is set without view acceleration for a workbook, then only query caching(Link opens in a new window) for the workbook will be affected by the policy.
  • If a workbook has a data freshness policy configured, then updating the workbook to turn on view acceleration will not impact the policy unless the update explicitly changes that.
  • If a workbook has accelerated views enabled, but does not have a data freshness policy explicitly set for it, data will be refreshed on the site default cadence of every 12 hours.
  • On Tableau Cloud, view acceleration is limited to 12 refreshes per day, per view. If data freshness policy for a workbook is set to refresh data more frequently than every 2 hours, refreshes for a view after the 12th one will not trigger the computation that accelerates that view until the first refresh of the next day.
  • The preceding example shows the freshAt data freshness policy option. The freshEvery option is illustrated in the following Attribute Values section.

Attribute Values

workbook name (Optional) New name for the workbook being updated.
workbook showTabs (Optional) Specify true to have the updated workbook show views in tabs; otherwise, false. The default is false.
workbook recentlyViewed (Optional) Set this value to true to have the updated workbook show in the site's recently viewed list. The default is false. Once the flag is set to true, setting it to false will have no effect. When enough views or workbooks have populated the recently viewed list, the oldest item will fall off the list and its recently-viewed-flag will revert to false.
workbook encryptExtracts (Optional) true to encrypt the extracts or false to not encrypt extracts. For more information, see Extract and Encryption Methods.
workbook description (Optional) The new description for the updated workbook.
project id (Optional) The LUID of a project to assign the workbook to.
owner id (Optional) The LUID of a user to assign the workbook to as owner.
dataAccelerationConfig accelerationEnable (Optional) Boolean: If true, accelerate the specified view(s). Default is false.
dataAccelerationConfig accelerateNow (Optional) Boolean: If true, make view acceleration available as soon as possible. Default is false. Note, the view object in the response (visible by using the ?includeViewAccelerationStatus=true query parameter) contains the accelerationStatus attribute, which can have the following values:
  • Off - Accelerate now is not enabled.
  • Pending - Accelerate now is enabled, but backgrounder processes are still running to make the acceleration available.
  • On Acceleration is enabled.
view id (Optional) LUID: The LUID of a view being accelerated. If no views are listed in the request then all views in the workbook will be accelerated.
dataFreshnessPolicy option (Optional) Enum: The data freshness policy(Link opens in a new window) mode for scheduling refreshment of the workbook data specified in the request. A valid value is one of:
  • SiteDefault - Use the default scheduling policy: refresh the data every 12 hours).
  • AlwaysLive - Refresh as the data changes.
  • FreshAt - Define a detailed cadence for refreshing the data.
  • FreshEvery- Define an interval between data refreshes.
freshAtSchedule frequency (Optional) Enum: The interval of workbook data refresh. A valid value is one of:
  • Day
  • Week
  • Month
freshAtSchedule time (Optional) Time in HH:MM:SS: The time of day that workbook data will be refreshed, in increment of 15 minutes. Minutes must end in 00, 15, 30, or 45. for instance time="10:30:00".
freshAtSchedule timeZone (Optional) Timezone string in IANA format: The timezone of the fresh at schedule time. For instance, timezone="America/Los_Angeles". If no timezone is provided, then the local timezone of the Tableau server is used."
freshAtSchedule intervals interval A value that specifies the interval between refreshes of view acceleration data. The value you specify here depends on the value specified in freshAtSchedule frequency.

Day

If the schedule frequency is Daily, no interval is specified. Any information specified in the <intervals> element is ignored.

Week

The interval expression is weekDay="weekday", where weekday is Sunday, Monday, Tuesday, Thursday, Friday, or specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week.

Month

The interval expression is monthDay="day", where day is either the day of the month (1, 2, etc.) or LastDay.

freshEverySchedule frequency (Optional) Enum: The time unit used for the cadence of view acceleration data refreshes. The count of the specified unit that occurs between refreshes is determined by freshEverySchedule value. A valid value is one of:
  • Minutes
  • Hours
  • Days
  • Weeks
freshEverySchedule value (Optional) Integer: The quantity of frequency units between view acceleration data refreshes. For instance, to specify a refresh every 4 hours, the dataFreshnessPolicy would look like:
XML JSON
Copy
<dataFreshnessPolicy option="FreshEvery">
  <freshEverySchedule 
  frequency="hours" 
  value="4" />
  </dataFreshnessPolicy>
Copy
"dataFreshnessPolicy": {
  "option": "FreshEvery",
  "freshEverySchedule": {
  "frequency": "hours",
  "value": 4"
  }
}

With the exception of dataFreshnessPolicy options, any combination of the elements inside the <workbook> element is valid. Only the attributes and child elements that are included result in updates to the data source. If no attributes or nested elements are included, no update is made.

The dataFreshnessPolicy option can only be one of listed options, and the elements of a specified option are required for that option to be updated.

If the <project> element is included, the id attribute must be included; other attributes of the <project> element are ignored.

If the <owner> element is included, the id attribute must be included; other attributes of the <owner> element are ignored.

cURL Example

curl --location --request PUT "https://myServer/api/3.22/sites/d76ee955-ccc7-4333-ab3b-25ad2f8b1aa8/workbooks/c75aaa17-727f-48f8-80d1-1e66c30497c5" \ --header "Content-Type: application/xml" \ --header "X-Tableau-Auth: vZg2soQ2TuiULoJgZ60h_A|JIfSgwAzBQ2QfSVS1PSsHvD9uynKLzWz|d76ee955-ccc7-4333-ab3b-25ad2f8b1aa8" \ --header "Cookie: AWSALBAPP-0=AAAAAAAAAADyQT+tw75WkCZpVc/icDu7+3QFC+j4W5jpddfTbd8p8kxx5cx5slxbi2jSYvaAa0RBfxXvQ3tTjfZGHnt3ORMP5y79bEWR/lBKRMbJpRVYfI4jV32tGCld6NPtpgwYogFxZBo=; AWSALBAPP-1=_remove_; AWSALBAPP-2=_remove_; AWSALBAPP-3=_remove_; hid=uw2a-hap01" \ --data "<tsRequest> <workbook > <dataAccelerationConfig accelerationEnabled='true' accelerateNow='true' /> <dataFreshnessPolicy option='FreshEvery'> <freshAtSchedule frequency='Week' time='08:15:00' timezone='America/Los_Angeles'> <intervals> <interval weekDay='Monday' /> </intervals> </freshAtSchedule> </dataFreshnessPolicy> </workbook> </tsRequest>"

Response Code

200

Response Body

Copy
<tsResponse>
  <workbook id="0828bd63-dea5-454f-8f54-30f9a92760ff" 
    name="WB_Election_live" 
    description="" contentUrl="WB_Election_live" 
    webpageUrl="http://MyServer/#/workbooks/4" 
    showTabs="false" size="1" createdAt="2024-01-25T23:42:57Z" 
    updatedAt="2024-01-25T23:42:57Z" 
    encryptExtracts="false" 
    defaultViewId="10f6d099-fe90-41a1-a77b-1512b818d23c">
      <project id="7eb51f54-bbca-11ee-9262-638afb01250c" name="Default"/>
      <location id="7eb51f54-bbca-11ee-9262-638afb01250c" type="Project" name="Default"/>
      <owner id="09d032b6-d17d-444c-afbe-d71c22f7ee31" name="test"/>
      <tags/>
      <views>
        <view id="fcc36499-fd2d-42af-8e2c-29d1c7893edd" 
            name="Votes" 
            contentUrl="WB_Election_live/sheets/Votes" 
            createdAt="2024-01-25T23:42:57Z" 
            updatedAt="2024-01-25T23:42:57Z" 
            viewUrlName="Votes">
            <tags/>
            <dataAccelerationConfig accelerationEnabled="true" 
                accelerationStatus="Pending"/>
          </view>
        </views>
      <dataFreshnessPolicy option="freshAt"/>
          <freshAtSchedule />
            <intervals>
              <interval weekDay="Monday"
            </intervals>
      </dataFreshnessPolicy>
  </workbook>
</tsResponse>
Copy
{
  "workbook": {
    "name": "Finance",
    "showTabs": "false",
    "recentlyViewed": "false",
    "encryptExtracts": "false",
    "description": "The finance workbook.",
    "project": {
      "id": "3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"
    },
    "owner": {
      "id": "ca6b9ee-1d85-465b-abc2-f200ae2443b9"
    },
    "views": {
      "view": {
        "id": "22e48174-8cdf-43ec-94dd-0a1fd366gh78"
      }
    },
    "dataAccelerationConfig": {
      "accelerationEnabled": "false",
      "accelerateNow": "false"
    },
    "dataFreshnessPolicy": {
      "option": "FreshAt",
      "freshAtSchedule": {
        "frequency": "weekly",
        "time": "08:15:00",
        "timezone": "America/Los_Angeles",
        "intervals": {
          "interval": {
            "day": "Monday"
          }
        }
      }
    }
  }
}

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

A response for the dataFreshnessPolicy segment with the FreshEvery option configured for weekly refreshes, would look like:

XML JSON
Copy
<dataFreshnessPolicy option="FreshEvery">
  <freshEverySchedule 
  frequency="Weeks" 
  value="1" />
  </dataFreshnessPolicy>
Copy
"dataFreshnessPolicy": {
  "option": "FreshEvery",
  "freshEverySchedule": {
  "frequency": "Weeks",
  "value": 1"
  }
}
n

Version

Version 2.0 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 400036 Bad request View acceleration is enabled, but the workbook loads too quickly to make use of it, or the view has never been accessed by a user.
403 403025 Project update forbidden A non-administrator user tried to change the workbook project, but the caller doesn't have Write permission for the target project.
403 403027 Owner update forbidden A non-administrator user tried to change the workbook owner.
403 403027 Update forbidden A non-administrator user tried to change the workbook, but the caller doesn't have Write permission for the workbook.
403 403004 Update forbidden A non-administrative user tried to update the workbook, but does not have permissions to publish the updated workbook to the project.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 Owner not found The owner ID in the request body doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't match the project ID provided in the request body.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

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.

URI

PUT /api/api-version/sites/site-id/workbooks/workbook-id/connections/connection-id

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to update.
connection-id The ID of the connection to update.

Request Body

<tsRequest>
  <connection
    serverAddress="server-address" serverPort="port"
    userName="connection-username" password="connection-password"
    embedPassword="embed-password"
	queryTaggingEnabled="query-tagging-enabled" />
</tsRequest>
        

Attribute Values

server-address The new server for the connection.
port The new port for the connection.
connection-username The new username for the connection.
connection-password The new password for the connection.
embed-password True to embed the password; otherwise, False.
query-tagging-enabled

In API 3.23 (Tableau Cloud June 2024 / Server 2024.2) and later: using queryTaggingEnabeld to enable query tagging for individual connections is deprecated, will no longer be supported, and may be retired in future releases. Instead:

- For Tableau Cloud, query tagging will be enabled for all content on a site by default.

- For Tableau Server 2023.3 and later, you can use TSM to enable query tagging for all content on a server by setting native_api.UserInfoInGeneratedSQLEnabled(Link opens in a new window) to true.

For API 3.22 or earlier: true to enable query tagging(Link opens in a new window) that associates a specific server log query event with the Tableau resource that made the query. False, which disables query tagging, is the default.

Any combination of the attributes inside the <connection> element is valid. If no attributes are included, no update is made.

Permissions

Users who are not server administrators or site administrators can update permissions only for a workbook for which they have the Write capability (either explicitly or implicitly). Only users with administrator permissions can enable or disable query tagging.

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:workbooks:update

Response Code

200

Response Body

<tsResponse>
  <connection id="connection-id"
    serverAddress="server-address" serverPort="port"
	userName="connection-user-name"
	queryTaggingEnabled="query-tagging-enabled" />
</tsResponse>
        

Version

Version 2.0 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 403029 Update forbidden A non-administrator user tried to update the workbook connection, 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 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404020 Connection not found The connection ID in the URI doesn't correspond to an existing connection.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

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

URI

POST /api/api-version/sites/site-id/workbooks/workbook-id/refresh

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to refresh.

Request Body

<tsRequest></tsRequest>
        

Permissions

Tableau Server users who are not server administrators or site administrators can only refresh workbooks if they own the workbook, or if they are the project leader for the project.

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:tasks:run

Response Code

202

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="RefreshExtract" createdAt="date-time">
    <extractRefreshJob>
      <workbook id="workbook-id" name="workbook-name" />
    </extractRefreshJob>
  </job>
</tsResponse>
        

Version

Version 2.8 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 The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user attempted to query workbook views, but the caller doesn't have sufficient permissions.
403 403004 Update forbidden A non-administrative user tried to update the workbook, but does not have permissions to publish the updated workbook to the project.
404 404000 Site not found The site ID in the URI is unknown.
404 404006 Resource not found The workbook ID in the URI is unknown.
405 405000 Invalid request method Request type was not POST.
409 409093 Operation already in Queue The extract refresh job is already in the queue.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/workbooks/5de9cc53-b17d-45af-804d-49144b39f29f/refresh" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -H "Content-Type: application/xml" –d @empty-tsrequest.xml"

Content of empty-tsRequest.xml:

<tsRequest>
</tsRequest>

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-2.8.xsd">
  <job id="20cf4ddc-6d73-4733-89ec-8d336669bd56" mode="Asynchronous" type="RefreshExtract" createdAt="2017-12-06T22:58:52Z">
    <extractRefreshJob>
      <workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" name="Regional" />
    </extractRefreshJob>
  </job>
</tsResponse>

Previous Schema Versions

The API reference reflects version 3.22 of the REST API schema, which is available with Tableau Server 2022.4. For more information, see REST API XML Schema and REST API and Resource Versions.

If you are working with an earlier version of Tableau Server, see the following REST API reference pages:


Thanks for your feedback!Your feedback has been successfully submitted. Thank you!