Tableau REST API Help
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.
- On this page, use theAPI Method Categories list, or find keywords in theAPI Method Details list withctrl/cmd-f search.
- For more information, seeFundamentals of the Tableau Server REST APIandREST API Example Requests.
Note: For help with your code that uses the Tableau REST API, submit questions and ask for help on theTableau 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.
| Add analytics extension connection to site | 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. |
| 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. |
| 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 allpersonal 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 toSign In. |
| Switch Site - Not available for Tableau Cloud. | Switches you onto another site without having to provide a user name and password again. |
| 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 | 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 | Get all external authorization servers (EASs) registered to a site. |
| List Connected Apps | Query all connected apps configured on a site. |
| List Registered EAS | Get an external authorization server (EAS) registered to a site. |
| Register EAS | 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. |
| 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. |
| Create custom domain settings - Not available for Tableau Server | Starts the process of custom domain setup for a Tableau site. |
| Delete custom domain settings - Not available for Tableau Server | Deletes the custom domain setup for a Tableau site. |
| Get Custom Domain Name - Not available for Tableau Server | Gets the custom domain for a Tableau site, if one is provisioned. For more information about how, see. |
| Get custom domain settings - Not available for Tableau Server | Gets the custom domain settings for a Tableau site. |
| Update custom domain settings - Not available for Tableau Server | Updates the custom domain setup for a Tableau site. |
| 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. |
| 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 Encrypted Keychain | Gets an encrypted version of the embedded credentials from the data source. These credentials can only be migrated to the linked destination Tableau Cloud or Tableau Server. |
| 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 theDownload 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 publisheddata source, callUpdate Data Source orUpdate 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 theQuery 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 alive-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 alive-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, authentication type, username, or password for the specified data source connection. |
| Update Data Source Now | Runs an extract refresh on the specified data source. |
| Upload Data Source Encrypted Keychain | Uploads the encrypted version of the embedded credentials. This method will only work if the credentials are encrypted with the latest public key used to link the source Tableau Server with the destination Tableau Cloud or Tableau Server site. |
| Create an Extract for a Data Source | Create an extract for a data source in a site. Optionally, encrypt the extract ifthe 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, seeAdd data source to server schedule andAdd 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, seeExtract 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, seeExtract 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, seeExtract 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, seeUpdate server schedule. |
| 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. |
| 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 withCreate Cloud Flow Task method. |
| Cancel Flow Run | Cancels a flow run that is in progress. |
| Create Cloud Flow Task - Not available for Tableau Server. Available only with a Data Management license. | Creates a flow task on Tableau Cloud, and set its schedule. |
| 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. |
| List Flow Permissions | Returns a list of permissions for the specific flow. |
| 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 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 - Available only with a Data Management license. | 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 project and/or owner of the specified flow. |
| Update Flow Connection | Updates the server address, port, username, or password for the specified flow connection. The connection can be an input or an output connection. |
| Update Flow Owner | Updates a flow's owner. |
| 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 on Server - Not available for Tableau Cloud | List information about all authentication instances associated with identity pools. |
| 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. |
| 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, seeCreate Cloud Extract Refresh Task. |
| 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. |
| Batch Update Schedule State - Not available for Tableau Cloud | Updates the state of one or more schedules. |
| 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 theQuery Jobs method. |
| Create Server Schedule - Not available for Tableau Cloud. | Creates a new server schedule on Tableau Server. For Tableau Cloud, seeCreate Cloud Extract Refresh Task andCreate 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, seeDelete Extract Refresh Task andDelete Subscription. |
| Get Data Acceleration Tasks in a Site | Returns a list of data acceleration tasks for the site. |
| Get Extract Refresh Task | Returns information about the specified extract refresh task. |
| Get Server Schedule - Not available for Tableau Cloud. | Returns detailed information about the specified server schedule on Tableau Server. |
| 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. |
| 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 theQuery Job method. To cancel an active job, pass a job ID returned by this method to theCancel Job method. |
| Run Extract Refresh Task | Runs the specified extract refresh task. |
| 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, seeUpdate cloud extract refresh task andUpdate subscription. |
| 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. |
| 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. |
| Add or Update Monitoring Quality Warning on Content - Available only with a Data Management license. | Create or update one or more monitoring quality warnings. |
| 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. |
| Add Tags to Virtual Connection - Available only with a Data Management license. | Adds tags to a virtual connection. |
| 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. |
| Delete Tag from Virtual Connection - Available only with a Data Management license. | Deletes a tag from a virtual connection. |
| 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. |
| Get Metadata Suggestion - Available only with Tableau+ | Gets a suggestion from generative AI about asset metadata. |
| List Database Permissions | Get information about the permissions on a database asset. |
| List Default Database Permissions | Get the default permissions applied to the database asset and its children tables. |
| 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. |
| List Table Permissions | Get information about the permissions on a table asset. |
| Move Database - Available only with a Data Management license. | Move one or more databases to a project. |
| 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 Databases | Get information about all database assets for a site. |
| Query Quality Warning Trigger | Get information about a quality warning trigger. |
| Query Table | Get information about 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 database permissions, or assign a Tableau Cloud or Server user as the database contact. |
| Update Label - Available only with a Data Management license. | Updates a label by its LUID. |
| 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. |
| Update labelValue - Available only with a Data Management license. | Updates a label value. |
| Update Monitoring Quality Warning - Available only with a Data Management license. | Update a monitoring quality warning. |
| 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. |
| 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. |
| 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. |
| 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, seeManage 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, seeManage Your Account Settings. |
| 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. |
| 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, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also adds default permission rules for database or table resources in a project for a user or group. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions arelocked 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, seePermissions(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 Virtual Connection Permissions - Available only with a Data Management license. | Adds permissions to the specified virtual connection 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, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also removes default permission rules for database or table resources in a project for a user or group. After removing default permission rules, new resources of the type you specify that are added to the project will no longer have those permission rules. If permissions arelocked 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 Virtual Connection Permission - Available only with a Data Management license. | Removes the specified virtual connection permission for the specified group or user. |
| 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. |
| List Data Source Permissions | Returns a list of permissions for a specific data source. |
| List Default Permissions | Returns details of default permission rules granted to users and groups for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, this method can also return details of default permission rules granted to users and groups for database or table resources in a project. |
| List Project Permissions | Returns information about the set of permissions allowed or denied for groups and users in a project. |
| List View Permissions | Returns a list of permissions for the specific view. |
| List Virtual Connection Permissions - Available only with a Data Management license. | Returns a list of permissions for a specific virtual connection. |
| List Workbook Permissions | Returns a list of permissions for the specific workbook. |
| Replace Content Permissions | Replaces existing permissions in the specified content. You can specify multiple sets of permissions using one call. |
| Replace Project's Default Permissions | Replaces default permissions in the specified content. If Tableau Catalog is enabled, it also adds default permission rules for database or table resources in a project. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions arelocked 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, seePermissions(Link opens in a new window). |
| 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, callUpdate 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. |
| Append to File Upload | Uploads a block of data and appends it to the data that is already uploaded. |
| Initiate File Upload | Initiates the upload process for a file. After the upload has been initiated, you callAppend to File Upload to send individual blocks of the file to the server. When the complete file has been sent to the server, you callPublish Data Source,Publish Flow, orPublish 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 publisheddata source, callUpdate Data Source orUpdate 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, callUpdate Workbook orUpdate Workbook Connection. |
| Batch create Pulse subscriptions - Not available for Tableau Server | Creates multiple subscriptions to a metric for specified users and/or groups. |
| Batch get Pulse 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 Pulse subscriptions - Not available for Tableau Server | Gets a batch of subscriptions, specified in a comma delimited list of subscriptions LUIDs. |
| Batch list metric definitions (few) - Not available for Tableau Server | Gets the details of a batch of metric definitions and metrics on a site, specified in a brief comma delimited list of LUIDs. |
| Batch list metric definitions (many) - Not available for Tableau Server | Gets the details of a batch of definitions specified in a comma delimited list of LUIDs. This method is optimized for batches with large numbers of definitions. |
| Batch list metrics (few) - Not available for Tableau Server | Gets a batch of metrics from a definition, specified in a comma delimited list. |
| Batch list metrics (many) - Not available for Tableau Server | Gets batches of metrics available on a server. Only metrics a user has privileges to view will be visible. This endpoint uses POST as an alternative to GET, where long lists of URL parameters could be problematic. |
| Create metric - Not available for Tableau Server | Creates a metric. |
| Create metric definition - Not available for Tableau Server | Creates a metric definition. |
| Create metric tag for user - Not available for Tableau Server | Creates a tag for the specified metric, for the signed in user. |
| 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 metric tag - Not available for Tableau Server | Deletes the specified metric tag. |
| Delete Pulse subscription - Not available for Tableau Server | Deletes a specified subscription to a metric. |
| Generate basic insight bundle - Not available for Tableau Server | Generates a basic insight bundle. |
| Generate breakdown insight bundle - Not available for Tableau Server | Generates a breakdown insight bundle. This provides the BAN and breakdown groups of insights. |
| 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 exploration insight bundle - Not available for Tableau Server | Generates an exploration insight bundle. This provides the BAN, anchor, and followup groups of insights. |
| Generate insight brief - Not available for Tableau Server | Generates an insight brief based on a user utterance by gathering insights for the specified metrics. |
| 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 'true' if a new metric was created, or 'false' if it already existed. |
| Get Pulse subscription - Not available for Tableau Server | Gets a specified subscription to a metric. |
| Get site entitlements - Not available for Tableau Server | Returns entitlements available for a site. If entitlements are True, then Pulse premium features are enabled for the site. |
| Gets recommended metrics - Not available for Tableau Server | Gets personalized groups of metrics to recommend to a user. Only metric that the user has privileges to view will be returned. |
| List followed metrics groups - Not available for Tableau Server | Gets the user's followed metrics. Optionally metrics can be grouped by characteristics like datasource, and sorted. |
| List metric definition measurement periods - Not available for Tableau Server | Gets the measurement periods for the specified metric definition. |
| 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 Pulse user preferences - Not available for Tableau Server | Gets the signed in user's preferences for notifications channels and cadence, and for grouping and sorting followed metrics in REST responses and UI. |
| List site alerts - Not available for Tableau Server | List the alerts for the authorized user user on a specified site. |
| 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. |
| Update Pulse user preferences - Not available for Tableau Server | Updates the signed in user's preferences for notifications channels and cadence, and for grouping and sorting followed metrics in REST responses and UI. |
| 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 theDownload 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. |
| 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 namelocal. |
| 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. |
| Create Site - Not available for Tableau Cloud. | Creates a site on Tableau Server. To make changes to an existing site, callUpdate Site. This method isn’t 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. |
| Get User Personal Space | Gets the details of the Personal Space for the currently authenticated user. |
| List Authentication Configurations for Site - Not available for Tableau Server. | List all authentications configurations on the site. |
| 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. |
| Create Subscription | Creates a new 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. |
| 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. |
| 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. |
| Create SCIM Configuration - Not available for Tableau Server. | Creates the System for Cross-domain Identity Management Configuration (SCIM) configuration on the Tableau Cloud site. |
| Create SCIM Token | Generates the System for Cross-domain Identity Management Configuration (SCIM) token and secret. |
| 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 SCIM Configuration - Not available for Tableau Server. | Permanently removes the System for Cross-domain Identity Management Configuration (SCIM) configuration from the Tableau Cloud site. |
| Delete SCIM Token - Not available for Tableau Server. | Permanently removes the System for Cross-domain Identity Management Configuration (SCIM) token. |
| Delete Users from Site with CSV | Creates a job to remove a list of users, specified in a .csv file, from a site. |
| Download User Credentials | Gets credentials for a user who is being migrated to another Tableau Cloud or Tableau Server 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 SCIM Configuration - Not available for Tableau Server. | Gets the System for Cross-domain Identity Management Configuration (SCIM) configuration on the Tableau Cloud site. |
| 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. |
| List Group Sets | Lists all group sets matching optional filter and ordered by optional sort expression. |
| List SCIM Configurations - Not available for Tableau Server. | Returns the System for Cross-domain Identity Management Configuration (SCIM) configurations on the Tableau Cloud site. |
| 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 SCIM Configuration - Not available for Tableau Server. | Updates the System for Cross-domain Identity Management Configuration (SCIM) configuration on the Tableau Cloud site. |
| Update User | Modifies information about the specified user. |
| Upload User Credentials | Uploads user credentials to a site on a destination Tableau Cloud or Tableau Server. |
| Add Tags to Virtual Connection - Available only with a Data Management license. | Adds tags to a virtual connection. |
| Add Virtual Connection Permissions - Available only with a Data Management license. | Adds permissions to the specified virtual connection for a user or group. You can specify multiple sets of permissions using one call. |
| Delete Tag from Virtual Connection - Available only with a Data Management license. | Deletes a tag from a virtual connection. |
| Delete Virtual Connection - Available only with a Data Management license. | Deletes a virtual connection. |
| Delete Virtual Connection Permission - Available only with a Data Management license. | Removes the specified virtual connection permission for the specified group or user. |
| Download Virtual Connection - Available only with a Data Management license. | Downloads a JSON-representation of a virtual connection. |
| Download Virtual Connection Revision - Available only with a Data Management license. | Downloads a JSON-representation of an earlier revision of a virtual connection. |
| List Virtual Connection Database Connections - Available only with a Data Management license. | Returns information about database connections in the specified virtual connection. |
| List Virtual Connection Permissions - Available only with a Data Management license. | Returns a list of permissions for a specific virtual connection. |
| List Virtual Connection Revisions - Available only with a Data Management license. | Lists revisions for a virtual connection. |
| List Virtual Connections - Available only with a Data Management license. | Returns a list of available virtual connection names and IDs. |
| Publish Virtual Connection - Available only with a Data Management license. | Publishes a downloaded JSON-representation of a virtual connection. |
| Update Virtual Connection - Available only with a Data Management license. | Updates a virtual connection's name, owner, project, or certification status. |
| 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. |
| 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 View | Deletes a view from a 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 Encrypted Keychain | Gets an encrypted version of the embedded credentials from the workbook. These credentials can only be migrated to the linked destination Tableau Cloud or Tableau Server. |
| Download Workbook PDF | Downloads a.pdf containing images of the sheets that the user has permission to view in a workbook. |
| 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).IfShow 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 Data | Returns a specified custom view rendered as data in comma separated value (CSV) format. |
| Get Custom View Image | Downloads a .png format image file of a specified custom view. |
| Get Custom View PDF | Returns a specified custom view rendered as a .pdf file. |
| 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 | Gets the list of users whose default view is the specified custom view. |
| Publish Workbook | Publishes a workbook on the specified site. To make changes to a published workbook, callUpdate Workbook orUpdate 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 hasRead (view) permissions for. |
| Set Custom View as Default for Users | 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. |
| 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 workbookshows views in tabs. Updated workbooks can optionally be marked to appear in the recently viewed list. |
| Update Workbook Connection | Updates the server address, port, authentication type, username, or password for the specified workbook connection. |
| Update Workbook Now | Refreshes the specified workbook. |
| Update Workbook Thumbnail Images | Updates a workbook's thumbnail images. |
| Upload Workbook Encrypted Keychain | Uploads the encrypted version of the embedded credentials. This method will only work if the credentials are encrypted with the latest public key used to link the source Tableau Server with the destination Tableau Cloud or Tableau Server site. |
API Method Details
The following content describes each endpoint in the Tableau REST API surface. Use the alphabetically sorted list of methods onthe right, orctrl/cmd-f to go directly to keywords you have in mind.
Add analytics extension connection to site
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
POST {server}/api/-/settings/site/extensions/analytics/connections
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 methodswill 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 as3.27. For more information, seeREST 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> <lensapi-placeholder">lens-luid" /> <granteeCapabilities> <userapi-placeholder">user-luid" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">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 areChangePermissions,Delete,Move,Read,Write. For more information, seePermissions. |
| capability-mode | Allow to allow the capability, orDeny to deny it. This value is case sensitive. |
Permissions
Users with server or site administrator permissions, and non-administrators that haveChangePermissions permission for the lens (either explicitly or implicitly), can add ask data lens permissions.
Response Code
200
Response Body
<tsResponse> <permissions> <lensapi-placeholder">lens-luid" name ="lens-name" /> <granteeCapabilities> <userapi-placeholder">user-luid" /> <capabilities> <capability name="capability" mode="Allow-or-Deny" /> <capability name="capability" mode="Allow-or-Deny" /> <!-- ... additional capabilities ... --> </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">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, seeREST 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 areChangePermissions,Delete,Move,Read, andWrite. |
| 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 thanAllow orDeny for any mode value. |
| 405 | 405000 | Invalid request method | Request type was notPUT. |
For more information, seeHandling 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theUpdate Labels method instead.
The Add Data Quality Warning method adds a data quality warning to an asset. (An automatically-generated monitoring warning does not count towards this limit.) In Tableau Cloud February 2024 and Tableau Server 2024.2 and earlier, adding a data quality warning to an asset that already has one causes an error.
This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.
URI
POST api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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:
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:
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 theServer Help orCloud Help. |
| message | (Optional. Was required in Tableau Server 2023.3 and earlier.) A custom message to accompany the data quality warning. |
| severity | (Optional) Enables high visibility for the data quality warning when set to "true". Value can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in theServer Help orCloud Help. |
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Response Body
Example response:
<tsResponse> <dataQualityWarning 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/><owner/> </dataQualityWarning></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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 childworkbook 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 as3.27. For more information, seeREST 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> <datasourceapi-placeholder">datasource-id" /> <granteeCapabilities> <userapi-placeholder">user-id" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">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 compatibilitywith earlier versions of the REST API. If the<datasource> element is included,thedatasource-id value must match the data source ID in the URI. Any other attributesin 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 arePulseMetricDefine,ChangePermissions,Connect,Delete,ExportXml,ExtractRefresh,Read (view),Write, andSaveAs. For more information, seePermissions. |
| capability-mode | Allow to allow the capability, orDeny 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 haveChangePermissions 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponseversion-and-namespace-settings> <permissions> <datasource /> <granteeCapabilities> <user /> <capabilities> <capability name="capability" mode="Allow-or-Deny" /> <capability name="capability" mode="Allow-or-Deny" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <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, seeREST 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 areChangePermissions,Connect,Delete,ExportXml,Read, andWrite. |
| 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 thanAllow orDeny for any mode value. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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"> <datasourceapi-placeholder">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 haveRead (view) permissions on the data source (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <favorites> <favorite label="favorite-label"> <datasourceapi-placeholder">datasource-id" /> </favorite> <favorite label="favorite-label"> <datasourceapi-placeholder">datasource-id" /> </favorite> ... additional favorites ... </favorites></tsResponse>Version
Version 2.3 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling 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, seeCreate Cloud Extract Refresh Task.
URI
PUT /api/api-version/sites/site-id/schedules/schedule-id/datasources
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 /> </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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:schedules:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <task> <extractRefresh> <schedule /> <datasource /> </extractRefresh> </task></tsResponse>Version
Version 2.8 and later. For more information, seeREST 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 notPUT. |
| 500 | 500000 | Internal Server Error | The schedule ID in the URI is unknown. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 /> </extractRefresh> </task></tsRequest>Example response:
<tsResponse> <task> <extractRefresh priority="50" consecutiveFailedCount="0" type="RefreshExtractTask"> <schedule name="Weekday early mornings" state="Active" /> <datasource /> </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 withTableau Data Management(Link opens in a new window).
Permissions:Users that are grantedChangePermissions 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 as3.27. For more information, seeREST 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 /> <granteeCapabilities> <user /> <capabilities> <capability name="ChangePermissions" mode="allow" /> <!-- ... additional capabilities ... --> </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <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:
These values are case sensitive. |
capability mode | Use one of the following capabilities:
These values are case sensitive. |
group id | The LUID of the group to add permissions for. |
Response Code
200
Response Body
<tsResponse> <permissions><database name="oracle.test.tsi.lan:1521"/><granteeCapabilities> <user/> <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 notPUT. |
| 409 | 409045 | Database error | An unknown database asset error occurred. |
| 409 | 409050 | Database update error | An unknown error occurred and the database asset could not be updated. |
| 409 | 409051 | Database update forbidden | A user without "write" permissions to the database asset attempted an update. |
Add Default Database Permissions
Adds default permission capabilities to a user or group for table resources in that database.
Default permissions function as a permissions template for the database's table assets.
Note: If a database is in a project, default database permissions are not evaluated to determine table permissions. Use theAdd 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 orLocked 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 orManaged 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 as3.27. For more information, seeREST 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> <userapi-placeholder">user-luid" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> <!-- ... additional capabilities ... --> </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">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:
These values are case sensitive. |
| capability-mode | Use one of the following capabilities:
These values are case sensitive. |
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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 name="oracle.test.tsi.lan:1521"/><granteeCapabilities> <user/> <capabilities><capability name="Read" mode="Allow"/> </capabilities></granteeCapabilities> </permissions></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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 thanAllow orDeny for any mode value. |
| 405 | 405000 | Invalid request method | Request type was notPUT. |
Add Default Permissions
Adds default permission rules for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also adds default permission rules for database or table resources in a project for a user or group. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions arelocked 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, seePermissions(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 callCreate Project or for an existing project by callingUpdate Project. For more information, seeLock Content Permissions to the Project(Link opens in a new window).
URI
Workbooks:
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks
Data sources:
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources
Data roles:
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles
Lenses:
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses
Metrics:
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics
Flows:
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows
Virtual Connections(endpoint introduced inAPI version(Link opens in a new window) 3.23):
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections
Databases:
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases
Tables:
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 as3.27. For more information, seeREST 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> <userapi-placeholder">user-luid" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> < !-- ... additional capabilities ... --> </capabilities></granteeCapabilities><granteeCapabilities> <groupapi-placeholder">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
Valid capabilities for a data source are
Valid capabilities for a flow are
For more information, seePermissions. |
| capability-mode | Allow to allow the capability, orDeny 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 theProjectLeader 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse> <permissions><database name="oracle.test.example.com:1521"/><granteeCapabilities> <user/> <capabilities><capability name="Read" mode="Allow"/></capabilities></granteeCapabilities> </permissions></tsResponse>Version
- Version 2.1 and later.
- Version 3.23 and later for the virtual connection default permissions methods.
- For more information, seeREST 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 areAddComment,ChangeHierarchy,ChangePermissions,CreateRefreshMetrics,Delete,ExportData,ExportImage,ExportXml,Filter,Read (view),RunExplainData,ShareView,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. Valid capabilities for a data source areChangePermissions,Connect,Delete,ExportXml,Read (view), andWrite. |
| 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 thanAllow orDeny for any mode value. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 /> <granteeCapabilities> <user /> <capabilities> <capability name="capability-name" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <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:
For more information, seePermissions. |
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).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:permissions:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <permissions> <flow name="Flow1"> <owner/> </flow> <granteeCapabilities> <group/> <capabilities> <capability name="Read" mode="Allow"/> <capability name="Write" mode="Allow"/> <capability name="Delete" mode="Deny"/> </capabilities> </granteeCapabilities> <granteeCapabilities> <user/> <capabilities> <capability name="Delete" mode="Allow"/> </capabilities> </granteeCapabilities> </permissions></tsResponse>Version
Version 3.3 and later. For more information, seeREST 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 areChangeHierarchy,ChangePermissions,Delete,Execute,ExportXml (Download),Read (view), andWrite. |
| 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. |
For more information, seeHandling 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 withCreate Cloud Flow Task method.
Adds a task to run a flow to an existing schedule.
Note: This method is unavailable if you do not have aData 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 as3.27. For more information, seeREST 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/> <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 theList 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, seeRun flows with parameters. |
| overrideValue | The run-time value for the flow parameter. You must specify this if the parameter is required. Use theList 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, seeRun 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:schedules:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Version
Version 3.3 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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/> <flowRunSpec> <flowParameterSpecs> <flowParameterSpec> parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89" overrideValue= "2"/> <flowParameterSpecs> <flowRunSpec> </flowRun> </task></tsRequestExample response:
<tsResponse version-and-namespace-settings> <task> <flowRun priority="50" consecutiveFailedCount="0" type="RunFlowTask"> <schedule 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 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 as3.27. For more information, seeREST 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"> <flowapi-placeholder">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 haveRead (view) permissions on the data source (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <favorites> <favorite label="favorite-label"> <flowapi-placeholder">flow-id" /> </favorite> <favorite label="favorite-label"> <flowapi-placeholder">flow-id" /> </favorite> ... additional favorites ... </favorites></tsResponse>Version
Version 3.3 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Add Group to Group Set
Adds group to a group set.
Version:Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| group-set-id | The unique ID of the group set you want to add the group to. |
| group-id | The unique ID of the group you want to add to the group set. |
Request Body
None
Response Code
200
Response Body
None
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 403 | 403004 | Unauthorized operation | Insufficient permissions to perform the operation. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404012 | Group not found | The group ID in the request body doesn't correspond to an existing group. |
| 409 | 409120 | Group set not found | The group set ID in the request body doesn't correspond to an existing group. |
For more information, seeHandling 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 methodswill 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 as3.27. For more information, seeREST 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"> <metricapi-placeholder">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 methodonly if they haveRead (view) permissions on the metric (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <favorites> <favorite label="favorite-label"> <metricapi-placeholder">metric-id" /> </favorite> <favorite label="favorite-label"> <metricapi-placeholder">metric-id" /> </favorite> ... additional favorites ... </favorites></tsResponse>Version
Version 3.15 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Add or Update Monitoring Quality Warning on Content
Create or update one or more monitoring quality warnings.
You can monitor for extract refresh failures on extract data sources or flow run failures on flows. An asset can only have one instance of monitoring. Adding monitoring to an asset that already has it will update it to use the latest specified values.
Note: An asset can have one monitoring warning in addition to otherdata quality warnings.
This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.
URI
Add or update a monitoring quality warning for an asset
POST api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid]
Add or update a monitoring quality warning for multiple assets
POST api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid1,content-luid2,content-luid3,...]
Note: The square brackets are required around the single LUID or comma-separated list of LUIDs.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| content-type | The type of content the monitoring is being applied to. Use one of the following values:
These values are not case sensitive. |
| content-luid | The LUID of the asset. This is the same as the content ID. The square brackets are required around the single LUID or comma-separated list of LUIDs. |
Request Body
<tsRequest> <dataQualityTrigger type="type" active="status" message="message" severe="severity"/></tsRequest>Attribute Values
| type | Type of monitoring quality warning. To specify the type, use one of the following values:
These values are not case sensitive. |
| status | Monitoring status. Values can be "true" or "false". If set to "true", the data source is monitored for extract refresh failures or the flow is monitored for flow run failures). If an extract refresh or flow run failure occurs, the specified data quality warning is attached to the data source or flow (depending ontype). The data quality warning is removed when the extract refresh or flow run is successful. For more information about monitoring quality warnings, see the monitoring quality warning section of the "Set a Data Quality Warning" topic in theServer Help orCloud Help. |
| message | (Optional) A custom message for the data quality warning. |
| severity | High visibility status of the data quality warning. Values can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in theServer Help orCloud Help. |
Permissions
If Tableau Server or Tableau Cloud is licensed throughData Management, the following users have permissions to add a monitoring quality warning:
- Tableau Server admins or Tableau Cloud site admins
- Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response
<tsResponse> <dataQualityTriggerList><dataQualityTrigger 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, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400136 | Generic quality warning trigger error | The monitoring quality warning could not be added or updated for some other reason than those specified below. |
| 403 | 403004 | Unauthorized operation | Insufficient permissions to perform the operation. |
| 409 | 409004 | Invalid parameter | One or more values in the request body are invalid. |
Add Project Permissions
Adds permissions to the specified project for a user or group. You can specify multiple sets of permissions using one call.
If the request body includes a childdatasource 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 as3.27. For more information, seeREST 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> <userapi-placeholder">user-id" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">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 areProjectLeader,Read (view), andWrite. For more information, seePermissions. |
| capability-mode | Allow to allow the capability, orDeny 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 haveChangePermissions (version2.0) orProjectLeader (version2.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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse> <permissions> <project name="project-name" /> <owner /> </project> <granteeCapabilities> <user /> <capabilities> <capability name="capability" mode="Allow-or-Deny" /> <capability name="capability" mode="Allow-or-Deny" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <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, seeREST 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 thelist of valid capability namesfor this method. The mode of the capability forProjectLeader cannot be set toDeny. |
| 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 thanAllow orDeny for any mode value. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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/> </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).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <favorites> <favorite label="favorite1-label"> <project /> </favorite> <favorite label="favorite2-label"> <project /> </favorite> </favorites></tsResponse>Version
Version 3.1 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 /> </favorite></tsRequest>Example response:
<tsResponse version-and-namespace-settings> <favorites> <favorite label="Economic Indicators"> <project/> </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 as3.27. For more information, seeREST 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 /> <granteeCapabilities> <user /> <capabilities> <capability name="capability-name" mode="capability-mode" /> <!-- ... additional capabilities ... --> </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <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:
These values are case sensitive. |
| capability-mode | Use one of the following capabilities:
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 throughData 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 name="_WarehouseConfig"/><granteeCapabilities> <user/> <capabilities><capability name="Read" mode="Allow"/> </capabilities></granteeCapabilities> </permissions></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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, seeTag 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:column_tags:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 as3.27. For more information, seeREST 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 haveRead permissions for the data source (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:datasource_tags:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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:
<tsResponseversion-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, seeTag 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:database_tags:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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, seeTag 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:table_tags:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 as3.27. For more information, seeREST 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 haveRead permissions for the view (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:view_tags:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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:
<tsResponseversion-and-namespace-settings> <tags> <tag label="GDP"/> <tag label="Health"/> <tag label="Spending"/> </tags></tsResponse>Add Tags to Virtual Connection
Adds tags to a virtual connection.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:You must have theView permission for the virtual connection and your site role must be at leastExplorer. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:virtual_connection_tags:update
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/tags
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| virtualconnection-luid | The LUID for the virtual connection. |
Request Body
<tsRequest> <tags> <tag label="tag" /> <!-- ...additional tag elements... --> </tags></tsRequest>Attribute Values
| tag | The text of the tag. |
cURL Request Example
curl --location --request PUT 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/tags' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml
Contents of data.xml.
<tsRequest> <tags> <tag label="Office" /> <!-- ...additional tag elements... --> </tags></tsRequest>Response Code
200
Response Body
<tsResponse> <tags> <tag label="tag"/> <!-- ...additional tags... --> </tags></tsResponse>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 virtual connection. |
| 403 | 403004 | Adding tags forbidden | The user doesn't have permissions to add tags to the virtual connection. |
| 404 | 404000 | Site not found | The site ID in the URI is not for an existing site. |
| 404 | 404006 | Virtual connection not found | The virtual connection ID in URI doesn't correspond to an existing virtual connection. |
| 404 | 405000 | Invalid request method | Request type was notPUT. |
For more information, seeHandling Errors.
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 as3.27. For more information, seeREST 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 haveRead permissions for the workbook (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:workbook_tags:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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:
<tsResponseversion-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 as3.27. For more information, seeREST 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 callingQuery 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Request Body
<tsRequest> <userapi-placeholder">user-id"/></tsRequest>Response Code
200
Response Body
<tsResponse> <userapi-placeholder">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 notPOST. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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/></tsRequest>Example response:
<tsResponse> <user 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 as3.27. For more information, seeREST 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> <userapi-placeholder">user-id" /></tsRequest>Bulk add users to a group (beginning in API 3.21)
<tsRequest> <users><userapi-placeholder">user-id1" /><userapi-placeholder">user-id2" /><userapi-placeholder">user-id2" /> </users></tsRequest>Attribute Values
| user-id | The ID (not name) of the user to add. You can get the user ID by callingGet 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).
tableau:groups:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Add a single user to a group
<tsResponse> <userapi-placeholder">user-id" name="user-name" siteRole="site-role" /></tsResponse>Bulk add users to group (beginning in API 3.21)
<tsResponse> <users><userapi-placeholder">user-id" name="user-name" siteRole="site-role" /><userapi-placeholder">user-id" name="user-name" siteRole="site-role" /> </users></tsResponse>ThesiteRole value is returned as one of the followingvalues:Creator,Explorer,ExplorerCanPublish,ServerAdministrator,SiteAdministratorExplorer,SiteAdministratorCreator,Unlicensed,ReadOnly,orViewer.
Version
Version 2.0 and later. For more information, seeREST 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 notPOST. |
| 409 | 409011 | User conflict | The specified user is already a member of the group. |
For more information, seeHandling Errors.
Example
Add a single user to a group
curl "http://MY-SERVER/api/3.27/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 /></tsRequest>Example response:
<?xml version="1.0" encoding="UTF-8" ?><tsResponseversion-and-namespace-settings> <user name="Adam" siteRole="Explorer" /></tsResponse>Bulk add users to a group (beginning in API 3.21)
curl "http://MY-SERVER/api/3.27/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 /><user /> </users></tsRequest>Example response:
<?xml version="1.0" encoding="UTF-8" ?><tsResponseversion-and-namespace-settings> <users> <user name="Adam" siteRole="Explorer" /> <user 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, seeProvision 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 as3.27. For more information, seeREST 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> <username="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:
|
| user-id | Required. The ID (not name) of the user to add. You can get the user ID by callingGet 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 callingList 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 theList 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, seeUsernames 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:identity_pools_users:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response:
<tsResponse> <useridentityPoolUuid="df47cf24-5ed3-11ed-9b6a-0242ac12000"id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a"name="Michele Kim" /></tsResponse>Version
Version 3.19 and later. For more information, seeREST 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 notPOST. |
| 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, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/identityPool" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-idpool.xml
MY-SERVERis the name or IP address of your server.9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4dis the ID of the site, as returned by a previous call toSign In.12ab34cd56ef78ab90cd12ef34ab56cdis the credentials token returned by a previous call toSign In.
Content of add-user-to-idpool.xml:
<tsRequest> <user /></tsRequest>Example response:
<?xml version="1.0" encoding="UTF-8" ?><tsResponseversion-and-namespace-settings> <user identityPoolUuid="7b54b6a8-6095-11ed-9b6a-0242ac120002" name="Michele Kim" /></tsResponse>Add User to Site
Adds a user to Tableau Server or Tableau and assigns the user to the specified site.
Tableau Server
If Tableau Server is configured to use local authentication, the information you specify is used to create a new user in Tableau Server.
Note: After creating the user, youmust set a full name, password, and email address for the user with the call toUpdate User. If you are using SAML with local authentication, the user information that you add is not synchronized with the SAML IdP, as it would be if you were using Active Directory. Even if it is not used by SAML, the user information must be present.
If Tableau Server is configured to use Active Directory for authentication, the user you specify is imported from Active Directory into Tableau Server.
Tableau Cloud
When you add a user to Tableau Cloud, the name of the user must be the email address that is used to sign in to Tableau Cloud. After you add a user, Tableau Cloud sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password.
If you try to add a user using a specific site role but you have already reached the limit on the number of licenses for your users, the user is added as an unlicensed user. In that case, the response code is 201 (which indicates success), but thesiteRole value in the response body is set toUnlicensed.
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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site to add users to. |
Request Body
(Use the icon in the top right corner to copy the text.)
<tsRequest> <user name="user-name" siteRole="site-role" authSetting="auth-setting"identityPoolName="identity-pool-name"idpConfigurationId="idp-configuration-id"email="email-address" /></tsRequest>(Use the icon in the top right corner to copy the text.)
{"user": { "name":"user-name", "siteRole":"site-role", "authSetting":"auth-setting", "identityPoolName":"identity-pool-name", "idpConfigurationId":"idp-configuration-id", "email":"email-address" }}Attribute Values
| user-name | The name of the user. If the server uses local authentication, this can be any name. If you are usingActive Directory authentication, or if you are using Tableau Cloud, there are specific requirements for the name. Tableau Server Note: Active Directory specifies a user name using two attributes: Tableau Cloud |
| site-role | The site role to assign to the user. You can assign the following roles:Creator,Explorer,ExplorerCanPublish,SiteAdministratorExplorer,SiteAdministratorCreator,Unlicensed,orViewer. Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role). |
| auth-setting | (Optional) The authentication method to assign the user. Tableau Server TheauthSetting attribute only applies when updating users on sites with site-specific SAML-enabled settings. Tableau Cloud The ability to create and enable multiple authentication methods simultaneously was introduced in API 3.25 (January 2025). As a result of this capability, consider the following:
Notes: You can assign the following values for theauthSetting attribute:
|
| identity-pool-name | (Optional, Tableau Server only) When identity pools are configured, the name of the identity pool. Starting in API 3.19, include the identity pool name when identity pools are configured and you need to add a user to an identity pool that uses the local identity store and OIDC authentication. For more information, seeIdentity Pools Methods. |
| idp-configuration-id | (Optional, Tableau Cloud only) The configuration to assign for user authentication. Added in API 3.25 (January 2025). To find theidpConfigurationId attribute value, use theList Authentication Configurations for Site method. Notes:
|
| email-address | (Optional, Tableau Cloud only) The email address where the user can receive notifications. If no value is provided, Tableau Cloud uses theusername value to send notifications to.Starting in API 3.26 (July 2025), you can specify an email address that is different from the username. |
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).
tableau:users:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Response Body
<tsResponse> <user name="user-name" siteRole="site-role" authSetting="auth-setting" identityPoolName="identity-pool-name" idpConfigurationId="idp-configuration-id" email="email-address" /></tsResponse>Response Headers
Location: /api/3.27/sites/site-id/users/new-user-id
Version
Version 1.0 and later. For more information, seeREST 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 settingServerDefault is not supported for you site. Try again usingTableauIDWithMFA instead. |
| 400 | 400013 | Invalid site role | The value of thesiteRole attribute must beExplorer,ExplorerCanPublish,SiteAdministratorCreator,SiteAdministratorExplorer,Unlicensed,orViewer. |
| 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 notPOST. |
| 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, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-site.xml
MY-SERVERis the name or IP address of your server.9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4dis the ID of the site to add the user to, as returned by a previous call toSign In.12ab34cd56ef78ab90cd12ef34ab56cdis the authentication returned by a previous call toSign In.
Content of add-user-to-site.xml:
<tsRequest> <user name="Adam" siteRole="Explorer" /></tsRequest>Example response:
<tsResponseversion-and-namespace-settings> <user 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 as3.27. For more information, seeREST 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 callingQuery Views for Site. |
Request Body
<tsRequest> <permissions> <view /><granteeCapabilities> <user /> <capabilities> <capability name="capability-name" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <capabilities> <capability name="capability-name" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> ... additional grantee capability sets ... </permissions></tsRequest>Attribute Values
| view-id | Theview-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 beengranted or denied for a specified user or group, that capability is ignored. For valid capabilities for a view areAddComment,ChangePermissions,Delete,ExportData,ExportImage,ExportXml,Filter,Read (view),ShareView,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. For more information, seePermissions. |
| capability-mode | Allow to allow the capability, orDeny 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 itsshowTabs attribute set toHide. You can configure this setting by using theUpdate 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse> <permissions> <view /> <owner/> </view> <granteeCapabilities> <user /> <capabilities> <capability name="capability-name" mode="capability-mode" /> <capability name="capability-name" mode="capability-mode" /> </capabilities> </granteeCapabilities> <granteeCapabilities> <user /> <capabilities> <capability name="capability-name" mode="capability-mode" /> <capability name="capability-name" mode="capability-mode" /> </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <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, seeREST 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 thanAllow orDeny). |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 /> <granteeCapabilities> <user /> <capabilities> <capability name="ExportImage" mode="Allow" /> <capability name="ChangePermissions" mode="Deny" /> </capabilities> </granteeCapabilities> </permissions></tsRequest>Example response:
<tsResponse> <permissions> <view name="What If Forecast"> <owner/> </view> <granteeCapabilities> <group/> <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/> <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 as3.27. For more information, seeREST 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"> <viewapi-placeholder">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).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <favorites> <favorite label="favorite-labe1"> <view name="view-name" contentUrl="content-url" createdAt="created-at"updatedAt="updated-at" viewUrlName="view-url-name"> <workbook/> <project id"project-luid"/> <tags /> </view></favorite> ... additional favorites ... </favorites></tsResponse>The value ofview-url-name is the name of the view in its URL.For example, if a view namedView 1 shows the URLhttps://MY_SERVER/#/site/MY_SITE/views/VIEW_1in your browser address bar, then theview-url-name would beVIEW_1.Modifying thename (display name) of a view will not impact theview-url-name(path element of the view's URL).
Version
Version 1.0 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 /> </favorite></tsRequest>Example response:
<tsResponseversion-and-namespace-settings> <favorites> <favorite label="DC Crimespotting"> <view name="Crimes_DC"contentUrl="content-url"createdAt="created-at"updatedAt="updated-at"viewUrlName="view-url-name"> <workbook/> <project id"3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"/> <tags /> </view> </favorite> <favorite label="Economic Indicators"> <view/> </favorite> </favorites></tsResponse>Add Virtual Connection Permissions
Adds permissions to the specified virtual connection for a user or group. You can specify multiple sets of permissions using one call.
If a specified permission has already been granted or denied for a given user or group, the system ignores it.
URI
PUT /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the virtual connection. |
| virtualconnection‑id | The ID of the virtual connection to set permissions for. |
Request Body
<tsRequest> <permissions> <granteeCapabilities> <userapi-placeholder">user-id" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> <!-- ...additional capabilities... --> </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">group-id" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> <!-- ...additional capabilities... --> </capabilities> </granteeCapabilities> <!-- ...additional granteeCapability sets... --> </permissions></tsRequest>Attribute Values
| user-id | The LUID of the user to add permissions for. A request does not need to include both a user and a group grantee. |
| group-id | The LUID of the group to add permissions for. A request does not need to include both a user and a group grantee. |
| capability-name | The capability to assign. Valid capabilities for a virtual connection areRead,Connect,Overwrite,ChangeHierarchy,Delete, andChangePermissions. For more information, seePermissions. |
| capability-mode | Allow to allow the capability, orDeny to deny it. |
Permissions
You must be an administrator or have theChangePermissions permission for the virtual connection (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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse> <permissions> <virtualConnection name="virtual-connection-name"> <owner/> </virtualConnection> <granteeCapabilities> <user /> <capabilities> <capability name="capability-name" mode="capability-mode" /> <!-- ... additional capabilities ... --> </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <capabilities> <capability name="capability-name" mode="capability-mode" /> <!-- ... additional capabilities ... --> </capabilities> </granteeCapabilities> <!-- ... additional granteeCapability sets ... --> </permissions></tsResponse>Version
Version 3.23 and later. For more information, seeREST 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 virtual connection. Valid capabilities for a virtual connection areRead,Connect,Overwrite,ChangeHierarchy,Delete, andChangePermissions. |
| 403 | 403004 | Permissions setting forbidden | The user tried to change permissions for a virtual connection but doesn't have the permission to change them. |
| 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 | 404012 | Group not found | The group specified in the request body 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). |
| 404 | 404014 | 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 thanAllow orDeny for any mode value. |
| 405 | 405000 | Invalid request method | Request type was notPUT. |
| 400 | 409004 | Invalid LUID | The virtual connection LUID in the URI was not found. |
For more information, seeHandling Errors.
Example
curl --location --request PUT 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest> <permissions> <granteeCapabilities> <user /> <capabilities> <capability name="read" mode="allow" /> </capabilities> </granteeCapabilities> </permissions></tsRequest>'
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 as3.27. For more information, seeREST 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> <workbookapi-placeholder">workbook-id" /> <granteeCapabilities> <userapi-placeholder">user-id" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">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, theworkbook-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 areAddComment,ChangeHierarchy,ChangePermissions,CreateRefreshMetrics,Delete,ExportData,ExportImage,ExportXml,ExtractRefresh,Filter,Read (view),RunExplainData,ShareView,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. For more information, seePermissions. |
| capability-mode | Allow to allow the capability, orDeny 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse> <permissions> <workbook /> <granteeCapabilities> <user /> <capabilities> <capability name="capability" mode="Allow-or-Deny" /> <capability name="capability" mode="Allow-or-Deny" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <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, seeREST 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 areAddComment,ChangeHierarchy,ChangePermissions,CreateRefreshMetrics,Delete,ExportData,ExportImage,ExportXml,Filter,Read (view),RunExplainData,ShareView,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. |
| 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 thanAllow orDeny for any mode value. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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"> <workbookapi-placeholder">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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <favorites> <favorite label="favorite-label"> <workbook /> </favorite> <favorite label="favorite"> <view /> </favorite> ... additional favorites ... </favorites></tsResponse>Version
Version 1.0 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling 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, seeCreate a Schedule.
For Tableau Cloud, seeCreate Cloud Extract Refresh Task.
This method is not available for Tableau Cloud.
Starting in Tableau version 2022.1 (API v3.16), with the introduction ofView 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 willalso not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removingany dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releasesresulting 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 as3.27.For more information, seeREST 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 /> </extractRefresh> </task> <task> <dataAcceleration> <workbook /> </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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:schedules:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <task> <extractRefresh type="extractRefresh-type"> <schedule /> <workbook /> </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 ofView 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 willalso not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removingany dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releasesresulting in error codes being returned.
For more information, seeREST 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 notPUT. |
| 500 | 500000 | Internal Server Error | The schedule ID in the URI is unknown. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 /> </extractRefresh> </task></tsRequest>Example response:
<tsResponse> <task> <extractRefresh priority="50" consecutiveFailedCount="0" type="RefreshExtractTask"> <schedule name="Weekday early mornings" state="Active" /> <workbook /> </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 withTableau 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) 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
POST {server}/api/-/settings/site/extensions/dashboard/safeListItems
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 usingInitiate File Upload.
You callAppend 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 callPublish Data Source,Publish Flow, orPublish Workbook to commit the file.
For more information, seePublishing 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 as3.27. For more information, seeREST 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 usingInitiate File Upload. |
Request Body
The content of the file to be uploaded is included in a MIME multipart message. For more information, seePublishing 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).
tableau:file_uploads:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Batch Add or Update Data Quality Certifications
Create or update one or more data quality certifications for different content and asset items.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theUpdate Labels method instead.
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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
Request Body
<tsRequest> <contentList><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /> </contentList> <dataQualityIndicator type="type" message="message"active="state" elevated="severity" /></tsRequest>Attribute Values
Any combination of attributes inside the<dataQualityIndicator> element is valid, howevertype andmessage 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-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 theServer Help orCloud 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Response Body
Example response
<tsRequest> <dataQualityIndicatorList><dataQualityIndicator 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 /> <owner /></dataQualityIndicator><dataQualityIndicator 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 /> <owner /><dataQualityIndicator> </dataQualityIndicatorList></tsRequest>Version
Version 3.13 and later. For more information, seeREST 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theUpdate Labels method instead.
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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
Request Body
<tsRequest> <contentList><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /> </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-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:
|
| 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 theServer Help orCloud 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 theServer Help orCloud Help. |
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response
<tsRequest> <dataQualityWarningList><dataQualityWarning 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 /> <owner /></dataQualityWarning><dataQualityWarning 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 /> <owner /><dataQualityWarning> </dataQualityWarningList></tsRequest>Version
Version 3.12 and later. For more information, seeREST 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, seeTag 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 as3.27. For more information, seeREST 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></content> <content></content> <content></content> <content></content> <content></content> <content></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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:tags:batch_createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response
<tsRequest> <tagBatch><tags> <tag label="PII"></tag> <tag label="Noteworthy"></tag></tags><contents> <content contentType="Database"></content> <content contentType="Table"></content> <content contentType="Column"></content> <content contentType="Datasource"></content> <content contentType="Workbook"></content> <content contentType="Flow"></content></contents> </tagBatch></tsRequest>Version
Version 3.9 and later. For more information, seeREST 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 Pulse 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.Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can create subscriptions.Permissions Overview
License: No additional license required.
Access Scope: `tableau:metric_subscriptions:create`
Access ScopesTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/subscriptions:batchCreate
Batch Delete Data Quality Warnings
Delete multiple data quality warnings from assets.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theDelete Labels method 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-id/dataQualityWarnings/batchDelete
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
Request Body
<tsRequest> <contentList><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /> </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-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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.12 and later. For more information, seeREST 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, seeTag 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 as3.27. For more information, seeREST 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></content> <content></content> <content></content> <content></content> <content></content> <content></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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:tags:batch_deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
Example response
<tsRequest> <tagBatch><tags> <tag label="PII"></tag> <tag label="Noteworthy"></tag></tags><contents> <content></content> <content></content> <content></content> <content></content> <content></content> <content></content></contents> </tagBatch></tsRequest>Version
Version 3.9 and later. For more information, seeREST 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 Pulse 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.Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can create subscriptions.Permissions Overview
License: No additional license required.
Access Scope: `tableau:metric_subscriptions:read`
Access ScopesTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/subscriptions:batchGetMetricFollowerCounts
Batch get Pulse 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.Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of subscriptions.Permissions Overview
License: No additional license required.
Access Scope: `tableau:metric_subscriptions:read`
Access ScopesTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/subscriptions:batchGet
Batch list metric definitions (few)
Gets the details of a batch of metric definitions and metrics on a site, specified in a brief comma delimited list of LUIDs.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/definitions:batchGet
Batch list metric definitions (many)
Gets the details of a batch of definitions specified in a comma delimited list of LUIDs. This method is optimized for batches with large numbers of definitions.
Version: Available in API 3.24 (Tableau Cloud December 2024) and later. Not available for Tableau Server.Version Overview
Permissions: Any user can make this request but users will see results only for metrics they have permissions to view.Permissions Overview
License: No additional license required.
Access Scope: `tableau:insights:read`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/definitions:batchGet
Batch list metrics (few)
Gets a batch of metrics from a definition, specified in a comma delimited list.
Version: Available in API 3.26 (Tableau Cloud September 2025) and later. Not available for Tableau Server.Version Overview
Permissions: Any user can get a batch of metrics as long as the user has read or connect access to the data source used in the definition that contains them.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
Batch list metrics (many)
Gets batches of metrics available on a server. Only metrics a user has privileges to view will be visible. This endpoint uses POST as an alternative to GET, where long lists of URL parameters could be problematic.
Version: Available in API 3.26 (Tableau Cloud September 2025) and later. Not available for Tableau Server.Version Overview
Permissions: Any user can get a batch of metrics as long as the user has read or connect access to the data source used in the definition that contains them.Permissions Overview
License: No additional license required.
Access Scope: `tableau:insight_metrics:read`
Access Scopes Overview:Tableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/metrics:batchGet
Batch Update Schedule State
Updates the state of one or more schedules.
Use theupdateAll URI parameter to update the state of all schedules in a single call.
Version: Available in API 3.27 (Tableau Server 2025.3 and later. Not available for Tableau Cloud.)
License: No additional license required.
Permissions: Only server administrators.
Access Scope:tableau:schedules:update
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/schedules?state=state-enum
PUT /api/api-version/schedules?state=state-enum&updateAll=update-all-flag
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| state-enum | Required, enum. Eitheractive orsuspended. The state for the schedule(s). |
update-all-flag | Optional, boolean. If |
Note: A common use case for this method is suspending all schedules before a maintenance window using theupdateAll URI parameter. If, after the maintenance window, you use the same tactic andactivate all schedules using theupdateAll URI parameter, you risk activating schedules that may have been intentionally suspended in the past, before you usedupdateAll to suspended all schedules.
Instead, when suspending all schedules using theupdateAll URI parameter, note which schedule LUIDs appear in the response body. This tells you which schedules were changed from active to suspended. Then, after the maintenance window, re-activatate only those schedules, notall schedules.
Request Body
<tsRequest> <scheduleLuids> <scheduleLuid>schedule-id</scheduleLuid> <!-- ... additional scheduleLuid elements ... --> </scheduleLuids></tsRequest>
{ "scheduleLuids": { "scheduleLuid": [ "schedule-id" ] }}Request Attributes
schedule-id | The LUID of the schedule. You can include multipleschedule-ids using additional Note: If the |
cURL Request Example
curl "https://MY-SERVER/api/3.27/schedules?state=active&updateAll=true" -X PUT -H "X-Tableau-Auth: a1B2c3D4e5F6g7H8i9J0kL|a1B2c3D4e5F6g7H8i9J0kL1m2N3o4P5q|12345678-90ab-4cde-8f01-234567890abc" -d @data.xmlContent of data.xml:
<tsRequest> <scheduleLuids> <scheduleLuid>12ab34cd-56ef-78ab-90cd-12ef34ab56cd</scheduleLuid> <scheduleLuid>08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6</scheduleLuid> </scheduleLuids></tsRequest>
Response Code
200
Response Body
The response body is a list of schedules that were updated with the call.
<tsResponse> <scheduleLuids> <scheduleLuid>schedule-id</scheduleLuid> <!-- ... additional scheduleLuid elements ... --> </scheduleLuids></tsResponse>{ "scheduleLuids": { "scheduleLuid": [ "schedule-id" ] }}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Generic error | An unknown error occurred. The content of the request body may be missing or incomplete, or may contain malformed XML. |
| 403 | 403188 | Permissions error | User calling the method isn't a server administrator. |
| 403 | 403189 | Invalid LUID | One or more of the schedule LUIDs isn't a valid LUID. |
| 404 | 404023 | LUID not found | One or more of the schedule LUIDs isn't found. |
| 405 | 405000 | Availability error | This method only exists on Tableau Server. Tableau Cloud isn't supported. |
| 409 | 409004 | Parameter error | The state parameter is absent or not recognized; or the updateAll parameter was absent or false and no schedule LUIDs were provided. |
For more information, seeHandling Errors.
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 withTableau 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
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 as3.27. For more information, seeREST 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flow_runs:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.10 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling 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 theQuery Jobs method.
The following jobs can be canceled using theCancel 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. SeeView 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:jobs:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.1 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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.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
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. Iftrue (default), the newly created webhook is enabled. Iffalse then the webhook will be disabled. |
Permissions
This method can only be called by server and site administrators.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:webhooks:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Response Body
<tsResponse> <webhook 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 name="webhook_owner_name"/> </webhook></tsResponse>
Response Headers
Location: /api/3.27/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 ifthe 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The LUID of the site. |
| datasource-id | The LUID of the datasource. |
| encryption-flag | Iftrue, then Tableau will attempt to encrypt the created extracts.Iffalse, or noencrypt parameter is appended to the URI, then the extract won'tbe encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned whenencrypt equalstrue 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 userswho own the data source or are an owner or leader of the project where the data source resides.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:extracts:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <job mode="Asynchronous" type="CreateExtract" createdAt="date-time"> <extractCreationJob> <datasourceapi-placeholder">datasource-id" name="datasource-name" /> </extractCreationJob></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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 notPOST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z"> <extractCreationJob> <datasource 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, seeHow 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
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.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
Create Cloud Extract Refresh Task
Creates a custom schedule for an extract refresh on Tableau Cloud.
For Tableau Server, seeAdd data source to server schedule andAdd 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
<tsRequest> <extractRefresh type="FullRefresh"> <workbook /> </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>
{ "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 arerequired to create a custom schedule for an extract refresh.
extractRefresh type | enumeration: The type of extract refresh being scheduled. Valid values include:
|
workbook idor datasource id | LUID: The LUID of the workbook or datasource that is the target of the custom schedule. |
schedule frequency | (Required to create subscription) enumeration: The scheduled frequency for triggering the task. Valid values include:
| ||||||||||
frequencyDetails start | (Required to create subscription) time: If the schedule frequency isDaily, Weekly, or Monthly, thenstartis the time of day on which scheduled jobs should run. If the frequency isHourly, thenstart is the beginning of thetime range during which jobs should be started. The valid format isHH:MM:SS. | ||||||||||
frequencyDetails end | (Required to create subscription) time: If the schedule frequency is | ||||||||||
interval{interval type} | (Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in thestart andend values of thefrequencyDetails of theschedule. The type and valid values foran interval expression depend on the declaredfrequency of theschedule as follows:
|
cURL Request Example
curl --location --request POST "qa-near.tsi.lan/api/3.27/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
<tsResponse> <extractRefresh consecutiveFailedCount="0" type="IncrementalRefresh" > <datasource /> </extractRefresh> <schedule 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>{ "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 betweenstart andend times are not increments of one hour,this error will result. |
For more information, seeHandling Errors.
Create Cloud Flow Task
Creates a flow task on Tableau Cloud, and set its schedule.
Note: This method is unavailable if you do not have aData Management license or Tableau Prep Conductor is disabled for your site.
Version:Available in API 3.22 (Tableau Cloud April 2024) and later. Not available for Tableau Server.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:A user can create a cloud flow task if you are a site or server administrator, or they own the flow,or are the project leader for the project that contains the workbook. Permissions Overview(Link opens in a new window)
JWT Access Scope:Not available.
URI
POST /api/api-version/sites/site-luid/tasks/flows
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
<tsRequest> <task> <flowRun> <flow/> </flowRun> </task> <schedule frequency="Daily"> <frequencyDetails start="12:30:00" end="23:30:00"> <intervals> <interval hours="4"/> <interval weekDay="Monday"/> <interval weekDay="Wednesday"/> </intervals> </frequencyDetails> </schedule></tsRequest>
{ "task": { "flowRun": { "flow": { "id": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541" } } }, "schedule": { "frequency": "Daily", "frequencyDetails": { "start": "12:30:00", "end": "23:30:00", "intervals": [ { "hours": "4" }, { "weekDay": "Monday" }, { "weekDay": "Wednesday" } ] } }}
Request Attributes
flow.id | (Required)The LUID of the flow the task is being scheduled for. |
schedule frequency | (Required to create subscription) enumeration: The scheduled frequency for triggering the task. Valid values include:
| ||||||||||
frequencyDetails start | (Required to create subscription) time: If the schedule frequency isDaily, Weekly, or Monthly, thenstartis the time of day on which scheduled jobs should run. If the frequency isHourly, thenstart is the beginning of thetime range during which jobs should be started. The valid format isHH:MM:SS. | ||||||||||
frequencyDetails end | (Required to create subscription) time: If the schedule frequency is | ||||||||||
interval{interval type} | (Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in thestart andend values of thefrequencyDetails of theschedule. The type and valid values foran interval expression depend on the declaredfrequency of theschedule as follows:
|
cURL Request Example
curl "http://MY-SERVER/api/3.27/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
<tsResponse> <task> <flowRun priority="50" consecutiveFailedCount="0" type="RunFlowTask"> <schedule name="SSS_e95a9d25-c616-4542-87b6-3725975bdfbd" state="Active" priority="50" createdAt="2024-04-09T18:54:12Z" updatedAt="2024-04-09T18:54:12Z" type="Flow" frequency="Daily" nextRunAt="2024-04-10T19:30:00Z"/> <flow name="olympic 1"> <parameters> <parameter type="integer" name="output_count" description="This is a parameter of a flow." value="2" isRequired="true"> <domain xsi:type="flowParameterAnyDomainType" domainType="all"/> </parameter> </parameters> </flow> <flowRunSpec flowId="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"> <flowOutputSteps> <flowOutputStep name="Output"/> </flowOutputSteps> <flowParameterSpecs/> </flowRunSpec> </flowRun> </task></tsResponse>{ "task": { "flowRun": { "id": "4d49655a-0f3a-45cc-ba61-b108a763e83a", "priority": "50", "consecutiveFailedCount": "0", "type": "RunFlowTask", "schedule": { "id": "1060dcb7-fef7-4fb1-8d3b-d0f042932d1a", "name": "SSS_e95a9d25-c616-4542-87b6-3725975bdfbd", "state": "Active", "priority": "50", "createdAt": "2024-04-09T18:54:12Z", "updatedAt": "2024-04-09T18:54:12Z", "type": "Flow", "frequency": "Daily", "nextRunAt": "2024-04-10T19:30:00Z" }, "flow": { "id": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541", "name": "olympic 1", "parameters": { "parameter": { "id": "4f22c514-5b56-4400-a48a-f69d9be217a9", "type": "integer", "name": "output_count", "description": "This is a parameter of a flow.", "value": "2", "isRequired": "true", "domain": { "xsi_type": "flowParameterAnyDomainType", "domainType": "all" } } } }, "flowRunSpec": { "flowId": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541", "flowOutputSteps": { "flowOutputStep": { "id": "485c8b5f-5647-466c-b549-e38410b7c7c8", "name": "Output" } }, "flowParameterSpecs": [] } } }}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, seeHandling Errors.
Create Connected App
Create a connected app.
A connected app can be used to securely authenticate your users to Tableau content embedded in a custom application or for REST API authorization (introduced to Tableau Cloud in June 2022 and Tableau Server 2023). By creating a connected app, you can establish a trusted relationship between Tableau and any custom application.
For more information about connected apps, see one of the following:
- For Tableau Server:Configure Tableau Connected Apps to Enable SSO for Embedded Content
- For Tableau Cloud:Configure Tableau Connected Apps with Direct Trust(Link opens in a new window)
URI
POST api/api-version/sites/site-id/connected-apps/direct-trust
Note: Theconnected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
Request Body
Tableau Cloud and Tableau Server using API 3.23 or later
<tsRequest> <connectedApplicationname="name"enabled="enabled"domainSafelist="domainSafelist"unrestrictedEmbedding="unrestrictedEmbedding"><projectIds><projectId>project_id</projectId><projectId>project_id</projectId><projectId>project_id</projectId></projectIds> </connectedApplication></tsRequest>Tableau Server (or Tableau Cloud) using API 3.21 or earlier
<tsRequest> <connectedApplicationname="name"enabled="enabled"projectId="project_id"domainSafelist="domainSafelist"unrestrictedEmbedding="unrestrictedEmbedding" /></tsRequest>Attribute Values
Any combination of attributes inside the<connectedApplication> element is valid, howevername 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, seeQuery Projects. You can specify one project, multiple projects, all projects on a site.
Note: The stand-aloneprojectId attribute will be retired in a future release so we recommend usingprojectIds 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 inDomain allowlist rules(Link opens in a new window) in the Tableau Server Help orDomain allowlist rules(Link opens in a new window) in the Tableau Cloud Help. Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. For example: |
| 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:connected_apps_direct_trust:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 theprojectId attribute.
Version
Version 3.14 and later. For more information, seeREST API and Resource Versions.
The resource, POST /api/api-version/sites/site-id/connected-apps/direct-trust, was added in version 3.17. The original resource, POST /api/api-version/sites/site-id/connected-applications, was deprecated in API 3.17 and will be retired in a future release.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400109 | Bad request | The request body can't be empty. |
| 400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
| 403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
| 404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404041 | Connected app not found | The requested connected app could not be found. |
Create Connected App Secret
Generate a secret for a connected app.
Secrets are tokens shared by Tableau and a custom application, and used to establish a trusted relationship.
A maximum of two secrets can be associated with a connected app. These secrets do not expire and remain valid until deleted. If a connected app has already reached its two secret maximum when another one is generated, an error is thrown.
URI
POST api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets
Note: Theconnected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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, seeREST 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 custom domain settings
Starts the process of custom domain setup for a Tableau site.
Version: Available in API 3.26 (Tableau Cloud June 2025) and later. Not available for Tableau Server.Versioning OverviewVersion Overview
Permissions: Only users with administrator permissions can create a custom domain for a site.Permissions OverviewPermissions Overview
License: No additional license required.
Access Scope: Not available.
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/customdomains/settings/site/{site_luid}
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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/dataAlerts
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
<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>{
"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:
|
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:
|
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:
|
dataAlertCreateAlert device | (Optional) Enumeration: The type of device the alert is formatted for.If no
|
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 viewIdOR
| (Required) LUID: The LUID of either theviewId orcustomViewId that contains the data that can trigger an alert. |
cURL Request Example
curl http://MY-SERVER/api/3.27/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
<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>{
"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 haveadministrator, 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 aslimited. |
| 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, seeHandling 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 haveconfiguration 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 aworkbook data source for a published data source, then refreshing the workbook extract will retrieve any changes to datafrom 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 theRunNow setting for the site. For more information, seeTableau 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The LUID of the site. |
| workbook-id | The LUID of the workbook. |
| encryption-flag | Iftrue, then Tableau will attempt to encrypt the created extracts.Iffalse, or noencrypt parameter is appended to the URI, then the extract won'tbe encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned whenencrypt equalstrue and encryption is disabled in the site or workbook. |
Request Body
<tsRequest> <datasources includeAll="extract-all-datasources-flag"><datasourceapi-placeholder">datasource-id" /> </datasources></tsRequest>Request Parameter Values
| datasource-id | LUID of the embedded data source to be extracted. |
| extract-all-datasources-flag | Boolean. Iftrue, then all data sources in the workbook will have an extract created for them.Iffalse, 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 userswho own the workbook, or are an owner or leader of the project where the workbook resides.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:extracts:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <job mode="Asynchronous" type="CreateExtract" createdAt="date-time"> <extractCreationJob> <workbookapi-placeholder">workbook-id" name="workbook-name" /></extractCreationJob> </job></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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 notPOST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 ofcreate-extracts-for-workbook.xml
<tsResponse> <datasources includeAll="false" /> <datasource /> </datasources></tsRequest>Response body:
<tsResponse> <job mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z"><extractCreationJob> <workbook 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, callAdd User To Group. To make changes to an existing group, callUpdate 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.
TheCreate 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 theLocation 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 callingQuery 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 as3.27. For more information, seeREST 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 tofalse (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 totrue, the process runs asynchronously. In that case, Tableau Server starts a job to perform the import and returns the job ID in theLocation header. You can check the status of the import job by callingQuery 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 andminimumSiteRole is specified, users are granted alicense 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 withgrantLicenseMode, asiteRole 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. Thesource attribute of the<import> element must be set toActiveDirectory.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 DirectorysAMAccountName 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 animport element orgrantLicenseModeattribute are present in the request. For Tableau Server, the site role assigned to users who are imported from Active Directory or granted alicense 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 onespecified in the request, based on the role that enables the most capabilities. This is true whether the group the user belongs to isimported from Active Directory (Tableau Server only) or local. Site roles that can be assigned, listed from the one enabling the least capabilities tothe most, are as follows.
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 isonLogin, a license is granted for each group member when they log in to a site. For local groups, the mode can be eitheronLogin 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 eitheronSyncoronLogin. The minimum role granted to users throughgrantLicenseMode is specified in thesiteRole attribute. If that role has less permissions than an existing roleassigned 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 withEmbedded Analytics(Link opens in a new window) usage-based model. Set totrue to enable the capability for the group or set tofalse 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) orOn-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).
tableau:groups:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201, for creating a local group and for importing immediately
202, for importing using a background process
Response Headers
Location: /api/3.27/sites/site-id/groups/new-group-id
Response Body
Creating a local group:
<tsResponse> <groupapi-placeholder">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> <groupapi-placeholder">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> <jobapi-placeholder">job-id" mode="Asynchronous" type="GroupImport" progress="0" createdAt="time-job-created" /></tsResponse>Version
Version 3.9 and later. For more information, seeREST 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 theminimumSiteRole orsiteRole attribute must beCreator,Explorer,ExplorerCanPublish,SiteAdministratorCreator,SiteAdministratorExplorer,Unlicensed,orViewer. |
| 400 | 400019 | Malformed import element | When the<import> element is present in the request body, the following attributes must be specified:source with the valueActiveDirectory;domainName;andsiteRoleIf 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 notPOST. |
| 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, seeHandling Errors.
Example: Local Group
curl "http://MY-SERVER/api/3.27/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.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d
Response body:
<tsResponseversion-and-namespace-settings> <group name="marketing-group" ephemeralUsersEnabled="true"/></tsResponse>Example: Active Directory Group
curl "http://MY-SERVER/api/3.27/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 name="marketing-group"> <import domainName="MY-DOMAIN" siteRole="Viewer" grantLicenseMode="onLogin" /> </group></tsRequest>Response header:
Location: /api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d
Response body:
<tsResponseversion-and-namespace-settings> <group 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 callingAdd Group to Group Set.
Version:Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site to create the group in. |
Request Body
<tsRequest>
<groupSet name="newGroupSet" />
</tsRequest{
"groupSet": {
"@name": "marketing-group"
}
}Request Attributes
name | (Required) Name of the new group set. |
cURL Request Example
curl "http://MY-SERVER/api/3.27/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
<tsRequest>
<groupSet
name="marketing-group"
groupCount="0" />
</tsRequest>{
"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 theminimumSiteRole orsiteRole attribute must beSiteAdministratorCreator orSiteAdministratorExplorer. |
| 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’tPOST. |
| 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, seeHandling 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.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
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 theData Labels in the REST API(Link opens in a new window) topic.
AData 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The unique LUID of the site asset. |
Request Body
<tsRequest> <labelCategory name="label-category-name" description="label-category-description" /></tsRequest>Attribute Values
| label-category-name | The label category name. Required. Must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.) |
| label-category-description | The label category description. Required. Must be 1-500 characters in length. |
Permissions
- Only a site or server administrator can create, update, or delete label categories.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_categories:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 |
|
Create metric
Creates a metric.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/metrics
Create metric definition
Creates a metric definition.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server.Version Overview
Permissions: Any user can create a metric definition as long as the user has write and 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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/definitions
Create metric tag for user
Creates a tag for the specified metric, for the signed in user.
Version: Available in API 3.25 (Tableau Cloud March 2025) and later. Not available for Tableau Server.Version Overview
Permissions: Anyone can make this request but users will see results only for metrics they have permissions to view.Permissions Overview
License: No additional license required.
Access Scope: `tableau:insight_metrics:read`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/metrics/{metric_id}/tag
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 totest the configuration(Link opens in a new window) andadd users(Link opens in a new window).
For more information about OIDC authentication in Tableau Cloud, seeOpenID 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.
URI
PUT /api/api-version/sites/site-luid/site-oidc-configuration
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
<tsRequest>
<siteOIDCConfiguration
idpConfigurationName="idpConfigurationName"
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>{
"siteOIDCConfiguration": {
"idpConfigurationName": "idpConfigurationName",
"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
idpConfigurationName | (Required) The name of the configuration. Starting in API 3.24, you can create and enable multiple authentication configurations. For more information, seeAuthentication(Link opens in a new window) in the Tableau Cloud Help. |
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". |
jwksUri | (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 whenuseFullName 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 whenuseFullName 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 whenuseFullName 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.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuration" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-update-oidc-config.xml
Content of create-update-oidc-config.xml:
<tsRequest>
<siteOIDCConfiguration
idpConfigurationName="idpConfigurationName"
enabled="enabled"
clientId="clientId"
clientSecret="clientSecret"
authorizationEndpoint="authorizationEndpoint"
tokenEndpoint="tokenEndpoint"
userinfoEndpoint="userinfoEndpoint"
jwksUri="jwksUri"
idpConfigurationName="idpConfigurationName"
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
<tsResponse>
<siteOIDCConfiguration
idpConfigurationName="Auth_External_OIDC"
enabled="true"
testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
allowEmbeddedAuthentication="false"
clientId="0oa111usf1gpUkVUt0h1"
clientSecret="<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>{
"siteOIDCConfiguration": {
"idpConfigurationName":"Auth_External_OIDC",
"enabled":"true",
"testLoginUrl":"https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC",
"allowEmbeddedAuthentication":"false",
"clientId":"0oa111usf1gpUkVUt0h1",
"clientSecret":"<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"
}
}Notes:
The response hides the client secret and replaces it with
<omit>.You can use thetestloginURL attribute 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, seeHandling 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 theUpdate labelValue method. If you want to change the name on an existing label value, use theUpdate 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 theData Labels in the REST API(Link opens in a new window) topic.
AData 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The unique LUID of the site asset. |
Request Body
<tsRequest> <labelValue name="label-value-name" category="label-value-category" description="label-value-description" /></tsRequest>Attribute Values
| label-value-name | The label value name. Required. If you specify an existing label value name, this method will update the label value. If you specify a label value name that's different than existing label value names, this method will create the label value. Required. Must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.) |
| label-value-category | The label value category. Required. If you're updating an existing label value, this must match the existing category for that label value. |
| label-value-description | The label value description. Required, but does not need to be different than the existing description. Must be 1-500 characters in length. |
Permissions
- Only a site or server administrator can create, update, or delete label values.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_values:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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/> </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 thecertification category. |
| 409 | 409004 | Invalid parameter |
|
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, callUpdate 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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 thepublish-value is not specified in the request, or thepublishSamples parameter is missing, no samples will be published. To publish the sample workbooks, setpublishSamples parameter totrue. This option is equivalent to thetabcmd command-line utility option,publishsamples. For more information, seetabcmd(Link opens in a new window). |
Request Body
<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/>
</project>
</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"
}
}
}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 theparentProjectId attribute. For information about how permissions are evaluated in project hierarchies, seeProject Permissions States and Defaults. |
project contentPermissions | (Optional) This value controls user permissions in a project, however, if the project is nested within a projectwith more restrictive policies, it will inherit those permissions and these settingswill have no effect. The functional permissions of a project, including those it inherits, are available in value ofcontentPermission in the response body from a request to create, update, or query a project.
The default isManagedByOwner. For more information, seeLock 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
<tsResponse>
<project
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/>
</project>
</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"
}
}
}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 toLockedToProjectWithoutNested 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 notPOST. |
| 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, seeHandling Errors.
Create SCIM Configuration
Creates the System for Cross-domain Identity Management Configuration (SCIM) configuration on the Tableau Cloud site.
The SCIM capability requires that you configure your Tableau Cloud site to support SAML authentication and associate the SCIM configuration with the SAML authentication configuration. For more information about the SCIM capability in Tableau, seeSCIM(Link opens in a new window) in the Tableau Cloud Help.
Version: Available in API 3.26 (Tableau Cloud August 2025) and later.
License: No additional license required.
Permissions: Tableau Cloud site admins only.
Access Scope:tableau:scim_configurations:create
Scope added in API 3.27 (Tableau Cloud December 2025)
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),access scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/scimConfigurations
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
<tsRequest> <scimConfiguration> <name>SCIM Contractors</name> <idpConfigurationId>d3b782da-0787-44ca-8585-6fd48dbfc658d3b782da-0787-44ca-8585-6fd48dbfc658</idpConfigurationId> </scimConfiguration></tsRequest>
{"scimConfiguration": { "name": "SCIM Contractors", "idpConfigurationId": "d3b782da-0787-44ca-8585-6fd48dbfc658d3b782da-0787-44ca-8585-6fd48dbfc658" }}
cURL Request Example
POST request: curl --location 'https://prod-ca-a.online.tableau.com/api/3.27/sites/0f04ea64-0d72-424a-afd8-ee7d758dc9b8/scimConfigurations \ --data '{ "scimConfiguration":{ "name": "SCIM Contractors","idpConfigurationId": "d3b782da-0787-44ca-8585-6fd48dbfc658d3b782da-0787-44ca-8585-6fd48dbfc658" } }'
Attribute Values
| name | (Required) Name of the SCIM configuration. |
| idpConfigurationId | (Required) SAML authentication configuration to associate with the SCIM configuration. Starting in API 3.26, you can have multiple SCIM configurations. Include theidpConfigurationId to identify which SAML authentication configuration to associate with this SCIM configuration. To get theidpConfigurationId, seeList Authentication Configurations for Site. |
Response Code
201
Response Body
<tsResponse> <scimConfiguration> <id>065693d8-436a-4738-a8f1-375953a2a888</id> <idpConfigurationId>95dcdf3b-30eb-42ae-b938-7ffca3e11fdc</idpConfigurationId> <isApiTokenActive>false</isApiTokenActive> <isOwner>true</isOwner> <name>SCIM Contractors</name> <createdAt>Tue Apr 01 06:31:47 UTC 2025</createdAt> </scimConfiguration></tsResponse>
{ "scimConfiguration": { "id": "065693d8-436a-4738-a8f1-375953a2a888", "idpConfigurationId": "95dcdf3b-30eb-42ae-b938-7ffca3e11fdc", "isApiTokenActive": false, "isOwner": true, "name": "SCIM Contractors", "createdAt": "Tue Apr 01 06:31:47 UTC 2025" }}
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad Request | The content of the request body is missing or incomplete, contains malformed XML, or theidpConfigurationId is not valid. |
| 400 | 400008 | Bad Request | The content of the request body is missing the SCIM configuration name, contains unsupported attributes, or theidpConfigurationId is missing. |
| 400 | 400802 | Bad Request | The maximum number of 20 SCIM configurations for the site has been reached. |
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header is invalid or has expired. |
For more information, seeHandling Errors.
Create SCIM Token
Generates the System for Cross-domain Identity Management Configuration (SCIM) token and secret.
You must be the user who created the SCIM configuration to generate the associated SCIM token. After the SCIM token is generated, ensure the SCIM token's secret is added to the identity provider's (IdP's) SCIM settings.
Version: Available in API 3.26 (Tableau Cloud August 2025) and later.
License: No additional license required.
Permissions: Tableau Cloud site admins only.
Access Scope: Not available
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),and access scopes forCloud(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/scimConfigurations/scim-configuration-id/apiToken
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| scim-configuration-id | The UUID of the SCIM configuration. To get the SCIM configuration UUID, seeList SCIM Configurations. |
Request Body
None
cURL Request Example
POST request: curl --location 'https://prod-ca-a.online.tableau.com/api/3.27/sites/0f04ea64-0d72-424a-afd8-ee7d758dc9b8/scimConfigurations/065693d8-436a-4738-a8f1-375953a2a888/apiToken'
Response Code
201
Response Body
<tsResponse> <id>065693d8-436a-4738-a8f1-375953a2a888</id> <clientName>SCIM_CLIENT_API_TOKEN:d3b782da-0787-44ca-8585-6fd48dbfc658</clientName> <secret>hqh8YEoYQ1enO9t9Z3h1xA==:X_jndRxNXuWKIXIUbvSGEvysnnSK6B7pt62GiWd8Vuw=</secret></tsResponse>
{ "apiToken": { "id": "065693d8-436a-4738-a8f1-375953a2a888", "clientName": "SCIM_CLIENT_API_TOKEN:d3b782da-0787-44ca-8585-6fd48dbfc658", "secret": "hqh8YEoYQ1enO9t9Z3h1xA==:X_jndRxNXuWKIXIUbvSGEvysnnSK6B7pt62GiWd8Vuw=" }}
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 | 400802 | Bad Request | The SCIM configuration is already associated with a SCIM token. To generate a new token for the SCIM configuration, first delete the associated SCIM token and try again. |
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header is invalid or has expired. |
| 403 | 403182 | Forbidden | A SCIM token can only be generated by the user who created the SCIM configuration. |
| 404 | 404057 | Resource Not Found | The SCIM configuration ID is not valid. |
For more information, seeHandling Errors.
Create Server Schedule
Creates a new server schedule on Tableau Server.
For Tableau Cloud, seeCreate Cloud Extract Refresh Task andCreate subscription.
Schedules are not specific to sites. For more information, seeCreating a Flow Schedule(Link opens in a new window),Extracts and Refresh Schedules(Link opens in a new window) andCreate 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, seeEnable 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 as3.27. For more information, seeREST 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> <intervalinterval-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, orDataAcceleration to create a data acceleration schedule.(Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. SeeView Acceleration(Link opens in a new window).) |
| schedule-execution-order | Parallel to allow jobs associated with this schedule to run at the same time, orSerial to require the jobs to run one after the other. |
| schedule-frequency | This represents the granularity of the schedule.
The value you provide forschedule-frequency determines whether you must include anend-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 formatHH: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 isHourly, the time of day on which scheduled jobs should stop being run, in the formatHH: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 inschedule-frequency.
The interval expression is only one of the following:
You can specify an interval in hours or minutes, but not both.
If the schedule frequency is
The interval expression is You can specify multiple<interval> elements to indicate that scheduled jobs should run on multiple days during the week.
The interval expression is 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:schedules:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Response Body
<tsResponse> <scheduleapi-placeholder">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"> <frequencyDetailsfrequency-expression > <intervals> <intervalinterval-expression /> </intervals> </frequencyDetails> </schedule></tsResponse>Version
Version 2.3 and later. For more information, seeREST 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 notPOST. |
| 409 | 409021 | Schedule name conflict | The schedule name in the request already belongs to an existing schedule. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 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 toDaily. Thestart attribute is required. Nointervals 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> <scheduleid="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 toWeekly. Astart attribute is required. Theintervals element is required, and must include between 1 and 7interval subelements that contain aweekDay attribute. Valid values for theweekDay attribute areSunday,Monday,Tuesday,Wednesday,Thursday,Friday, orSaturday.
<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 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 toMonthly. Astart attribute is required. Theintervals element is required, and must include 1interval subelement that contains amonthDay attribute. Valid values for themonthDay attribute are integers between 1 and 31 and the stringLastDay.
<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> <scheduleid="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, callUpdate Site. This method isn’t available for Tableau Cloud.
For more information, seeWork with Sites(Link opens in a new window)andAdd 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 aquery 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" 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="dqw-subscriptions-enabled" groupAssertionsEnabled="group-assertions-enabled-flag" groupAssertionsSAMLEnabled="group-assertions-saml-enabled-flag" groupAssertionsOIDCEnabled="group-assertions-oidc-enabled-flag" groupAssertionsConnectedAppsEnabled="group-assertions-connected-apps-enabled-flag" groupSetsEnabled="group-sets-enabled-flag" recycleBinEnabled="recycle-bin-enabled-flag" /></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) SpecifyContentAndUsers to allow site administrators to use the serverinterface and Note: You can’t setadminMode toContentOnly and also setuserQuota.The default value isContentAndUsers. |
| 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) Specifytrue to prevent users from being able to subscribe to workbooks on the specified site. The default isfalse. |
| editing-flows-enabled-flag | (Optional) Specifytrue to enable andfalse to disable editing flows for a site. For more information on flows, seeEnable and Configure Tableau Prep Conductor(Link opens in a new window). The default is set totrue, which means editing flows is enabled by default. For more information, seeImplication of disabling Tableau Prep Conductor. |
| scheduling-flows-enabled-flag | (Optional) Specifytrue to enable andfalse to disable scheduling flows for a site. For more information on flows, seeEnable and Configure Tableau Prep Conductor(Link opens in a new window). The default is set totrue which means scheduling flows is enabled by default. For more information, seeImplication of disabling Tableau Prep Conductor. |
| flows-enabled-flag | TheflowsEnabled attribute is deprecated as of API version 3.10. |
| allow-subscription-attachments-flag | (Optional) Iftrue, 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 defaultvalue istrue. If subscription to attachments is disabled in the server settings,then making this valuetrue will have no effect.Default istrue. |
| guest-access-enabled-flag | (Optional) Specifytrue to enable andfalse to disable the ability for guests, users without specific site access permission, to access the site.Default isfalse. |
| cache-warmup-enabled-flag | This attribute is removed in API 3.19 and later (Tableau Cloud September 2021). For currentmethods to improve Tableau performance see,View Acceleration(Link opens in a new window). (Optional) Set this value totrue to enable cache warm up to improve workbook load time. Set the value tofalse to disable cache warmup.Default istrue. |
| commenting-enabled-flag | (Optional) Specifytrue to enable andfalse to disable the ability for user comments on views in the site.Default istrue. |
| revision-history-enabled | (Optional)true if the site maintains revisions for changes toworkbooks and data sources; otherwise,false. The default isfalse. |
| 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) Specifytrue to enable andfalse to disable the ability for view owners to subscribe other users to a view.Default istrue. |
| extractEncryptionMode | (Optional) Specifyenforced,enabled, ordisabled. Default isdisabled.For more information, seeExtract and Encryption Methods. |
| requestAccessEnabled | (Optional) Specifytrue to allow users send access request emails to content or project owners. Specifyfalse if you don’t want users to be able to request access. The default isfalse. |
| runNowEnabled | (Optional) Specifytrue to allow users to run flows, extract refreshes, and schedules manually. Specifyfalse if you don’t want users to be able to run flows, extract refreshes, and subscriptions manually. The default istrue. If this attribute is set tofalse, the following methods will fail and will return an error message. Run Flow Task(Link opens in a new window) |
Licensing attributes | |
User quota all-license-limit-total | (Optional) The maximum total number of users with Creator, Explorer, or Viewer licenses currently allowed on a site. On-premises server administrators can set An administrator can revert the license limit to number of activated licenses on the site, or shift control of licenselimits to tiered capacities values, by omitting |
Tiered capacity attributes creator-license-limit | (Optional) The maximum number of licenses for users with the Creator,Explorer, or Viewer role, respectively, allowed on a site. On-premises server administrators can set tiered capacity attributes with the following rules: the number can'texceed the number of licenses of a given type that are activated for the site; a value must be supplied forevery 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 ofactivated licenses configured for the role. Setting the value of a tiered capacity to -1 will not automaticallyincrease the limit if more licenses are purchased and activated for the role in the future. To use role-specific license limits, the |
data-alerts-enabled-flag | (Optional, boolean) Iftrue, data alerts are enabled on the site. Default value istrue. |
commenting-mentions-enabled-flag | (Optional, boolean) Iftrue, mentions for commenting are enabled. Default value istrue. |
catalog-obfuscation-enabled-flag | (Optional, boolean) Iftrue, catalog obfuscation is enabled on the site. Default value istrue. |
flow-auto-save-enabled-flag | (Optional, boolean) Iftrue, flow auto save is enabled on the site.Default value istrue. |
run-now-enabled-flag | (Optional, boolean) Iftrue, run now for schedules is enabled which allows non-administrators to run schedules manually. Default value istrue. |
metrics-content-type-enabled-flag | (Optional, boolean) Iftrue, the metrics content type is enabled on the server. Default value istrue. |
notify-site-admins-on-throttle-flag | (Optional, boolean) Iftrue, site admins will be notified if their background jobs are being throttled. Default value isfalse. |
authoring-enabled-flag | (Optional, boolean) Iftrue, web authoring is enabled. Default value istrue. |
custom-subscription-email-enabled-flag | (Optional, boolean) Iftrue, sending custom subscription email is enabled. If set to false after being set true, the current custom subscription email is voided. Default value isfalse. |
custom-subscription-email | A valid custom email that will be sent ifcustomSubscriptionEmailEnabled is set to true. Default value isfalse. |
custom-subscription-footer-enabled-flag | (Optional, boolean) Iftrue, 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 isfalse. |
custom-subscription-footer | A custom subscription footer that will be added to subscription and data alerts ifcustomSubscriptionFooterEnabled is set to true. Default value isfalse. |
ask-data-mode | The mode of the ask data feature on the site. Can be set to one of two values:
DisabledByDefault. For more information, seeDisable or Enable Ask Data for a Site(Link opens in a new window). |
named-sharing-enabled-flag | (Optional, boolean) Iftrue, named sharing is enabled. Default value istrue. |
cataloging-enabled-flag | (Optional, boolean) Iftrue, data catalog is enabled for the site. Default value istrue. |
derived-permissions-enabled-flag | (Optional, boolean) Iftrue, derived permissions are enabled for the site. Default value isfalse. |
user-visibility-mode | (Optional, string) When the value isFULL users can see the user of other site users. If the value isLIMITED User information on the site is not visible to other users. Default value isFULL. For more information, seeUser Visibility(Link opens in a new window). |
| use-default-time-zone | Optional, boolean) Set this totrue, if you want thetime-zone attribute use the Server time Zone at run time. This attribute is set to the official IANA name. If this is set tofalse, thetime-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 onWikipedia. |
| 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 from 7 through 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
|
| dqwSubscriptionsEnabled | (Optional, boolean) Set this attribute to
|
| groupAssertionsEnabled | (Optional, boolean) Set totrue to allow assertions into group membership using session info. Set tofalse if you do not want users to be able to be asserted in to groups. The default isfalse. If this attribute is set to false, it will disable group assertions for the entire site, including the following settings:
|
| groupAssertionsSAMLEnabled | (Optional, boolean) Set totrueto allow assertions into group membership using SAML session info. Set tofalseif you don’t want users to be able to be asserted in to groups. The default isfalse. If this attribute is set to false, it will disable group assertions for SAML sessions. |
| groupAssertionsOIDCEnabled | (Optional, boolean) Set to Note: This parameter only applies to Tableau Cloud. |
| groupAssertionsConnectedAppsEnabled | (Optional, boolean) Set totrueto allow assertions into group membership using Connected App JWT tokens. Set tofalseif you don’t want users to be able to be asserted in to groups via connected apps. The default isfalse. If this attribute is set to false, it will disable group assertions for JWT connected app connections. |
| groupSetsEnabled | (Optional, boolean) Set totrueto allow groups sets. Set tofalseif you don’t want group sets support for the site. The default isfalse. If this attribute is set to false, it will disable group sets for the site. |
| recycleBinEnabled | (Optional, boolean) Set totrue to enable the Recycle Bin. Set tofalse to disable it. The default istrue. |
Permissions
This method can only be called by server administrators.
Required scope for JWT authorization
Introduced in Tableau Server 2022.3 (API 3.17).
tableau:sites:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Response Body
<tsResponse> <siteapi-placeholder">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" 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" groupAssertionsEnabled="group-assertions-enabled-flag" groupAssertionsSAMLEnabled="group-assertions-saml-enabled-flag" groupAssertionsOIDCEnabled="group-assertions-oidc-enabled-flag" groupAssertionsConnectedAppsEnabled="group-assertions-connected-apps-enabled-flag" groupSetsEnabled="group-sets-enabled-flag" recycleBinEnabled="recycle-bin-enabled-flag" /> </site></tsResponse>Response Body Details:
- userQuota,storageQuota, and tiered capacity (tierCreatorCapacity,tierExplorerCapacity,tierViewerCapacity) attributes are only present in the response body if those quotas have been set for the site being queried.
Response Headers
Location: /api/3.27/sites/new-site-id
Version
Version 1.0 and later. For more information, seeREST 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 wasn’t a positive number. |
| 400 | 400000 | Invalid user quota | The user quota value wasn’t a positive number. |
| 400 | 400013 | Invalid administrator mode | The user provided an administrator mode that isn’tContentOnly orContentAndUsers. Note: An empty string or all whitespace is invalid. |
| 405 | 405000 | Invalid request method | Request type was notPOST. |
| 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 anduserQuota. One or the other must be null. |
| 409 | 409004 | License limit exceeded | The request cannot set tiered capacity attributes oruserQuota 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 setadminMode toContentOnly and also specify auserQuota value. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 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 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, seeSubscribeto 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 aquery 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 as3.27. For more information, seeREST 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 unified access token (UAT) or connected app. For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orTableau Cloud connected app scopes(Link opens in a new window) orTableau Server connected apps scopes(Link opens in a new window).Available in API 3.20 (Tableau Cloud June 2023) / Tableau Server 2023.3.
Tableau Server Request
Create a subscription task and add it to a server schedule on Tableau Server.
For Tableau Cloud, seeTableau Cloud Request.
Request Body
<tsRequest> <subscription subject="subscription-subject" attachImage="attach-image-flag" attachPdf="attach-pdf-flag" pageOrientation="page-orientation" pageSizeOption="page-size-option" message="message" suspended="suspended-flag"> <content type="content-type" sendIfViewEmpty="send-view-if-empty-flag" customViewId="custom-view-id"/> <schedule /> <user /> </subscription></tsRequest>
{ "subscription": { "subject": "subscription-subject", "attachImage": "attach-image-flag", "attachPdf": "attach-pdf-flag", "pageOrientation": "page-orientation", "pageSizeOption": "page-size-option", "message": "message", "suspended": "suspended-flag", "content": { "id": "content-id", "type": "content-type", "sendIfViewEmpty": "send-view-if-empty-flag", "customViewId": "custom-view-id" }, "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 If subscriptions to attachments are disabled in Tableau server or site settings,then making a request that sets |
| attach-pdf-flag | (Optional) Setting this If subscriptions to attachments are disabled in Tableau server or site settings,then making a request that sets |
| page-orientation | (Optional) The orientation of the pages produced whenattach-pdf-flagistrue. The value can bePortrait orLandscape. If this parameter is not present the page orientation will default toPortrait. |
| page-size-option | (Optional) The type of page produced, which determines the page dimensions whenattach-pdf-flag istrue. The value can be:A3,A4,A5,B5,Executive,Folio,Ledger,Legal,Letter,Note,Quarto, orTabloid. If this parameter is not present the page type will default toLetter. |
| message | The text body of the subscription email message. |
| suspended-flag | (Optional) Iftrue, the subscription is created in a disabled state, meaning it won't run until it's enabled using theUpdate Subscription method orResume Subscription in the web UI. The default value isfalse. |
| content-type | Workbook to create a subscription for a workbook, orView to create a subscription for a view. |
| send-view-if-empty-flag | (Optional) Applies to views only. Iftrue, an image is sent even if the view specified in a subscription isempty. Iffalse, nothing is sent if the view is empty. The default value is true. |
| custom-view-id | (Optional) Applies to views only. The LUID of a custom view to use instead of the default view. |
| 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,callList Server Schedules. The type of the schedule must beSubscription. |
| 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 haveRead (view) permissions for.
Response Code
201
Response Body
<tsResponse> <subscription subject="subscription-subject" suspended="suspended-flag" pageOrientation="page-orientation" pageSizeOption="page-size-option" message="message" > <content type="content-type" sendIfViewEmpty="send-view-if-empty-flag"/> <schedule name="schedule-name" /> <user name="user-name" /> </subscription></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" } }}Response Headers
Location: /api/3.27/sites/site-id/subscriptions/new-subscription-idVersion
Available in API 2.3 and later. For more information, seeREST 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 notWorkbook orView. |
| 400 | 400069 | Invalid schedule type | The schedule type is notSubscription. |
| 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 haveRead (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 notPOST. |
For more information, seeHandling Errors.
Tableau Cloud Request
Create a subscription task and define its frequency on Tableau Cloud.
For Tableau Server, seeTableau 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
<tsRequest> <subscription subject="finance report" attachImage="true" attachPdf="true" pageOrientation="true" pageSizeOption="Folio" message="Daily finance report" suspended="false"> <content type="Workbook" sendIfViewEmpty="false" customViewId="12ab34cd-56ef-78ab-90cd-12ef34ab56cd"/> <user/> </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>
{ "subscription": { "subject": "finance report", "attachImage": "true", "attachPdf": "true", "pageOrientation": "true", "pageSizeOption": "Folio", "message": "daily finance report", "suspended": "false", "content": { "id": "13237fd-6365-44d5-925b-644e5281b605", "type": "Workbook", "sendIfViewEmpty": "false", "customViewId": "12ab34cd-56ef-78ab-90cd-12ef34ab56cd" }, "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 arerequired 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 If subscriptions to attachments are disabled in Tableau server or site settings,then making a request that sets |
subscription attachPdf | boolean: Setting this If subscriptions to attachments are disabled in Tableau server or site settings,then making a request that sets |
subscription pageOrientation | enumeration: The orientation of the pages produced whenattach-pdf-flagistrue. The value can bePortrait orLandscape. If this parameter is not present the page orientation will default toPortrait. |
subscription pageSizeOption | enumeration: The type of page produced, which determines the page dimensions whenattach-pdf-flag istrue. The value can be:A3,A4,A5,B5,Executive,Folio,Ledger,Legal,Letter,Note,Quarto, orTabloid. If this parameter is not present the page type will default toLetter. |
subscription message | string: The text body of the subscription email message. |
subscription suspended | boolean: Iftrue, the subscription is created in a disabled state, meaning it won't run until it's enabled using theUpdate Subscription method orResume Subscription in the web UI. The default value isfalse. |
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, orView to create a subscription for a view. |
content sendIfViewEmpty | boolean: Applies to views only. Iftrue, an image is sent even if the view specified in a subscription isempty. Iffalse, nothing is sent if the view is empty. The default value is true. |
content customViewID | string: Applies to views only. The LUID of a custom view to use instead of the default view. |
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 task. Valid values include:
| ||||||||||
frequencyDetails start | (Required to create subscription) time: If the schedule frequency isDaily, Weekly, or Monthly, thenstartis the time of day on which scheduled jobs should run. If the frequency isHourly, thenstart is the beginning of thetime range during which jobs should be started. The valid format isHH:MM:SS. | ||||||||||
frequencyDetails end | (Required to create subscription) time: If the schedule frequency is | ||||||||||
interval{interval type} | (Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in thestart andend values of thefrequencyDetails of theschedule. The type and valid values foran interval expression depend on the declaredfrequency of theschedule as follows:
|
cURL Request Example
curl --location --request POST "qa-near.tsi.lan/api/3.27/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 type="Workbook" sendIfViewEmpty="false"/><user/> </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
<tsResponse> <subscription subject="finance report" attachImage="true" attachPdf="true" pageOrientation="true" pageSizeOption="Folio" message="Daily finance report"> <content type="Workbook" sendIfViewEmpty="false"/> <user/> </subscription> <schedule 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>{ "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 betweenstart andend times are not increments of one hour,this error will result. |
For more information, seeHandling 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.Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can create subscriptions.Permissions Overview
License: No additional license required.
Access Scope: `tableau:metric_subscriptions:create`
Access ScopesTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/subscriptions
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, seeExtract 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site. |
Request Body
None
Permissions
Tableau Server administrators can call this method.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:extract_encryption:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.5 and later. For more information, seeREST 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 notPOST. |
For more information, seeHandling 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:webhooks:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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) and later.Version Overview
Permissions: Can only be called by users with site or 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/site/extensions/analytics/connections/{connection_luid}
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, seeHow 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}
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 methodswill be retired in Tableau Cloud andTableau Server version 2024.1. With advances in natural language technologies, we're developingan improved interface that will make it easier to ask questions of your data and stay on top ofchanges. For more information, seeHow 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 as3.27. For more information, seeREST 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 areChangePermissions,Delete,Move,Read,Write. For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny to remove the deny permission. |
Request Body
None
Permissions
Users with server or site administrator permissions, and non-administrators that haveDelete orChangePermissions 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, seeREST 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 areChangePermissions,Delete,Move,Read, andWrite. |
| 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 thanAllow orDeny). |
| 404 | 404014 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow orDeny). |
| 405 | 405000 | Invalid request method | Request type was notDELETE. |
For more information, seeHandling 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}
Delete Connected App
Permanently remove a connected app.
Deleting the connected app also deletes the secrets associated with the connected app. For more information about deleting a connected app, see one of the following:
- For Tableau Server:Effects of deleting a connected app(Link opens in a new window)
- For Tableau Cloud:Effects of deleting a connected app(Link opens in a new window)
URI
DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id
Note: Theconnected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:connected_apps_direct_trust:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.14 and later. For more information, seeREST API and Resource Versions.
The resource, DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id, was added in version 3.17. The original resource, DELETE api/api-version/sites/site-id/connected-applications/client-id, was deprecated in version 3.17 and will be retired in a future release.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
| 403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
| 404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404041 | Connected app not found | The requested connected app could not be found. |
Delete Connected App Secret
Permanently remove a secret associated with a connected app.
For more information about deleting a connected app, see one of the following:
- For Tableau Server:Effects of deleting a secret(Link opens in a new window)
- For Tableau Cloud:Effects of deleting a secret(Link opens in a new window)
URI
DELETE api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets/secret-id
Note: Theconnected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:connected_app_direct_trust_secrets:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.14 and later. For more information, seeREST 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 domain settings
Deletes the custom domain setup for a Tableau site.
Version: Available in API 3.26 (Tableau Cloud June 2025) and later. Not available for Tableau Server.Versioning OverviewVersion Overview
Permissions: Only users with administrator permissions can view a site's custom domain settings.Permissions OverviewPermissions Overview
License: No additional license required.
Access Scope: Not available.
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
DELETE {server}/api/-/customdomains/settings/site/{site_luid}
Delete Custom View
Deletes the specified custom view.
Version:Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1).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
- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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, seeAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help.
tableau:views:updatecURL 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 orRead 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, seeHandling 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 ofView 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 willalso not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removingany dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releasesresulting 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:data_acceleration_tasks:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 ofView 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 willalso not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removingany dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releasesresulting in error codes being returned.
For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theDelete Label method 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-id/dataQualityCertifications/certification-luid
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Version
Version 3.13 and later. For more information, seeREST 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theDelete Labels method 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-id/dataQualityCertifications
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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" /><content contentType="content" /><content contentType="content" /><content contentType="content" /><content contentType="content" /> </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-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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Version
Version 3.13 and later. For more information, seeREST 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theDelete Labels method 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-id/dataQualityWarnings/content-type/content-luid
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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:
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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.5 and later. For more information, seeREST 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theDelete Label method 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-id/dataQualityWarnings/dataqualitywarning-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.5 and later. For more information, seeREST 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 as3.27. For more information, seeREST 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 haveRead (view) andDelete permissions (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:datasources:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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 haveRead (view) andDelete 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 haveRead (view) permissions on the data source (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.3 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 areChangePermissions,Connect,Delete,ExportXml,Read (view),Write, andSaveAs. For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:deleteResponse Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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 areChangePermissions,Connect,Delete,ExportXml,Read, andWrite. |
| 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 callingQuery 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 as3.27. For more information, seeREST 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 areRead,Write,ChangePermissions, orChangeHierarchy. |
| capability-mode | The permissions mode to remove. Modes that can be removed areAllow orDeny. |
Request Body
None
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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, seeREST 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 theDelete 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 as3.27. For more information, seeREST 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:
For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny to remove the deny permission. |
Request Body
None
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400120 | Bad request | Permissions could not be deleted because support for explicit permissions is available for database assets associated with published data sources only. |
| 401 | 401000 | Unauthorized access | No authorization credentials were provided. |
| 401 | 401002 | Unauthorized access | Invalid authorization credentials were provided. |
| 403 | 403117 | Database locked | Default permissions cannot be deleted because the database asset is locked. |
| 404 | 404000 | Resource not found | The site LUID in the URI doesn't correspond to an existing site. |
| 404 | 404031 | Database not found | The requested database could not be found. |
| 409 | 409045 | Database error | An unknown database asset error occurred. |
| 409 | 409051 | Database update forbidden | A user without "write" permissions to the database asset attempted an update. |
Delete Default Permission
Removes default permission rules for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also removes default permission rules for database or table resources in a project for a user or group. After removing default permission rules, new resources of the type you specify that are added to the project will no longer have those permission rules. If permissions arelocked 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
Virtual Connections(endpoints introduced inAPI version(Link opens in a new window) 3.23):
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections/users/user-luid/capability-name/capability-mode
DELETE /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections/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 as3.27. For more information, seeREST 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
Valid capabilities for a data source are
Valid capabilities for a flow are
For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny 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 haveProjectLeader 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:deleteResponse Code
204
Response Body
None
Version
- Version 2.1 and later.
- Version 3.23 and later for the virtual connection default permissions methods.
- For more information, seeREST 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 thanAllow orDeny 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| eas-id | The unique ID of the registered EAS. |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:external_authorization_servers:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Introduced in Tableau Cloud June 2022 (API 3.16). Introduced in Tableau Server 2024.2 (API 3.23).
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 as3.27. For more information, seeREST 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
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
tableau:tasks:delete (this scope is included in the scope:tableau:tasks)
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can delete an extract refresh task for which they haveRead (view) andDelete permissions (either explicitly or implicitly).
Response Code
204
Response Body
None
Version
Version 3.6 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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/workbooks/workbook-id/deleteExtract
Path Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 userswho 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:extracts:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None.
Version
Version 3.5 and later. For more information, seeREST 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 notPOST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 ofcreate-extracts-for-workbook.xml
<tsResponse> <datasources includeAll="true" /></tsRequest>Response body:
None. Response code is200.
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 as3.27. For more information, seeREST 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).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flows:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.3 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 methodonly if they haveRead (view) permissions on the data source (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.3 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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:
For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny toremove 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 haveChangePermissions permission for flow (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:permissions:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.3 and later. For more information, seeREST 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 areChangeHierarchy,ChangePermissions,Delete,Execute,ExportXml (Download),Read (view), andWrite. |
| 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 thanAlloworDenyat 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 (AlloworDeny). |
| 405 | 405000 | Invalid request method | Request type was notDELETE. |
For more information, seeHandling 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 theAll 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 as3.27. For more information, seeREST 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).
tableau:groups:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.1 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 (Tableau Cloud February 2024 / Server 2024.2) 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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.27/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’tDELETE. |
| 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, seeHandling 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.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}
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.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}
Delete Label
Deletes a data label by its LUID.
You can't delete extract refresh or flow run monitoring warnings (theextract_refresh_failure andflow_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 theTableau Server(Link opens in a new window) andTableau Cloud(Link opens in a new window) Help and the quality warning trigger methods inMetadata Methods.
For more information on data label objects and properties, see theData 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 aData 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 as3.27. For more information, seeREST 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 havewrite 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 assetnot in a project, you must have thechange permissions permission on the associated asset.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 theData Labels in the REST API(Link opens in a new window) topic.
AData 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_categories:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 |
|
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 (theextract_refresh_failure andflow_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 theTableau Server(Link opens in a new window) andTableau Cloud(Link opens in a new window) Help and the quality warning trigger methods inMetadata Methods.
For more information on data label objects and properties, see theData 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 aData 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 as3.27. For more information, seeREST 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. SeeData Labels in the REST API for information on label values and categories. |
Request Body
<tsRequest> <contentList> <content contentType="asset-type" api-placeholder">asset-luid" /> <!-- ... additional content elements ... --> </contentList></tsRequest>Attribute Values
| asset-type | The type of asset. Valid asset types are:
|
| asset-luid | The asset LUID. |
Permissions
- To delete a data label other than a certification label, you must havewrite 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 assetnot in a project, you must have thechange permissions permission on the associated asset.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 | ThecontentType andcontentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrectcontentType, an incorrectcontentID, 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 theData Labels in the REST API(Link opens in a new window) topic.
AData 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_values:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 |
|
| 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.Version Overview
Permissions: Any user can delete a metric from a definition as long as the user has write and 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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
DELETE {server}/api/-/pulse/metrics/{metric_id}
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 methodswill 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 as3.27. For more information, seeREST 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 implicitRead (view) andDelete permission.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
tableau:metrics:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.9 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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.Version Overview
Permissions: Any user can delete a metric definition as long as the user has write and 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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
DELETE {server}/api/-/pulse/definitions/{definition_id}
Delete metric tag
Deletes the specified metric tag.
Version: Available in API 3.25 (Tableau Cloud March 2025) and later. Not available for Tableau Server.Version Overview
Permissions: Anyone can make this request but users will see results only for metrics they have permissions to view.Permissions Overview
License: No additional license required.
Access Scope: `tableau:insight_metrics:read`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
DELETE {server}/api/-/pulse/metrics/{metric_id}/tag/{tag_id}
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 theExternal Assets Default Project, and can also be found inExternal Assets. In Tableau Cloud October 2022 / Server 2022.3 and earlier, external assets are not moved to any other project, but can be found inExternal 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 as3.27. For more information, seeREST 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).
tableau:projects:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.1 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 as3.27. For more information, seeREST 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 areProjectLeader,Read (view), andWrite. For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny 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 haveChangePermissions (version2.0) orProjectLeader (version2.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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:deleteResponse Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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 thecapability-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 thanAllow orDeny for any mode value. |
| 405 | 405000 | Invalid request method | Request type was notDELETE. |
For more information, seeHandling Errors.
Delete Pulse 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.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
DELETE {server}/api/-/pulse/subscriptions/{id}
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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.11 and later. For more information, seeREST 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 as3.27. For more information, seeREST 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:
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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.10 and later. For more information, seeREST 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 SCIM Configuration
Permanently removes the System for Cross-domain Identity Management Configuration (SCIM) configuration from the Tableau Cloud site.
Deleting the SCIM configuration deletes the associated SCIM token. You must be the user who created the SCIM configuration to delete the SCIM configuration unless the creator of the SCIM configuration is no longer a member of the site. After the SCIM configuration is deleted, ensure the SCIM token's secret is also removed from the identity provider's (IdP's) SCIM settings.
Version: Available in API 3.26 (Tableau Cloud August 2025) and later.
License: No additional license required.
Permissions: Tableau Cloud site admins only.
Access Scope:tableau:scim_configurations:delete
Scope added in API 3.27 (Tableau Cloud December 2025)
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),access scopes for UATs(Link opens in a new window) (Cloud) and access scopes for connected apps:Cloud(Link opens in a new window).
URI
DELETE /api/api-version/sites/site-luid/scimConfigurations/scim-configuration-id
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| scim-configuration-id | The UUID of the SCIM configuration. To get the SCIM configuration UUID, seeList SCIM Configurations. |
Request Body
None
cURL Request Example
DELETE request: curl --location --request DELETE 'https://prod-ca-a.online.tableau.com/api/3.27/sites/0f04ea64-0d72-424a-afd8-ee7d758dc9b8/scimConfigurations/065693d8-436a-4738-a8f1-375953a2a888'
Response Code
204
Response Body
None
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header is invalid or has expired. |
| 403 | 403182 | Forbidden | The SCIM configuration can only be deleted by the user who created the SCIM configuration. |
| 404 | 404057 | Resource Not Found | The SCIM configuration cannot be deleted because it does not exist on this site. |
For more information, seeHandling Errors.
Delete SCIM Token
Permanently removes the System for Cross-domain Identity Management Configuration (SCIM) token.
You must be the user that created the SCIM configuration to delete the associated SCIM token unless the creator of the SCIM configuration is no longer a member of the site. After the SCIM token is deleted, ensure the SCIM token's secret is also removed from the identity provider's (IdP's) SCIM settings.
Version: Available in API 3.26 (Tableau Cloud August 2025) and later.
License: No additional license required.
Permissions: Tableau Cloud site admins only.
Access Scope:tableau:scim_api_tokens:delete
Scope added in API 3.27 (Tableau Cloud December 2025)
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),access scopes for UATs(Link opens in a new window) (Cloud) and access scopes for connected apps:Cloud(Link opens in a new window).
URI
DELETE /api/api-version/sites/site-luid/scimConfigurations/scim-configuration-id/apiToken
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| scim-configuration-id | The UUID of the SCIM configuration. To get the SCIM configuration UUID, seeList SCIM Configurations. |
Request Body
None
cURL Request Example
DELETE request: curl --location --request DELETE 'https://prod-ca-a.online.tableau.com/api/3.27/sites/0f04ea64-0d72-424a-afd8-ee7d758dc9b8/scimConfigurations/065693d8-436a-4738-a8f1-375953a2a888/apiToken'
Response Code
204
Response Body
None
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header is invalid or has expired. |
| 404 | 404050 | Resource Not Found | The SCIM configuration does not have an associated SCIM token. |
| 404 | 404057 | Resource Not Found | The SCIM configuration ID is not valid. |
For more information, seeHandling Errors.
Delete Server Schedule
Deletes the specified schedule on Tableau Server.
For Tableau Cloud, seeDelete Extract Refresh Task andDelete Subscription.
URI
DELETE /api/api-version/schedules/schedule-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| schedule-id | The ID of the schedule to delete. To determine what schedules are available, callList Server Schedules. |
Request Body
None
Permissions
This method can only be called by server administrators.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:schedules:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.3 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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, seeCollect Data with the Tableau Server Repository andTableau Server Postgres Data Dictionary. |
Request Body
None.
Permissions
This method can only be called by server administrators.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:sessions:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.9 and later. For more information, seeREST 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 thekey 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 theSign 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 as3.27. For more information, seeREST 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 parameterkey=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.
|
Request Body
None
Permissions
This method can only be called by server administrators.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:sites:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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> <jobapi-placeholder">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 theQuery Job(Link opens in a new window) method.
mode has the value of
Asynchronous.type has the value of
SiteDelete.progress is set to
0when the asynchronous delete job is created, and then changes to100when 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
1when the asynchronous delete job is created, and then changes to0when the job is complete.
Version
Version 1.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
cURL Request Example
Delete site
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
curl "http://MY-SERVER/api/3.27/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.27/sites/async-delete/9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
curl "http://MY-SERVER/api/3.27/sites/async-delete/marketing-site?key=contentUrl" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
curl "http://MY-SERVER/api/3.27/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 theQuery 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 as3.27. For more information, seeREST 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, callQuery Subscriptions. |
JWT Access Scope
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
tableau:tasks:delete (this scope is included in the scope:tableau:tasks)
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Request Body
None
Permissions
Tableau Server users can call this method to delete any subscription that they had permission to create. For details, seeCreate Subscription.
Response Code
204
Response Body
None
Version
Version 2.3 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400062 | Error deleting the subscription. | An unspecified error occurred 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 notDELETE. |
For more information, seeHandling Errors.
Delete Table Permissions
Permanently remove the permissions applied to a table asset.
This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.
URI
DELETE api/api-version/sites/site-luid/tables/table-luid/permissions/users/user-luid/capability-name/capability-mode
DELETE api/api-version/sites/site-luid/tables/table-luid/permissions/groups/group-luid/capability-name/capability-mode
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 areRead,Write,ChangePermissions, orChangeHierarchy. |
| capability-mode | The permissions mode to remove. Modes that can be removed areAllow orDeny. |
Request Body
None
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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, seeREST 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, seeTag 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:column_tags:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.9 and later. For more information, seeREST 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:datasource_tags:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
Delete Tag from Database
Delete a tag from a database.
For more information about tags, seeTag 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:database_tags:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.9 and later. For more information, seeREST 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, seeTag 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:table_tags:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.9 and later. For more information, seeREST 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:view_tags:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
Delete Tag from Virtual Connection
Deletes a tag from a virtual connection.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:You must have theView permission for the virtual connection and your site role must be at leastExplorer. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:virtual_connection_tags:delete
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/tags/tag-name
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| virtualconnection-luid | The LUID for the virtual connection. |
| tag-name | The text of the tag. |
Request Body
None
cURL Request Example
curl --location --request DELETE 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/tags/office' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Response Code
204
Response Body
None
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400077 | Error deleting tag | There was a problem deleting the tag from the specified virtual connection. |
| 403 | 403004 | Deleting tags forbidden | The user doesn't have permissions to add delete tags from the virtual connection. |
| 404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
| 404 | 404004 | Virtual connection not found | The virtual connection ID in the URI doesn't correspond to an existing virtual connection. |
| 404 | 404007 | Tag not found | The tag in the URI doesn't exist for the specified virtual connection. |
| 405 | 405000 | Invalid request method | Request type was notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:workbook_tags:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 userswho own the data source or are an owner or leader of the project where the data source resides.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:extracts:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204 No Content
Response Body
None.
Version
Version 3.5 and later. For more information, seeREST 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 notPOST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 as3.27. For more information, seeREST 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 callingQuery 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 one of the following topics:
For Tableau Cloud -CSV Import File Guidelines(Link opens in a new window)
For Tableau Server -CSV Import File Guidelines(Link opens in a new window)
URI
POST /api/api-version/sites/site-id/users/delete
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 multi-part request is required. For more information on multi-part requests, SeeImporting CSV files with Multipart Requests(Link opens in a new window).
--boundary-stringContent-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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:users:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.15 and later. For more information, seeREST 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, seeHandling 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.csvDelete View
Deletes a view from a workbook.
Use theGet Workbook method or theQuery Views for Workbook method to find the view ID.
If you delete the only view in a workbook, the workbook is deleted.
URI
DELETE /api/api-version/sites/site-id/views/view-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the view. |
| view-id | The ID of the view to remove. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can delete a view for which they haveRead (view) andDelete permissions (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:views:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Introduced in Tableau Cloud December 2025 / Server 2025.3 (API 3.27). For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400212 | Generic error | An unknown error occurred. Try again. |
| 403 | 403004 | Operation on resource unauthorized | Insufficient permissions to perform the operation. Confirm you haveRead andDelete permissions for the view. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. Confirm the site ID. |
| 404 | 404011 | View not found | The view ID in the URI doesn't correspond to an existing view. Confirm the view ID. |
| 405 | 405000 | Invalid request method | The HTTP request method was wrong. Confirm you're using the HTTPDELETE method. |
For more information, seeHandling Errors.
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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 callingQuery 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 areAddComment,ChangePermissions,Delete,ExportData,ExportImage,ExportXml,Filter,Read (view),ShareView,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny 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 haveChangePermissions 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:deleteResponse Code
204
Response Body
None
Version
Version 3.2 and later. For more information, seeREST 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 thanAllow orDeny). |
| 404 | 404014 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow orDeny). |
| 405 | 405000 | Invalid request method | Request type was notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 Virtual Connection
Deletes a virtual connection.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:You must have theDelete permission for the virtual connection and your site role must be at leastCreator. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:virtual_connections:delete
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
DELETE /api/api-version/sites/site-luid/virtualconnections/virtualconnection-luid
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| virtualconnection-luid | The LUID for the virtual connection. |
Request Body
None
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl --request DELETE 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Response Code
204
Response Body
None
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 403 | 403004 | User not authorized. | Check to make sure the user has the required permissions. |
| 404 | 404049 | Virtual connection not found | Check the virtual connection LUID. |
| 409 | 409122 | Generic error | An unknown error occurred. |
For more information, seeHandling Errors.
Delete Virtual Connection Permission
Removes the specified virtual connection permission for the specified group or user.
URI
DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions/groups/group-id/capability-name/capability-mode
DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions/users/user-id/capability-name/capability-mode
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the virtual connection. |
| virtualconnection‑id | The ID of the virtual connection to remove the permission for. |
| group-id | The LUID of the group to remove the permission for. A request does not need to include both a user and a group grantee. |
| user-id | The LUID of the user to remove the permission for. A request does not need to include both a user and a group grantee. |
| capability-name | The capability to remove the permission for. Valid capabilities for a virtual connection areRead,Connect,Overwrite,ChangeHierarchy,Delete, andChangePermissions. For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny to remove the deny permission. |
Request Body
None
Permissions
You must be an administrator or have theDelete permission for the virtual connection (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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:deleteResponse Code
204
Response Body
None
Version
Version 3.23 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400009 | Invalid capability | The specified capability is invalid for a virtual connection. Valid capabilities for a virtual connection areRead,Connect,Overwrite,ChangeHierarchy,Delete, andChangePermissions. |
| 403 | 403004 | Permissions setting forbidden | The user tried to change permissions for a virtual connection but doesn't have the permission to change them. |
| 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 | 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). |
| 404 | 404014 | 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 thanAllow orDeny for any mode value. |
| 405 | 405000 | Invalid request method | Request type was notDELETE. |
| 400 | 409004 | Invalid LUID | The virtual connection LUID in the URI was not found. |
For more information, seeHandling Errors.
Example
curl --location --request DELETE 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/read/allow' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
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 as3.27. For more information, seeREST 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 haveRead (view) andDelete permissions (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:workbooks:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 areAddComment,ChangeHierarchy,ChangePermissions,Delete,ExportData,ExportImage,ExportXml,Filter,Read (view),ShareView,ViewComments,ViewUnderlyingData,WebAuthoring,Write,RunExplainData, andCreateRefreshMetrics. For more information, seePermissions. |
| capability-mode | Allow to remove the allow permission, orDeny 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 haveChangePermissions 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:deleteResponse Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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 areAddComment,ChangeHierarchy,ChangePermissions,Delete,ExportData,ExportImage,ExportXml,Filter,Read,Share_view,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. |
| 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 thanAllow orDeny 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 notDELETE. |
For more information, seeHandling 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 withTableau 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) and later.Version Overview
Permissions: Can only be called by users with site or 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/site/extensions/dashboard/safeListItems/{safe_list_item_luid}
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 as3.27. For more information, seeREST 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) Theextract-value is a Boolean value (False orTrue). 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 haveExportXml 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).
tableau:datasources:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 Encrypted Keychain
Gets an encrypted version of the embedded credentials from the data source. These credentials can only be migrated to the linked destination Tableau Cloud or Tableau Server.
Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, seeMigrate Workbooks and Data Sources with Embedded Credentials.
Version:Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:No additional license required.
Permissions:This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:embedded_credentials:download
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/datasources/datasource-luid/retrieveKeychain
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| datasource-luid | The LUID of the data source to download the encrypted keychain from. |
Request Body
<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace> <destinationSiteLuid>d56023b5-8f8b-4241-aa74-8974ced85827</destinationSiteLuid> <destinationServerUrl>http://example.com</destinationServerUrl></tsRequest>
{ "destinationSiteUrlNamespace": "site1", "destinationSiteLuid": "d56023b5-8f8b-4241-aa74-8974ced85827", "destinationServerUrl": "http://localhost"}
Request Attributes
destinationSiteUrlNamespace | (Required) The site name on Tableau Cloud. |
destinationSiteLuid | (Required) The site ID on Tableau Cloud. |
destinationServerUrl | (Required) The destination Tableau Cloud URL. |
cURL Request Example
curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/retrieveKeychain" --header "Content-Type: application/xml" --header "X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86" --data "<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace><destinationSiteLuid>9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</destinationSiteLuid><destinationServerUrl>http://example.com</destinationServerUrl></tsRequest>"
Response Code
200
Response Body
<tsResponse> <associatedUserLuidList/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyKgNw5FnJud0etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/py5okFzVW4wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oCS5wRNtJ6lGz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1L2q9VyhVr8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKhsBZyFrVY7Wtf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ13hV0jXW7nXUhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain> </encryptedKeychainList></tsResponse>{ "associatedUserLuidList": [], "encryptedKeychainList": { "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyKgNw5FnJud0etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/py5okFzVW4wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oCS5wRNtJ6lGz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1L2q9VyhVr8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKhsBZyFrVY7Wtf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ13hV0jXW7nXUhfIW7o5iUtbYWrpCvVwubZLf4U5Y=" }}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
| 403 | 403054 | Unauthorized Access | A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
| 405 | 405000 | Invalid request method | Request type was notPOST. |
For more information, seeHandling Errors.
Download Data Source Revision
Downloads a specific version of a data source prior to the current one in.tdsx format. To down load the current version of a data source use theDownload Data Source method.
Note: This method is available only if version history is enabled for the specified site. For more information, seeMaintain 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 as3.27. For more information, seeREST 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, callGet 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 ofExplorerCanPublish.
- Read (view),Write (save), andDownload (save as) permissions for the specified data source.
- Save (write) permissions for the project that contains the data source.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 notGET. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flows:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.3 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 User Credentials
Gets credentials for a user who is being migrated to another Tableau Cloud or Tableau Server site.
Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, seeMigrate Workbooks and Data Sources with Embedded Credentials.
Version:Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:No additional license required.
Permissions:This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:oauth_credentials:download
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/users/user-luid/retrieveSavedCreds
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| user-luid | The LUID of the user whole credentials you want to download. |
Request Body
<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace> <destinationSiteLuid>d56023b5-8f8b-4241-aa74-8974ced85827</destinationSiteLuid> <destinationServerUrl>http://example.com</destinationServerUrl></tsRequest>
{ "destinationSiteUrlNamespace": "site1", "destinationSiteLuid": "d56023b5-8f8b-4241-aa74-8974ced85827", "destinationServerUrl": "http://localhost"}
Request Attributes
destinationSiteUrlNamespace | (Required) The site name on Tableau Cloud. |
destinationSiteLuid | (Required) The site ID on Tableau Cloud. |
destinationServerUrl | (Required) The destination Tableau Cloud URL. |
cURL Request Example
curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/retrieveKeychain" --header "Content-Type: application/xml" --header "X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86" --data "<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace> <destinationSiteLuid>9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</destinationSiteLuid> <destinationServerUrl>http://example.com</destinationServerUrl> </tsRequest>"
Response Code
200
Response Body
<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api https://help.tableau.com/samples/en-us/rest_api/ts-api_3_24.xsd"> <associatedUserLuidList/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y= <encryptedKeychain></encryptedKeychainList></tsResponse>
{ "associatedUserLuidList": [], "encryptedKeychainList": { "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=" }}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
| 403 | 403054 | Unauthorized Access | A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
| 405 | 405000 | Invalid request method | Request type was notPOST. |
For more information, seeHandling Errors.
Download View Crosstab Excel
Downloads an Excel (.xlsx) file containing crosstab data from a view that the user has permission to access in a workbook.If a crosstab is exported from a dashboard, data from only the first view in the dashboard will appear in the.xlsx file. Downloads of data from story dashboards are not supported at this time.
If you make multiple requests for an.xlsx, subsequent calls return a cached version of the file. This means that the returned.xlsx might not include the latest changes to the workbook. To decrease the amount of time that a workbook is cached,use themaxAge 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,seeFiltering 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 as3.27. For more information, seeREST 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, seeView 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 needRead andExportData permissions for the workbook containing theview and for the view itself.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:views:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 withoutRead and/orExportData 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 notGET. |
For more information, seeHandling 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 Virtual Connection
Downloads a JSON-representation of a virtual connection.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:You must have theOverwrite permission for the virtual connection and your site role must be at leastCreator. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:virtual_connections:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
GET /api/api-version/sites/site-luid/virtualconnections/virtualconnection-luid
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| virtualconnection-luid | The LUID for the virtual connection. |
Request Body
None
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd" -X GET -H "Content-Type: application/xml" -H "X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3"
Response Code
200
Response Body
<tsResponse> <virtualConnection name="virtualconnection-name"> <project/> <owner/> <content>virtualconnection-as-json</content> </virtualConnection></tsResponse>{ "virtualConnection": { "project": { "id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" }, "owner": { "id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" }, "content": "virtualconnection-as-json", "name": "virtualconnection-name" }}The response body contains the project LUID, owner LUID, and acontent element (for XML output) orcontent property (for JSON output) containing the virtual connection schema rendered as JSON.
If the response is XML, thecontent element is unescaped JSON.
If the response is JSON, thecontent property is escaped JSON.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400200 | Generic error | An unknown error occurred. |
| 403 | 403174 | User not authorized. | Check to make sure the user has the required permissions. |
| 404 | 404049 | Virtual connection not found | Check the virtual connection LUID. |
For more information, seeHandling Errors.
Download Virtual Connection Revision
Downloads a JSON-representation of an earlier revision of a virtual connection.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:You must have theOverwrite permission for the virtual connection and your site role must be at leastCreator. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:virtual_connections:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
GET /api/api-version/sites/site-luid/virtualconnections/virtualconnection-luid/revisions/revision-number
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| virtualconnection-luid | The LUID for the virtual connection. |
| revision-number | The revision number (revisionNumber) of the virtual connection, as returned by theGet Virtual Connection Revisions method. This is an integer, not a LUID. |
Request Body
None
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/revisions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
Response Code
200
Response Body
<tsResponse> <virtualConnection name="virtualconnection-name"> <project/> <owner/> <content>virtualconnection-as-json</content> </virtualConnection></tsResponse>{ "virtualConnection": { "project": { "id": "project-luid" }, "owner": { "id": "owner-luid" }, "content": "virtualconnection-as-json", "name": "virtualconnection-name" }}The response body contains the project LUID, owner LUID, and acontent element (for XML output) orcontent property (for JSON output) containing the virtual connection schema rendered as JSON.
If the response is XML, thecontent element is unescaped JSON.
If the response is JSON, thecontent property is escaped JSON.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400200 | Generic error | An unknown error occurred. Check to make sure the revision number is a revision and not the active virtual connection. |
| 403 | 403174 | User not authorized. | Check to make sure the user has the required permissions. |
| 404 | 404049 | Virtual connection not found | Check the virtual connection LUID. Check that the revision number exists. |
For more information, seeHandling Errors.
Download Workbook
Downloads a workbook in.twb or.twbx format.
Security note: Content in .twb or .twbx files downloaded using this method is stored in plain text.All data, including filter values that may give semantic clues to the data, will be readable by anyone who opens the files.
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 as3.27. For more information, seeREST 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) Theextract-value is a Boolean value (False orTrue). 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 haveExportXml 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).
tableau:workbooks:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
One of the following, depending on the format of the workbook:
- The workbook's content in
.twbformat (Content-Type: application/xml) - The workbook's content in
.twbxformat (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, seeREST 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 haveExportXml 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 Encrypted Keychain
Gets an encrypted version of the embedded credentials from the workbook. These credentials can only be migrated to the linked destination Tableau Cloud or Tableau Server.
Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, seeMigrate Workbooks and Data Sources with Embedded Credentials.
Version:Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:No additional license required.
Permissions:This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:embedded_credentials:download
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/workbooks/workbook-luid/retrieveKeychain
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| workbook-luid | The LUID of the workbook to download the encrypted keychain from. |
Request Body
<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace> <destinationSiteLuid>d56023b5-8f8b-4241-aa74-8974ced85827</destinationSiteLuid> <destinationServerUrl>http://localhost</destinationServerUrl></tsRequest>
{ "destinationSiteUrlNamespace": "site1", "destinationSiteLuid": "d56023b5-8f8b-4241-aa74-8974ced85827", "destinationServerUrl": "http://localhost"}
Request Attributes
destinationSiteUrlNamespace | (Required) The site name on Tableau Cloud. |
destinationSiteLuid | (Required) The site ID on Tableau Cloud. |
destinationServerUrl | (Required) The destination Tableau Cloud URL. |
cURL Request Example
curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/retrieveKeychain" --header "Content-Type: application/xml" --header "X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86" --data "<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace> <destinationSiteLuid>9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</destinationSiteLuid> <destinationServerUrl>http://example.com</destinationServerUrl> </tsRequest>"
Response Code
200
Response Body
<tsResponse> <associatedUserLuidList/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyKgNw5FnJud0etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/py5okFzVW4wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oCS5wRNtJ6lGz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1L2q9VyhVr8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKhsBZyFrVY7Wtf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ13hV0jXW7nXUhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain> </encryptedKeychainList></tsResponse>{ "associatedUserLuidList": [], "encryptedKeychainList": { "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyKgNw5FnJud0etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/py5okFzVW4wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oCS5wRNtJ6lGz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1L2q9VyhVr8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKhsBZyFrVY7Wtf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ13hV0jXW7nXUhfIW7o5iUtbYWrpCvVwubZLf4U5Y=" }}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).IfShow 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 themaxAge parameter.
Version: Available in API 3.4 and later.
License: No additional license required.
Permissions: To download a.pdf of a workbook, Tableau Server users who are not server administrators or site administrators needRead andExportImage permissions for the workbook.The user needsRead andExportImage permissions for a view in a workbook in orderfor that view to appear in the.pdf.
Access Scope:tableau:workbooks:download
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?type=page-type&orientation=orientation
GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?maxAge=max-age-minutes
Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later:
GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?vf_fieldname>=filter-value
Available in API 3.26 (Tableau Cloud June 2025) and later, but not available in Tableau Server:
GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?vizHeight=viz-height&vizWidth=viz-width
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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. |
| orientation | (Optional) The orientation of the pages in the .pdf file produced. The value can bePortraitorLandscape. If this parameter is not present the page orientation will default toPortrait. |
| page-type | (Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be: If this parameter is not present the page type will default to |
| fieldname=filter-value | Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later: (Optional) An expression that applies a granular filter to the request. Returns will be based on the value (filtervalue) of the dimension or measure (fieldname) of your view data you specify. For more information, seeView filter queries. |
| viz-height | (Optional) The height of the rendered pdf image in pixels that, along with the value ofvizWidth, determines its resolution and aspect ratio. |
| viz-width | (Optional) The width of the rendered pdf image in pixels that, along with the value ofvizHeight, determines its resolution and aspect ratio. |
Request Body
None
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 haveContent-Type:application/pdf.
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 haveRead and/orExportImage permissions for the workbookor user does not haveRead 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 notGET. |
For more information, seeHandling Errors.
cURL Request Example
curl "http://MY-SERVER/api/3.27/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, is 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).IfShow 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 themaxAge 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 as3.27. For more information, seeREST 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 needRead andExportImage permissions for the workbook.The user needsRead andExportImage permissions for a view in a workbook in orderfor that view to appear in the.pptx.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:workbooks:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 haveRead and/orExportImage permissions for the workbookor user does not haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 as3.27. For more information, seeREST 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, callGet Workbook Revisions. Note that the current revision of a workbook cannot be accessed by this call; useDownload Workbook instead. |
| extract-value | (Optional) Theextract-value is a Boolean value (False orTrue). 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 ofExplorerCanPublish.
- Read (view),Write (save), andDownload (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).
tableau:workbooks:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
One of the following, depending on the format of the workbook:
- The workbook's content in
.twbformat (Content-Type: application/xml) - The workbook's content in
.twbxformat (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, seeREST 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 notGET. |
For more information, seeHandling 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
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, seeExtract 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site. |
Request Body
None
Permissions
Tableau Server administrators can call this method.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:extract_encryption:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.5 and later. For more information, seeREST 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 notPOST. |
For more information, seeHandling Errors.
Generate basic insight bundle
Generates a basic insight bundle.
Version: Available in API 3.24 (Tableau Cloud December 2024) and later. Not available for Tableau Server.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/insights/basic
Generate breakdown insight bundle
Generates a breakdown insight bundle. This provides the BAN and breakdown groups of insights.
Version: Available in API 3.26 (Tableau Cloud September 2025) and later. Not available for Tableau Server.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/insights/breakdown
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.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/insights/ban
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.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. For theusage-based licensing model, each call to this method counts as an analytical impression.
Access Scope: `tableau:insights:read`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/insights/detail
Generate exploration insight bundle
Generates an exploration insight bundle. This provides the BAN, anchor, and followup groups of insights.
Version: Available in API 3.26 (Tableau Cloud September 2025) and later. Not available for Tableau Server.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/insights/exploration
Generate insight brief
Generates an insight brief based on a user utterance by gathering insights for the specified metrics.
Version: Available in API 3.26 (Tableau Cloud September 2025) and later. Not available for Tableau Server.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_brief:create`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/insights/brief
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.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/insights/springboard
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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:webhooks:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <webhook 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 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 withTableau 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) and later.Version Overview
Permissions: Can only be called by users with site or 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/site/extensions/dashboard/safeListItems/{safe_list_item_luid}
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) and later.Version Overview
Permissions: Can only be called by users with site or 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/site/extensions/analytics/connections/{connection_luid}
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, seeHow 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}
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 they administer. Other users can get statistics for any content they own or have at least Read permissions for.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
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 withTableau 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.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}
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: Theconnected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:connected_apps_direct_trust:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeCreate Connected App Secret. To get the secret value, seeQuery 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. Iffalseis 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, seeREST 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: Theconnected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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, seeREST 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) and later.Version Overview
Permissions: Search results will be limited to those objects that the user has permissions to access.Permissions Overview
License: No additional license required.
Access Scope: `tableau:content:read`.Tableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/search
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 2023.1) and later.Version Overview
Permissions: Suggestions will be limited to those objects that the user has permissions to access.Permissions Overview
License: No additional license required.
Access Scope: Not available.Tableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/suggestions
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) and later.Version Overview
Permissions: This method can be called by users that have permissions to the specified workbook.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
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 |
Request Body
None
Permissions
This method can be called by all authenticated users.
Response Code
200
Response Body
<tsResponse"> <session><site 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="" lastLogin="2020-04-29T04:59:08Z" name="workgroupuser" siteRole="ServerAdministrator"/> </session></tsResponse>The response for users without administrator permissions contains only the siteuser,id,name, andcontent-url attributes.
Version
Version 3.1 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 405 | 405000 | Invalid request method | Request type was notGET. |
For more information, seeHandling Errors.
Example Response
<tsResponse"> <session> <site 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="" lastLogin="2020-04-29T04:59:08Z" name="workgroupuser" siteRole="ServerAdministrator"/> </session></tsResponse>Get Custom Domain Name
Gets the custom domain for a Tableau site, if one is provisioned. For more information about how, see
Version: Available in API 3.26 (Tableau Cloud June 2025) and later. Not available for Tableau Server.Versioning OverviewVersion Overview
Permissions: Can be called by any user that is a member of the site associated with the custom domain.Permissions OverviewPermissions Overview
License: No additional license required.
Access Scope: Not available.
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/customdomains/site/{site_luid}
Get custom domain settings
Gets the custom domain settings for a Tableau site.
Version: Available in API 3.26 (Tableau Cloud June 2025) and later. Not available for Tableau Server.Versioning OverviewVersion Overview
Permissions: Only users with administrator permissions can view a site's custom domain settings.Permissions OverviewPermissions Overview
License: No additional license required.
Access Scope: Not available.
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/customdomains/settings/site/{site_luid}
Get Custom View
Gets the details of a specified custom view.
Version:Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1).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 viewthat they haveRead permissions for. Permissions Overview
JWT Access Scope: tableau:content:read
Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
- For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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 -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 name="New name 2" createdAt="2016-02-03T23:35:09Z" updatedAt="2022-09-28T23:56:01Z" lastAccessedAt="2022-09-28T23:57:12Z" shared="false"> <view name="circle"/> <workbook name="marks and viz types 2"/> <owner 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","lastAccessedAt": "2022-09-28T23:57:12Z","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 orRead 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, seeHandling Errors.
Get Custom View Data
Returns a specified custom view rendered as data in comma separated value (CSV) format.
Version: Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later.
License: No additional license required.
Permissions: Tableau Server users who are not server administrators or site administrators can query workbook views only if they haveRead (view) andExport data permissions for the underlying view (either explicitly or implicitly).
Access Scope:tableau:views:download
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 custom 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 custom view. To decrease the amount of time that data of a custom view is cached,use themaxAge parameter. Default age of data is 60 minutes.
For Tableau Cloud, concurrent requests to endpoints that start long-running jobs, including this one, are limited to20 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,seeFiltering and Sorting in the REST API.
URI
GET /api/api-version/sites/site-id/customviews/custom-view_luid/data
GET /api/api-version/sites/site-id/customviews/custom-view_luid/data?maxAge=max-age-minutes
GET /api/api-version/sites/site-id/customviews/custom-view_luid/data?vf_fieldname>=filter-value
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the view. |
| custom-view-luid | 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. |
| fieldname=filter-value | (Optional) An expression that applies a granular filter to the request. Returns will be based on the value (filtervalue) of the dimension or measure (fieldname) of your view data you specify. For more information, seeView filter queries. |
Request Body
None
cURL Request
curl "http://MY-SERVER/api/3.27/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/customviews/2474164d-8d37-4a4c-abc7-c2070fd25fd5/data?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
The response body contains view data in CSV format no more than 60 minutes old.
Month of Date,Year of Date,Above Median?,Avg. MedianJanuary,1893,below median,-1.0January,1864,below median,-0.9January,1861,below median,-0.9December,1862,below median,-0.9March,1917,below median,-0.8December,1892,below median,-0.8February,1862,below median,-0.8February,1911,below median,-0.8February,1917,below median,-0.8May,1861,below median,-0.8November,1862,below median,-0.8March,1898,below median,-0.8December,1860,below median,-0.8January,1862,below median,-0.7March,1850,below median,-0.7February,1893,below median,-0.7December,1870,below median,-0.7Errors
| 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 get custok views, but the caller doesn't haveRead orExpot imagepermission. |
| 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 notGET. |
| 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, seeHandling 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 / Server 2023.1).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 viewthat they havePublish permissions for. Permissions Overview
JWT Access Scope:tableau:views:download
- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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 tohigh 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, seeView filter queries. |
Request Body
None.
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 orRead 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, seeHandling Errors.
Get Custom View PDF
Returns a specified custom view rendered as a .pdf file.
Version: Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later.
License: No additional license required.
Permissions: Tableau Serverand site administrators can get custom views as PDFs. Other users can do this only if they haveRead (view) andExport image permissions for the views (either explicitly or implicitly).
Access Scope:tableau:views:download
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 custom view. To decrease the amount of time that an PDF is cached,use themaxAge parameter.
This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views,seeFiltering and Sorting in the REST API.
URI
GET /api/api-version/sites/site-luid/customviews/custom-view-luid/pdf
GET /api/api-version/sites/site-luid/customviews/custom-view-luid/pdf?vizHeight=viz-height&vizWidth=viz-width
GET /api/api-version/sites/site-luid/customviews/custom-view-luid/pdf?maxAge=max-age-minutes
GET /api/api-version/sites/site-luid/customviews/custom-view-luid/pdf?type=page-type&orientation=orientation
GET /api/api-version/sites/site-luidcustomviews/custom-view-luid/pdf?vf_fieldname=filter-value
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The ID of the site that contains the view. |
| custom-view-luid | The ID of the view to render as a .pdf file. |
| viz-height | (Optional) The height of the rendered pdf image in pixels that, along with the value ofvizWidth, determines itsresolution and aspect ratio. |
| viz-width | (Optional) The width of the rendered pdf image in pixels that, along with the value ofvizHeight, determines itsresolution 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. |
| orientation | (Optional) The orientation of the pages in the .pdf file produced. The value can bePortraitorLandscape. If this parameter is not present the page orientation will default toPortrait. |
| page-type | (Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be: If this parameter is not present the page type will default to |
| fieldname=filter-value | (Optional) An expression that applies a granular filter to the request. Returns will be based on the value (filtervalue) of the dimension or measure (fieldname) of your view data you specify. For more information, seeView filter queries. |
Request Body
None
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 haveContent-Type:application/pdf.
cURL Example
curl "http://MY-SERVER/api/3.27/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84dcustomviews/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.
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 haveRead 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 notGET. |
For more information, seeHandling 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 ofView 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 willalso not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removingany dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releasesresulting 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:data_acceleration_reports:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 ofView 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 willalso not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removingany dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releasesresulting in error codes being returned.
For more information, seeREST 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 notGET |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dataAccelerationReport" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-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 ofView 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 willalso not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removingany dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releasesresulting 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:data_acceleration_tasks:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 ofView 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 willalso not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removingany dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releasesresulting in error codes being returned.
For more information, seeREST 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 notGET |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/dataAcceleration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-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, seeMaintain 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 theDownload 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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 ofExplorerCanPublish.
- Read (view),Write (save), andDownload (save as) permissions for the specified data source.
- Save (write) permissions for the project that contains the data source.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" /> <revisions> <revision revisionNumber="1" publishedAt="date" deleted="false"> <publisherapi-placeholder">publisher-id" name="publisher-name"/> </revision> <revision revisionNumber="2" publishedAt="date" deleted="false"> </revision> <revision revisionNumber="3" publishedAt="date" deleted="false" current="true" sizeInBytes="size> <publisherapi-placeholder">publisher-id" name="publisher-name"/> </revision> </revisions></tsResponse>If the revision element includes the attributedeleted="true", the data source has been deleted and cannot be downloaded using theDownload Data Source Revision method.
If a user has been deleted from the site, no<publisher> element is included in the<revision> element.
Version
Version 2.3 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 callingQuery 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Request Body
None
Response Code
200
Response Body
<tsResponse> <dataAlert subject="alert-subject" creatorId="creator-id" createdAt="created-date" updatedAt="updated-date" frequency="alert-frequency" public="is-public-flag"> <owner name="username"/> <view name="view-name"> <workbook name="workbook-name"/> <project name="project-name"/> </view> <recipients> <recipient/> </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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse> <dataAlert 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 name="admin"/> <view name="Shipping"> <workbook name="Superstore"/> <project name="Default"/> </view> <recipients> <recipient/> </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:
- For Tableau Cloud, seeEmbedded asset appears in External Assets(Link opens in a new window).
- For Tableau Server, seeEmbedded asset appears in External Assets(Link opens in a new window).
URI
POST api/api-version/sites/site-id/databaseAndTables/lookup
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 (
|
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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"> <tableAnchors><tableAnchor name="Marketing" fullName="[Marketing]"/> </tableAnchors></databaseAnchor><databaseAnchor connectionName="sqlserver.myco"> <tableAnchors><tableAnchor name="Advertising" fullName="[dbo].[Advertising]"/> </tableAnchors></databaseAnchor> </databaseAnchors></tsResponse>Note: BothdatabaseAnchor andtableAnchor IDs returned from this request correspond todatabase andtable IDs that you can use to retrieve additional information about databases and tables endpoints using other REST endpoints, includingQuery Database andQuery Table.
Version
Version 3.13 and later. For more information, seeREST 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 theTableau 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the views. |
Request Body
None
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:embedding_site_settings:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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.27/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 notGET. |
For more information, seeHandling 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
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
Get Extract Refresh Task
Returns information about the specified extract refresh task.
This method shows you information about the scheduled task for the data source extract or a published workbook that connects to the data extract.
Note: This method doesn't work for scheduled tasks associated with virtual connection extracts.
URI
GET /api/api-version/sites/site-id/tasks/extractRefreshes/task-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
tableau:tasks:read (this scope is included in the scope:tableau:tasks)
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 Response
For Tableau Server an extract refresh task with a server schedule is returned.
<tsResponse>
<task>
<extractRefresh
priority="nn"
consecutiveFailedCount="n"
type="REFRESH_EXTRACT">
<schedule
name="schedule_name"
state="state"
priority="nn"
createdAt="DATE_TIME"
updatedAt="DATE_TIME"
type="Extract"
frequency="frequency"
nextRunAt="DATE_TIME" />
<datasource />
</extractRefresh>
</task>
<task>
<!-- ... additional tasks ... -->
</task>
</tsResponse>[
{
"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 Response
For Tableau Cloud an extract refresh task with its frequency is returned.
Response for a server schedule on Tableau Server:
<tsResponse>
<task>
<extractRefresh 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/>
</extractRefresh>
</task>
</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": "Thursday" }
]
}
}
},
"workbook": {
"id": "7e766949-7166-4b3d-90ba-784f7575743b"
}
}
}
}Version
Version 2.6 and later. For more information, seeREST 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, or the task is associated with a virtual connection instead of a workbook or published data source. |
| 405 | 40500 | Invalid requests method | Request type was notGET |
For more information, seeHandling 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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponseversion-and-namespace-settings> <favorites><favorite label="favorite-label"> <viewname="view-name"contentUrl="content-url"createdAt="created-at"updatedAt="updated-at"viewUrlName="view-url-name"> <workbook/> <project id"project-luid"/> <tags /> </view></favorite><!-- . . .more favorites. . . --> </favorites></tsResponse>The value ofview-url-name is the name of the view in its URL.For example, if a view namedView 1 shows the URLhttps://MY_SERVER/#/site/MY_SITE/views/VIEW_1in your browser address bar, then theview-url-name would beVIEW_1.Modifying thename (display name) of a view will not impact theview-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, seeREST 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, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/favorites/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <favorites> <favorite label="Global Economic Indicators"> <viewname="Overview"contentUrl="Superstore/sheets/Overview"createdAt="2015-11-09T21:39:59Z"updatedAt="2019-08-30T21:05:37Z"viewUrlName="Overview" > <workbook/> <owner/> <project/> <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 as3.27. For more information, seeREST 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flow_runs:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <flowRun flow status="status" startedAt="DATE_TIME" completedAt="DATE_TIME" progress="100" backgroundJobId="background_job_id"/> <flowParameterRuns> <parameterRuns parameter name="parameter_name" description="parameter_description" overrideValue="override_value"/> </flowParameterRuns> </flowRun></tsResponse>Thestatus attribute can be:Pending,InProgress,Success,Cancelled, orFailed.
Version
Version 3.10 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flow_tasks:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <task> <flowRun priority="nn" consecutiveFailedCount="n" type="RunFlowTask"> <schedule name="schedule_name" state="state" priority="nn" createdAt="DATE_TIME" updatedAt="DATE_TIME" type="flowRun" frequency="frequency" nextRunAt="DATE_TIME"/> <flow name="flow_name"/> <parameters><parameter 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, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 priority="50" consecutiveFailedCount="2" type="RunFlowTask"> <schedule 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 name="allUseCaseTFLX2"/> <parameters><parameter 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flow_tasks:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <tasks> <task> <flowRun priority="nn" consecutiveFailedCount="n" type="RunFlowTask"> <schedule name="schedule_name" state="state" priority="nn" createdAt="DATE_TIME" updatedAt="DATE_TIME" type="flowRun" frequency="frequency" nextRunAt="DATE_TIME" /> <flow/> <parameters> <parameter 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, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 405 | 405000 | Invalid request method | Request type was notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 priority="50" consecutiveFailedCount="2" type="RunFlowTask"> <schedule 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 name="allUseCaseTFLX2"/> <parameters><parameter type="string" name="Region" description="" value="North" isRequired="false"><domain xsi:type="flowParameterListDomainType" domainType="any"></domain></parameter> </parameters> </flowRun> </task> <task> <flowRun priority="50" consecutiveFailedCount="2" type="RunFlowTask"> <schedule 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 name="allUseCaseTFLX2"/> <flowParameterSpecs/> </flowRun> </task> <task> <flowRun priority="44" consecutiveFailedCount="2" type="RunFlowTask"> <schedule 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 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 as3.27. For more information, seeREST 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 theuserId of the user who started the flow run,flowId,progress,startedAt, andcompletedAt. You can include multiple filter expressions. For more information, seeFiltering and Sorting. |
Request Body
None
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flow_runs:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <flowRuns> <flowRuns flow 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>Thestatus attribute can be:Pending,InProgress,Success,Cancelled, orFailed.
Version
Version 3.10 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Get Group Set
Returns information about the specified group set including ID, name, and member groups.
Version:Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/8cf3b6c1-839f-4eae-b41f-2144165193f2" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<tsResponse version-and-namespace-settings>
<groupSet name="All Users" groupCount="2">
<group
name="All Users" >
</group>
<group
name="Researchers" >
</group>
</groupSet>
</tsResponse>{
"groupSet": {
"id": "8cf3b6c1-839f-4eae-b41f-2144165193f2",
"name": "All Users",
"groupCount": "2",
"group": [
{
"id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d",
"name": "All Users"
},
{
"id": "4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234",
"name": "Researchers"
}
]
}
}Version
Version 3.22 and later. For more information, seeREST 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’tGET. |
| 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, seeHandling 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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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).
tableau:users:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" /> <groups> <groupapi-placeholder">group-id" name="group-name" > <domain name="group-domain-name"/></group> <!-- . . . additional groups ... --> </groups></tsResponse>Version
Version 3.7 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/groups" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="2"/> <groups> <group name="All Users" > <domain name="mydomain"/></group><group 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}
Get Label
Gets a data label by its LUID.
For more information on data label objects and properties, see theData 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 aData 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 as3.27. For more information, seeREST 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 haveread permissions on the associated asset.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).
tableau:labels:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <label 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/> <owner/> </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 theData 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 aData 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 as3.27. For more information, seeREST 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. SeeData Labels in the REST API for information on label values and categories. |
Request Body
<tsRequest> <contentList> <content contentType="asset-type" api-placeholder">asset-luid" /> <!-- ... additional content elements ... --> </contentList></tsRequest>Attribute Values
| asset-type | The type of asset. Valid asset types are:
|
| asset-luid | The asset LUID. |
Permissions
To view a data label, you must haveread permissions on the associated asset.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).
tableau:labels:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <labelList> <label 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/> <owner/> </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 (thecontentList element contains more than onecontent 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 | ThecontentType andcontentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrectcontentType, an incorrectcontentID, 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 theData Labels in the REST API(Link opens in a new window) topic.
AData 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_values:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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/> </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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:linked_tasks:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <linkedTasks id= "linkedTasks-id" numSteps="number-of-steps"> <schedule name="schedule-name" state="Active-or-Suspended" priority="priority" createdAt="datetime-created" updatedAt="datetime-updated" type="schedule-type" frequency="frequency" nextRunAt="datetime-nextrun"/> <linkedTaskSteps> <linkedTaskStepsstep-number" stopDownstreamTasksOnFailure="true-or-false"/> ...additional linked tasks steps... <task> <flowRun 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, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 numSteps="2"> <schedule 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 stepNumber="1" stopDownstreamTasksOnFailure="true"> <task> <flowRun priority="50" consecutiveFailedCount="0" type="RunFlowTask"> <flow 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:linked_tasks:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <linkedTasks> <linkedTasks id= "linkedTasks-id" numSteps="number-of-steps"> <schedule name="schedule-name" state="Active-or-Suspended" priority="priority" createdAt="datetime-created" updatedAt="datetime-updated" type="schedule-type" frequency="frequency" nextRunAt="datetime-nextrun"/> <linkedTaskSteps> <linkedTaskStepsstep-number" stopDownstreamTasksOnFailure="true-or-false"/> ...additional linked tasks steps... <task> <flowRun 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, seeREST 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 notGET. |
For more information, seeHandling Errors.
cURL Example
curl "http://MY-SERVER/api/3.27/sites/9a6b7c6d-5e4f-4a2b-1c0d-9e8f7s6b5c4d/tasks/linked" -X GET -H "X-Tableau-Auth:12ab34cd56ef98ab90ce12ef34ab52cd"
Example response:
<tsResponse version-and-namespace-settings> <linkedTasks> <linkedTasks numSteps="2"> <schedule 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 stepNumber="1" stopDownstreamTasksOnFailure="true"> <task> <flowRun priority="50" consecutiveFailedCount="0" type="RunFlowTask"> <flow name="r-3"/> </flowRun> </task> </linkedTaskSteps> <linkedTaskSteps stepNumber="2" stopDownstreamTasksOnFailure="true"> <task> <flowRun priority="50" consecutiveFailedCount="0" type="RunFlowTask"> <flow name="flights"/> </flowRun> </task> </linkedTaskSteps> </linkedTasks> <linkedTasks numSteps="2"> <schedule 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 stepNumber="1" stopDownstreamTasksOnFailure="true"> <task> <flowRun priority="50" consecutiveFailedCount="0" type="RunFlowTask"> <flow name="Test3"/> </flowRun> </task> </linkedTaskSteps> <linkedTaskSteps stepNumber="2" stopDownstreamTasksOnFailure="true"> <task> <flowRun priority="50" consecutiveFailedCount="2" type="RunFlowTask"> <flow name="Superstore Flow"/> </flowRun> </task> </linkedTaskSteps> </linkedTaskSteps> </linkedTasks> </linkedTasks></tsResponse>Get Metadata Suggestion
Gets a suggestion from generative AI about asset metadata.
As of June 2024, the type of suggestion is limited to the description for a workbook, data source, or table. Generative AI suggests a description based on the chosen asset's metadata, such as asset name, field names, and/or column names. This method can't apply the suggested description to the asset.
More than one request results in alternative suggestions.
Note:
- This REST API method uses generative AI. Generative AI can produce inaccurate or harmful responses. Check the output before using. For more information, seeAI in Tableau and Trust.
- Salesforce's generative AI is built on the Einstein Trust Layer. Your data stays safe and secure through data and privacy controls that are seamlessly integrated into the user experience. For more information, seeEinstein Trust Layer(Link opens in a new window).
Version:Available in API 3.23 (Tableau Cloud June 2024) and later. Not available for Tableau Server.Version Overview(Link opens in a new window)
License:RequiresTableau+(Link opens in a new window).
Permissions:Overwrite permission on the asset you're requesting suggestions for. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/metadataSuggestions?suggestionType=suggestion-type
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| suggestion-type | The type of metadata suggestion. The only valid type of suggestion isdescription. Note: The URI parametersuggestionType is case-sensitive. |
Request Body
(Use the icon in the top right corner to copy the text.)
<tsRequest> <contentList> <content contentType="asset-type"api-placeholder">asset-luid" /> </contentList></tsRequest>
(Use the icon in the top right corner to copy the text.)
{ "contentList": { "content": [ {"contentType":"asset-type","id":"asset-luid"} ] }}
Request Attributes
| asset-type | Valid types are:
|
| asset-luid | The LUID of the asset. |
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl --location 'https://MY-SERVER//api/3.23/sites/f480b345-8ab5-4e0b-98e6-9553de5748f9/metadataSuggestions?suggestionType=description' --header 'X-Tableau-Auth: 5Jgp0n2lSUaYbTB7NA6Wrw|mtqLBgKQEoup31yMme7la61kywW6LaTm|f480b345-8ab5-4e0b-98e6-9553de5748f9' --header 'Content-Type: application/xml' --data data.xml'
Contents of data.xml.
(Use the icon in the top right corner to copy the text.)
<tsRequest> <contentList> <content contentType="datasource" /> </contentList></tsRequest>
Response Code
200
Response Body
Multiple requests result in alternative suggestions.
<tsResponse> <suggestionList> <suggestion suggestionId="suggestion-luid" contentType="asset-type" contentId="asset-luid" suggestionType="suggestion-type" text="suggested-description"/> </suggestionList></tsResponse>{ "suggestionList": { "suggestion": [ { "suggestionId": "suggestion-luid", "contentType": "asset-type", "contentId": "asset-luid", "suggestionType": "suggestion-type", "text": "suggested-description" } ] }}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400192 | Missing or incomplete payload | Make sure the request body is present and complete. |
| 400 | 400193 | Generic error | An unknown error occurred. |
| 403 | 403004 | Permission denied | Check permissions for the asset. Check the asset type and asset LUID. |
| 403 | 403157 | Feature disabled | This method is only available on Tableau Cloud with Tableau+. |
| 404 | 404055 | Asset not found | Can't find selected asset. Check the asset type and asset LUID. |
| 409 | 409004 | Invalid parameter | URI parameter may be incorrect. ThesuggestionType parameter is case sensitive, and must bedescription. |
For more information, seeHandling Errors.
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.Version Overview
Permissions: Any user can update a metric if they have both write and publish 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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/metrics/{metric_id}
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 methodswill 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 as3.27. For more information, seeREST 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).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <metricapi-placeholder">metric-id"name="metric-name"description="metric-description"webpageUrl="metric-content-url"createdAt="datetime-created"updatedAt="datetime-updated"suspended="suspended-flag"> <projectapi-placeholder">project-id" name="project-name"/> <ownerapi-placeholder">metric-owner-id"/> <tags> <tag label="tag"/> <!-- ... additional tags ... --> </tags> <underlyingViewapi-placeholder">view-id"/> </metric></tsResponse>Version
Version 3.9 and later. For more information, seeREST 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 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 name="my project name"/> <owner/> <tags/> <underlyingView/> </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 methodswill 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 as3.27. For more information, seeREST 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 withReadcapability 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).
tableau:metrics:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
your_timestamp_column_name,your_measure_column_nametimestamp_1,measure_1timestamp_2,measure_1Version
Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. For more information, seeREST 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 notGET. |
| 429 | 405000 | Too many requests | The concurrent request limit for the site was exceeded. Retry after a pause. |
For more information, seeHandling 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,Measure2021-12-31:11:59:57-0800,32021-12-31:11:59:58-0800,22021-12-31:11:59:59-0800,1Get 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.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/definitions/{definition_id}
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:tableau:mobile_security_site_settings:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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
<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.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>
{
"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.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 occurred. |
| 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, seeHandling 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:tableau:mobile_security_site_settings:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
cURL Request Example
curl "http://MY-SERVER/api/3.27/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
<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.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>
{
"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.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 occurred. |
| 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, seeHandling 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.
URI
GET /api/api-version/sites/site-luid/site-oidc-configuration?idpConfigurationId=idp-configuration-id
Note: The resource, GET /api/api-version/sites/site-luid/site-oidc-configuration?idpConfigurationId=idpConfigurationId, was added in version 3.24. The original resource, PUT /api/api-version/sites/site-luid/site-oidc-configuration, continues to be a supported resource if your site is configured with only one OIDC authentication configuration. If you don’t specify anidpConfigurationId value starting in API 3.24, the initial OIDC configuration on the site is removed. If there is no initial OIDC configuration on the site, then no OIDC configuration is removed.
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| idp-configuration-id | The ID of the configuration. To get theidpConfigurationId value, use theList Authentication Configurations for Site method. |
Request Body
None
cURL Request Example
curl "https://us-west-2a.online.tableau.com/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuration?idpConfigurationId=00000000-0000-0000-0000-0000000000" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<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="<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"
idpConfigurationName="Initial OIDC"
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"
idpConfigurationId="00000000-0000-0000-0000-000000000000" />
</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":"<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",
"idpConfigurationName":"Initial OIDC"
"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",
"idpConfigurationId":"00000000-0000-0000-0000-000000000000"
}
}Notes:
The response hides the client secret and replaces it with
<omit>.You can use the
testloginURLto validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.You can use the
idpConfigurationIdto assign the authentication method to a user using theAdd User to Site andUpdate User methods.
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, seeHandling 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 'true' if a new metric was created, or 'false' if it already existed.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server.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:Tableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/metrics:getOrCreate
Get Pulse 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.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/subscriptions/{id}
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 as3.27. For more information, seeREST 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 hasRead 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).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse ><recents> <recent><view api-placeholder">view-id" name="view-name" contentUrl="view-content-url" createdAt="created-at-time" updatedAt="updated-at-time" viewUrlName="view-url-name"><workbookworkbook-of-view" "/><ownerapi-placeholder">owner-id" /><projectapi-placeholder">project-id" /><tags/></view> </recent> <recent> <workbook api-placeholder">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" > <projectapi-placeholder">project-id"/> <ownerapi-placeholder">ownwer-id"name="project-name" /> <tags/></workbook> </recent> <!-- more recently viewed views and workbooks --></tsResponse>The value ofview-url-name is the name of the view in its URL.For example, if a view namedView 1 shows the URLhttps://MY_SERVER/#/site/MY_SITE/views/VIEW_1in your browser address bar, then the theview-url-name would beVIEW_1.Modifying thename (display name) of a view will not impact theview-url-name(path element of the view's URL).
Version
Version 3.5 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling 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 name="MySQL PostgresSQL" contentUrl="my_site1" createdAt="2019-01-28T20:33:35Z" updatedAt="2019-01-28T20:44:05Z"viewUrlName="MySQL_PostgresSQL"> <workbook/> <owner/> <project/> <tags/> </view> </recent> <recent> <workbook 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 name="project2"/> <owner 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:recommendations:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsRequest> <recommendations> <recommendation score="recommendation_score"> <view /> <similarUsersExplanation> <users> <user /> <user /> </users> </similarUsersExplanation> </recommendation> <recommendation score="recommendation_score"> <view /> <popularExplanation /> </recommendation> </recommendations></tsRequest>Version
Version 3.7 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 /> <similarUsersExplanation> <users> <user /> <user /> </users> </similarUsersExplanation> </recommendation> <recommendation score="94.038491833"> <view /> <popularExplanation /> </recommendation> </recommendations></tsRequest>Get SCIM Configuration
Gets the System for Cross-domain Identity Management Configuration (SCIM) configuration on the Tableau Cloud site.
Version: Available in API 3.26 (Tableau Cloud August 2025) and later.
License: No additional license required.
Permissions: Tableau Cloud site admins only.
Access Scope:tableau:scim_configurations:read
Scope added in API 3.27 (Tableau Cloud December 2025)
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),access scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected appsCloud(Link opens in a new window).
URI
GET /api/api-version/sites/site-luid/scimConfigurations/scim-configuration-id
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| scim-configuration-id | The UUID of the SCIM configuration. To get the SCIM configuration UUID, seeList SCIM Configurations. |
Request Body
None
cURL Request Example
GET request: curl --location 'https://prod-ca-a.online.tableau.com/api/3.27/sites/0f04ea64-0d72-424a-afd8-ee7d758dc9b8/scimConfigurations/065693d8-436a-4738-a8f1-375953a2a888'
Response Code
200
Response Body
<tsResponse> <scimConfiguration> <id>065693d8-436a-4738-a8f1-375953a2a888</id> <idpConfigurationId>95dcdf3b-30eb-42ae-b938-7ffca3e11fdc</idpConfigurationId> <isApiTokenActive>false</isApiTokenActive> <isOwner>false</isOwner> <name>SCIM Contractors</name> <createdAt>2025-03-27 11:07:49.129</createdAt> </scimConfiguration></tsResponse>
{ "scimConfiguration": { "id": "065693d8-436a-4738-a8f1-375953a2a888", "idpConfigurationId": "95dcdf3b-30eb-42ae-b938-7ffca3e11fdc", "isApiTokenActive": false, "isOwner": false, "name": "SCIM Contractors", "createdAt": "2025-03-27 11:07:49.129" }}
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header is invalid or has expired. |
| 404 | 404057 | Resource Not Found | The SCIM configuration UUID is not valid. |
For more information, seeHandling Errors.
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 aquery 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 as3.27. For more information, seeREST 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, seeJobs, 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:schedules:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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> <intervalschedule-frequency/></intervals> </frequencyDetails> </schedule></tsResponse>Version
Version 3.8 and later. For more information, seeREST 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, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/schedules/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings> <schedulename="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 site entitlements
Returns entitlements available for a site. If entitlements are True, then Pulse premium features are enabled for the site.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server.Version Overview
Permissions: Can be called by any user, but only details about sited the user has permissions to view.Permissions Overview
License: No additional license required.
Access Scope: `tableau:entitlements:read`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/entitlements
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 as3.27. For more information, seeREST 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 unified access token (UAT) or connected app. For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orTableau Cloud connected app scopes(Link opens in a new window) orTableau Server connected apps scopes(Link opens in a new window).Available in API 3.20 (Tableau Cloud June 2023) / Tableau Server 2023.3.
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.27/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.
<tsResponse>
<subscription
subject="subscription-subject"
attachImage="attach-image-flag" attachPdf="attach-pdf-flag"
suspended="suspended-flag"
pageOrientation="page-orientation"
pageSizeOption="page-size-option">
<content
type="content-type"
sendIfViewEmpty="send-view-if-empty-flag"/>
<schedule name="schedule-name" />
<user name="user-name" />
</subscription>
</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"
}
}
}Tableau Cloud Request
For Tableau Cloud, a subscription task with frequency is returned.
<tsResponse>
<subscription subject="Subscription - postman" message="Test out postman Subscriptions" attachImage="true" attachPdf="false" suspended="false">
<content 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 name="mysite.com"/>
</subscription>
</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" }
]
}
}
},
"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, seeREST 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 notGET. |
For more information, seeHandling Errors.
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 they administer. Other users can get statistics for any content they own or have at least Read permissions for.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}
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, seeManage 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 as3.27. For more information, seeREST 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:
You can include multiple filter expressions. For more information, seeFiltering 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:user_notifications:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 notGET. |
For more information, seeHandling 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 User Personal Space
Gets the details of the Personal Space for the currently authenticated user.
Personal Space must be enabled for the site in order to be returned by this method. For more information see,Create and Edit Private Content in Personal Space(Link opens in a new window)
Version: Available in API 3.13 and later.
License: No additional license required.
Permissions: Only the user that owns a Personal Space can get its details.
Access scope:tableau:projects:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
GET /api/api-version/sites/site-id/personalSpace
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the user. |
Request Body
none
cURL Example
curl "http://MY-SERVER/api/3.27/sites/7bfb590b-cfa7-4576-8bea-e9cc035/personalSpace -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<tsResponse> <personalSpace luid="b76c9984-c7a8-4ae4-826d-e08372ad7d61", ownerLuid="39e76bc4-737f-40c0-bca7-e635fe0e9fd9", readOnly="false" /></tsResponse>
{ "personalSpace": { "luid": "b76c9984-c7a8-4ae4-826d-e08372ad7d61", "ownerLuid": "39e76bc4-737f-40c0-bca7-e635fe0e9fd9", "readOnly": false }}
readOnly istrue only if Personal Space is disabled in site settings or the user's role for the site does not allow writing to a Personal Space.
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 notGET. |
For more information, seeHandling Errors.
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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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).
tableau:groups:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" /> <users> <userapi-placeholder">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>ThesiteRole value is returned as one of the followingvalues:Creator,Explorer,ExplorerCanPublish,ServerAdministrator,SiteAdministratorExplorer,SiteAdministratorCreator,Unlicensed,ReadOnly,orViewer.
TheexternalAuthUserId 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 oflastLogin is an empty string.
Version
Version 2.0 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="2"/> <users> <user name="Adam" siteRole="Explorer" /> <user 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 as3.27. For more information, seeREST 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 asname andlastLogin. You can include multiple filter expressions. For more information, seeFiltering 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, seeFiltering 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 caninclude multiple field expressions in a request. For more information, seeUsing Fields in the REST API. |
Note: Thefilter andsort parameters can be combined with each other and with paging parameters andfields 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).
tableau:users:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="total-available" /> <users> <user email="email" api-placeholder">user-id" fullName="full-name" name="user-name" siteRole="site-role" lastLogin="date-time" externalAuthUserId="authentication-id-from-external-provider" authSetting="auth-setting" idpConfigurationId="idp-configuration-id" language="language-code" locale="locale-code"> <domain name="domain-name" /> </user> <user email="email" api-placeholder">user-id" fullName="full-name" name="user-name" siteRole="site-role" lastLogin="date-time" externalAuthUserId="authentication-id-from-external-provider" authSetting="auth-setting" idpConfigurationId="idp-configuration-id" language="language-code" locale="locale-code"> <domain name="domain-name"/> </user> </users></tsResponse>Notes:
ThesiteRole value is returned as one of the followingvalues:Creator,Explorer,ExplorerCanPublish,ServerAdministrator,SiteAdministratorExplorer,SiteAdministratorCreator,Unlicensed,ReadOnly,orViewer.
TheexternalAuthUserId value is returned for Tableau Cloud only ; it represents ID stored in Tableau's single sign-on (SSO) system. For other server configurations, this field contains null, and the value oflastLogin is an empty string.
TheauthSetting attribute is only returned if you are usingTableau Server with site-specific SAML enabled, or Tableau Cloud with either SAML or OpenID Connect enabled.
Starting in API 3.24,idpConfigurationId indicates the authentication method assigned to the user in Tableau Cloud only.
Version
Version 1.0 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="161"/> <users> <user email="alex@example.com" fullName="Alex Smith" name="Alex" siteRole="Viewer" language="en-GB" locale="GB"> <domain name="tsi.lan" /> </user> <user email="jannaj@example.org" fullName="Janna Johnson" name="Janna" siteRole="Unlicensed" language="en-GB" locale="GB" idpConfigurationId="00000000-0000-0000-0000-0000000000"> <domain name="tsi.lan" /> </user> <user email="fred.zuzuki@example.net" fullName="Fred Suzuki" name="Fred" siteRole="ExplorerCanPublish" language="en-GB" locale="GB" idpConfigurationId="b2207590-024c-4a6e-ac4a-eca6eefabb2e"> <domain name="tsi.lan" /> </user> ... more users ... </users></tsResponse>curl "http://MY-SERVER/api/3.27/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.
Version: Available in API 3.0 and later.
License: No additional license required.
Permissions: For users who are not server administrators or site administrators,the method returns only the views that the user owns or hasRead permissions for (either explicitly or implicitly).
Access Scope:tableau:content:read
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
GET /api/api-version/sites/site-id/views/view-id?includeUsageStatistics=get-usage-information
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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. |
| (Optional)get-usage-information | true to return usage statistics. The default isfalse. |
Request Body
None
Response Code
200
Response Body
<tsResponse><viewapi-placeholder">view-id" name="view-name" contentUrl="path-to-view" createdAt="created-date" updatedAt="updated-date" viewUrlName="view-url-name"> <workbookapi-placeholder">workbook-id"/><ownerapi-placeholder">owner-id"/><projectapi-placeholder">project-id"/><tags/></view></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": [] }}
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 notGET. |
For more information, seeHandling Errors.
cURL Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6ds" -X GET -H "X-Tableau-Auth:RDEj_zqgQtGGcCiD3BXnSA|abXWv8thv5ocrXLNU7axCicQu3UdfgeX"Example response:
<tsResponse> <viewname="Sheet 1"contentUrl="workbook/sheets/Sheet1"createdAt="2019-05-07T17:59:42Z"updatedAt="2019-05-07T17:59:48Z"viewUrlName="view-name"> <workbook/> <owner/> <project/> <tags/> </view></tsResponse>Get View by Path
Gets the details of all views in a site with a specified name.
Version: Available in API 3.6 and later.
License: No additional license required.
Permissions: For users who are not server administrators or site administrators,the method returns only the views that the user owns or hasRead permissions for (either explicitly or implicitly).
Access Scope:tableau:content:read
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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. Forhttps://MY_SERVER/#/MY_SITE/views/workbook-name/Sheet1?:iid=1,the name would beSheet1. |
Request Body
None
Response Code
200
Response Body
<tsResponse><viewapi-placeholder">view-id" name="view-name" contentUrl="path-to-view" createdAt="created-date" updatedAt="updated-date" viewUrlName="view-name" ><workbookapi-placeholder">workbook-id" /><ownerapi-placeholder">owner-id" /><projectapi-placeholder">product-id" /><tags/></view><!-- potential additional views with the same name --></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": "owner-id" }, "project": { "id": "product-id" }, "tags": [] } }The value ofview-url-name is the name of the view in its URL.For example, if a view namedView 1 shows the URLhttps://MY_SERVER/#/site/MY_SITE/views/VIEW_1in your browser address bar, then theview-url-name would beVIEW_1.Modifying thename (display name) of a view will not impact theview-url-name(path element of the view's URL).
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 notGET. |
For more information, seeHandling Errors.
cURL Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views?filter=viewUrlName:eq:Sheet1" -X GET -H "X-Tableau-Auth:RDEj_zqgQtGGcCiD3BXnSA|abXWv8thv5ocrXLNU7axCicQu3UdfgeX"Example response:
<tsResponse> <viewname="Sheet 1"contentUrl="workbook/sheets/Sheet1"createdAt="2019-05-07T17:59:42Z"updatedAt="2019-05-07T17:59:48Z">viewUrlName="Sheet1" > <workbook/> <owner/> <project/> <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 explicitRead permissionsfor the workbook, or are a Tableau Administrator. Permissions Overview
JWT Access Scope:tableau:content:read
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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.
|
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
<tsResponse>
<workbook
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 name="Default"/>
<location type="Project" name="Default"/>
<owner name="test"/>
<tags/>
<views>
<view
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>{
"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"
}
}
}
}
}
}Thedatetime-created anddatetime-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 haveRead 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 notGET. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:workbook_downgrade_info:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 notGET. |
For more information, seeHandling 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 theDownload Workbook Revision method. For more information, seeMaintain 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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 ofExplorerCanPublish.
- Read (view),Write (save), andDownload (save as) permissions for the specified workbook.
- Save (write) permissions for the project that contains the workbook.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" /> <revisions> <revision createdAt="date" revisionNumber="1" isDeleted="false"> <userapi-placeholder">user-id" name="user-name"/> </revision> <revision createdAt="date" revisionNumber="2" isDeleted="false"> </revision> <revision createdAt="date" revisionNumber="3" isCurrent="true"> <userapi-placeholder">user-id" name="user-name"/> </revision> </revisions></tsResponse>If the revision element includes the attributeisDeleted="true", the workbook has been deleted and cannot be downloaded using theDownload 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, seeREST 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 notGET. |
For more information, seeHandling Errors.
Gets recommended metrics
Gets personalized groups of metrics to recommend to a user. Only metric that the user has privileges to view will be returned.
Version: Available in API 3.26 (Tableau Cloud September 2025) and later. Not available for Tableau Server.Version Overview
Permissions: Any user can get a batch of metrics as long as the user has read or connect access to the data source used in the definition that contains them.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:recommended
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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the group. |
Request Body
<tsRequest><recommendationDismissal><view /></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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:recommendation_dismissals:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 1.0 and later. For more information, seeREST 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dismissals -X PUT \-H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" \-d "@hide-view.xml"Content ofhide-view.xml
<tsRequest> <recommendationDismissal> <view /> </recommendationDismissal></tsRequest>Example response:
No response body. Response code is204.
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, seeHow 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) and later.Version Overview
Permissions: This method can only be called by server administrators or site 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
Import Users to Site from CSV
Creates a job to import the users listed in a specified .csv file to a site, and assign their roles and authorization settings.
The .csv file should comply with the rules described in one of the following topics:
For Tableau Cloud -CSV Import File Guidelines(Link opens in a new window)
For Tableau Server -CSV Import File Guidelines(Link opens in a new window)
URI
POST api/api-version/sites/site-id/users/import
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
Request Body
Because this method involves a file that is external to Tableau a multi-part request is required. For more information on multi-part requests, SeeImporting CSV files with Multipart Requests(Link opens in a new window).
--boundary-stringContent-Disposition: name="tableau_user_import"Content-Type: filepath_to_csv--boundary-stringContent-Disposition: name="request_payload"Content-Type: text/xml<tsRequest> <user name="user-name"authSetting="auth-setting"idpConfigurationId="idp-configuraion-id" /> <!-- more users --></tsRequest>--boundary-string--Arequest-payload without user name or authSetting is valid, but must be present in the request in the form:<tsRequest><user /></tsRequest>.
Attribute Values
| path-to-csv | The file path to the .csv list users to be imported. |
| user-name | (Optional) The name of the user. If the server uses local authentication, this can be any name. If you are usingActive Directory authentication, or if you are using Tableau Cloud, there are specific requirements for the name. Tableau Server Note: Active Directory specifies a user name using two attributes: Tableau Cloud |
| auth-setting | Tableau Server TheauthSetting attribute only applies when updating users on sites with site-specific SAML-enabled settings. Tableau Cloud The ability to create and enable multiple authentication methods simultaneously was introduced in API 3.25 (January 2025). As a result of this capability, consider the following:
Notes: You can assign the following values for theauthSetting attribute:
Assigning user auth settings with this method |
| idp-configuration-id | (Optional, Tableau Cloud only) The configuration to assign for user authentication. Added in API 3.25 (January 2025). To find theidpConfigurationId attribute value, use theList Authentication Configurations for Site method. Notes:
|
| isVerbose | Tableau Cloud only When set tofalse, this method only returns the top three errors in a batch of users. When set totrue, the method displays a full list of errors during CSV upload.Available in REST API 3.22 (Tableau Cloud February 2024) |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:users:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Version
REST API version 3.15 and later. For more information, seeREST API and Resource Versions.
Response Body
<tsResponse> <jobapi-placeholder">job-luid"mode="Asynchronous"type="UserImport"progress="progress-status-code"createdAt="created-date" finishCode="job-finish-status-code" /></tsResponse>Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request payload is missing or incomplete, or contains malformed XML. |
| 500 | 500000 | Internal Server Error | The request could not be completed. |
For more information, seeHandling Errors.
Example
curl -X POST \http://10.108.21.238//api/3.15/sites/8aa3291f-1b5a-4f52-a3be-6512661f574d/users/import \-H 'cache-control: no-cache' \-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \-H 'x-tableau-auth: AVjAKZb3SQimzoqyMmQXEg|9OSHQrwCXF83SIR2XCuDEK91AM7v3FZr' \-F tableau_user_import=@users.csv \-F 'request_payload=<tsRequest><user name="jdoe" idpConfigurationId="00000000-0000-0000-0000-0000000000"/></tsRequest>'Response
<tsResponse><job 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 callAppend to File Upload to send individual blocks of the file to the server. When the complete file has been sent to the server, you callPublish Data Source,Publish Flow, orPublish Workbook to commit the upload.
Initiate File Upload returns an upload session ID that you pass toAppend 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 toAppend to File Upload or the publishing APIs update this value.
For more information, seePublishing Resources.
URI
POST /api/api-version/sites/site-id/fileUploads
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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).
tableau:file_uploads:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Response Body
<tsResponse> <fileUpload uploadSessionId=new-upload-session-id fileSize=0 /></tsResponse>Version
Version 2.0 and later. For more information, seeREST 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 notPOST. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:external_authorization_servers:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 in Tableau Cloud June 2022 (API 3.16). Introduced in Tableau Server 2024.2 (API 3.23).
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 withTableau 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) 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/safeListItems
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) and later.Version Overview
Permissions: This method can be called by users that have permissions to the specified workbook.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
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
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 as3.27. For more information, seeREST 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 haveRead permission (either explicitly or implicitly), can list permissions for an ask data lens.
luResponse Code
200
Response Body
<tsResponse> <permissions><parent type="Project"api-placeholder">project-luid" /> <lensapi-placeholder">lens-luid" name ="lens-name/> <granteeCapabilities> <userapi-placeholder">user-luid" /> <capabilities> <capability name="capability" mtode="Allow-or-Deny" /> <capability name="capability" mode="Allow-or-Deny" /> <-- ... additional capabilities ... --> </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">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, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 403 | 403018 | Read forbidden | A non-administrator user attempted to query metrics for the site, but the caller doesn't haveRead permission. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404046 | Lens not found | A lens with the requested LUID could be found. |
| 405 | 405000 | Invalid request method | Request type was notGET. |
For more information, seeHandling 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, seeHow 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
List Authentication Configurations for Site
List all authentications configurations on the site.
For more information, seeAuthentication(Link opens in a new window) in the Tableau Cloud Help.
Version: Available in API 3.24 (Tableau Cloud November 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.
URI
GET /api/api-version/sites/site-luid/site-auth-configurations
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-auth-configurations" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<tsResponse>
<siteAuthConfigurations>
<siteAuthConfiguration>
authSetting="OIDC"
enabled="true"
idpConfigurationId="00000000-0000-0000-0000-000000000000"
idpConfigurationName="Initial Salesforce"
knownProviderAlias="Salesforce"
</siteAuthConfiguration>
<siteAuthConfiguration>
authSetting="SAML"
enabled="true"
idpConfigurationId="11111111-1111-1111-1111-111111111111"
idpConfigurationName="Initial SAML"
</siteAuthConfiguration>
</siteAuthConfigurations>
</tsResponse>{
"siteAuthConfigurations": [
{
"authSetting":"OIDC",
"enabled":"true",
"idPConfigurationId":"00000000-0000-0000-0000-000000000000",
"idPConfigurationName":"Initial Salesforce",
"knownProviderAlias":"Salesforce"
},
{
"authSetting":"SAML",
"enabled":"true",
"idPConfigurationId":"11111111-1111-1111-1111-111111111111",
"idPConfigurationName":"Initial SAML"
}
]
}Notes:
Use theidpConfigurationId to specify the authentication method for a user inAdd User to Site andUpdate User methods.
TheknownProviderAlias is returned when the authentication type is either Google or Salesforce.
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, seeHandling Errors.
List Authentication Configurations on Server
List information about all authentication instances associated with 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/auth-configurations
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 withTableau 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
List Connected Apps
Query all connected apps configured on a site.
URI
GET api/api-version/sites/site-id/connected-apps/direct-trust
Note: Theconnected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:connected_apps_direct_trust:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeCreate Connected App Secret. To get the secret value, seeQuery 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. Iffalseis 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, seeREST 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 2022 and Tableau Server 2023.1) and later.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, seePermissions Details . Permissions Overview
JWT Access Scope: tableau:content:read
- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
| field-expression | (Optional) An expression that lets you specify the set of available fields to return. When a request has avalid field expression, describing the attributes of a Tableau resource like a workbook or data source, onlythe attributes specified in the expression will be present in the response. For example, a field expressionthat results in a response containing only the resources LUIDs of the resources being requested would look like:
You can qualify the expression to return values based upon predefined keywords such as The supported fields for custom views are its attributes: For more information, seeUsing 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 hasa resource, an operator, and a value. For example, a filter that returns only resources created after a specified date would look like:
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 For more information, seeFiltering and Sorting in the Tableau REST API. |
| sort-expression | (Optional) An expression that lets you sort the Tableau resources present in the response. A sort expression containsan attribute name and a direction (
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 For more information, seeFiltering 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud) seeAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:content:readcURL 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 name="New name 2" createdAt="2016-02-03T23:35:09Z" updatedAt="2022-09-28T23:56:01Z" lastAccessedAt="2022-09-28T23:58:25Z" shared="false"> <view name="circle"/> <workbook name="marks and viz types 2"/> <owner 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", "lastAccessedAt": "2022-09-28T23:58:25Z", "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 arequest, and the details of those views that are displayed, depend on four things:
- Does the user have bothWrite andWebAuthoring permissions for the custom view?
- Is the user is the owner of the custom view
- Is there filter applied in the request parameters.
- Issite user visibility(Link opens in a new window) set toLimited?
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
viewIdand/orworkbookId, and don't includeownerId:- Users will see those custom views that they haveWrite andWebAuthoring permissions for.
- If site user visibility in not set toLimited, the Users will see those custom views that are "public", meaningthe value of their
sharedattribute istrue.
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 orRead permissions for the custom view.. |
| 405 | 405000 | Invalid Request Method | Request type was not GET. |
For more information, seeHandling 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 withTableau 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
List 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 as3.27. For more information, seeREST 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 haveRead (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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:readResponse Code
200
Response Body
<tsResponse> <permissions> <parent type="Project"api-placeholder">project-id" <datasourceapi-placeholder">datasource-id" owner="owner-user-id" /> <granteeCapabilities> <userapi-placeholder">user-id" /> <capabilities> <capability name="capability-name" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">group-id" /> <capabilities> <capability name="capability" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> ... additional grantee capability sets ... </permissions></tsResponse>Note: Theparent 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 callCreate Project or for an existing project by callingUpdate Project. For more information, seeLock Content Permissions to the Project(Link opens in a new window).
Version
Version 2.0 and later. For more information, seeREST 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. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <parent type="Project" /> <permissions> <datasource name="USPS-rates"> <owner/> </datasource> <granteeCapabilities> <group /> <capabilities> <capability name="Connect" mode="Allow"/> <capability name="Read" mode="Allow"/> </capabilities> </granteeCapabilities> </permissions></tsResponse>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 as3.27. For more information, seeREST 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Request Body
None
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="1" pageSize="100" totalAvailable="1"/> <dataAlerts> <dataAlert subject="alert-subject" creatorId="creator-id" createdAt="created-date" updatedAt="updated-date" frequency="alert-frequency" public="is-public-flag"> <owner name="username"/> <view name="view-name"> <workbook name="workbook-name"/> <project 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, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse> <dataAlerts> <dataAlert 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 name="admin"/> <view name="Shipping"> <workbook name="Superstore"/> <project name="Default"/> </view> </dataAlert> </dataAlerts></tsResponse>List Database Permissions
Get information about the permissions on a database asset.
URI
GET api/api-version/sites/site-luid/databases/database-luid/permissions
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 throughData 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 name="oracle.test.example.com:1521"/><granteeCapabilities> <user/> <capabilities><capability name="Read" mode="Allow"/> </capabilities></granteeCapabilities> </permissions></tsResponse>Example response without explicit permissions set on a database asset:
<tsResponse> <permissions><database name="stage"/> </permissions></tsResponse>Version
Version 3.5 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400120 | Bad request | Permissions could not be returned because support for explicit permissions is available for database assets associated with published data sources only. |
| 401 | 401000 | Unauthorized access | No authorization credentials were provided. |
| 400 | 400120 | Bad request | Support for explicit permissions is available for database assets associated with published data sources only. |
| 401 | 401002 | Unauthorized access | Invalid authorization credentials were provided. |
| 404 | 404000 | Resource not found | The site LUID in the URI doesn't correspond to an existing site. |
| 404 | 404031 | Database not found | The requested database could not be found. |
| 409 | 409045 | Database error | An unknown database asset error occurred. |
List Default Database Permissions
Get the default permissions applied to the database asset and its children tables.
Note: If a database is in a project, default database permissions are not evaluated to determine table permissions. UseQuery 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 as3.27. For more information, seeREST 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 throughData 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 name="oracle.test.example.com:1521"/><granteeCapabilities> <user/> <capabilities><capability name="Read" mode="Allow"/> </capabilities></granteeCapabilities> </permissions></tsResponse>Version
Version 3.5 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400120 | Bad request | Permissions could not be returned because support for explicit permissions is available for database assets associated with published data sources only. |
| 404 | 404000 | Site not found | The site LUID in the URI doesn't correspond to an existing site. |
| 404 | 404003 | Resource not found | The database LUID in the URI doesn't correspond to a database asset on the site. |
List Default Permissions
Returns details of default permission rules granted to users and groups for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, this method can also return details of default permission rules granted to users and groups for database or table resources in a project.
URI
Workbooks:
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks
Data sources:
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources
Data roles:
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles
Lenses:
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses
Metrics:
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics
Flows:
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows
Virtual Connections(endpoint introduced inAPI version(Link opens in a new window) 3.23):
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections
Databases:
GET /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases
Tables:
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 as3.27. For more information, seeREST 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 theProjectLeader 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess 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:readResponse Code
200
Response Body
<tsResponse> <permissions><project name="project-name" /><granteeCapabilities> <user /> <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.
- Version 3.23 and later for the virtual connection default permissions methods.
- For more information, seeREST 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. |
For more information, seeHandling Errors.
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 theList Server Schedules method.Note that theList Server Schedules method is global to the server; schedules are not specific to a site. Therefore, the URI for theList Server Schedules method does not include/sites/ or a site ID. However, individual scheduled tasks are specific to a site, and the URI forQuery Extract Refresh Tasks must include the site information.
For more information about refresh tasks, seeManage 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 as2.2. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
JWT Access Scope
Not available.
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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> <extractapi-placeholder">task-id" priority="task-priority" type="incremental-or-full" > <workbookapi-placeholder">workbook-id" /> </extract> <extractapi-placeholder">task-id" priority="task-priority" type="incremental-or-full" > <datasourceapi-placeholder">datasource-id" /> </extract> ... additional extract refresh tasks ... </extracts></tsResponse>Version
Version 2.2 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/schedules/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba/extracts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings><pagination pageNumber="1" pageSize="100" totalAvailable="2" /> <extracts> <extract priority="60" type="FullRefresh"> <datasource /> </extract> <extract 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.
Note: Virtual connection extracts are listed in the response, but are not identified by an element the way that workbooks and published data sources are.
URI
GET /api/api-version/sites/site-id/tasks/extractRefreshes
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that the user is a member of. |
JWT Access Scope
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
tableau:tasks:read (this scope is included in the scope:tableau:tasks)
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
cURL Example
curl "http://MY-SERVER/api/3.27/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 Response
On Tableau Server, a list of extract refresh tasks with their server schedules is returned.
<tsResponse>
<tasks>
<task>
<extractRefresh
priority="nn"
consecutiveFailedCount="n"
type="REFRESH_EXTRACT">
<schedule
name="schedule_name"
state="state"
priority="nn"
createdAt="DATE_TIME"
updatedAt="DATE_TIME"
type="Extract"
frequency="frequency"
nextRunAt="DATE_TIME" />
<datasource />
</extractRefresh>
</task>
<task>
<!-- ... additional tasks ... -->
</task>
</tasks>
</tsResponse>{
"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 Response
On Tableau Cloud, a list of extract tasks with their frequency is returned.
<tsResponse>
<tasks>
<task>
<extractRefresh 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/>
</extractRefresh>
</task>
</tasks>
</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": "Thursday" }
]
}
}
},
"workbook": {
"id": "7e766949-7166-4b3d-90ba-784f7575743b"
}
}
}
}
}Version
Version 2.6 and later. For more information, seeREST API and Resource Versions.
Errors
| 405 | 40500 | Invalid requests method | Request type was notGET |
For more information, seeHandling Errors.
List 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:permissions:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse > <permissions> <flow name="flow-name"> <owner/> </flow> <granteeCapabilities> <group/> <capabilities> <capability name="Read" mode="Allow"/> <capability name="Write" mode="Allow"/> ... additional capabilities ... </capabilities> </granteeCapabilities> </permissions></tsResponse>Note: Theparent element is included in the response only if theworkbook'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 callCreate Project(Link opens in a new window) or for an existing project by callingUpdate Project(Link opens in a new window).For more information, seeLock Content Permissions to the Project(Link opens in a new window).
Version
Version 3.3 and later. For more information, seeREST 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. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 name="SQLServerUserNamePassword Good"> <owner/> </flow> <granteeCapabilities> <group/> <capabilities> <capability name="Read" mode="Allow"/> <capability name="Write" mode="Allow"/> </capabilities> </granteeCapabilities> </permissions></tsResponse>List followed metrics groups
Gets the user's followed metrics. Optionally metrics can be grouped by characteristics like datasource, and sorted.
Version: Available in API 3.23 (Tableau Cloud December 2023) and later. Not available for Tableau Server.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`Tableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/metrics:followedMetricsGroups
List Group Sets
Lists all group sets matching optional filter and ordered by optional sort expression.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
Version:Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
| filter-expression | (Optional) An expression that lets you specify a subset of group sets to return. You can filter on predefined fields such asname. You caninclude multiple filter expressions. For more information, seeFiltering 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 theinformation that's returned is undefined. For more information, seeFiltering and Sorting. |
Request Body
None
cURL Request Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets&[resultlevel=[members,local]]" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<tsResponse version-and-namespace-settings>
<pagination pageNumber="1" pageSize="100" totalAvailable="3"/>
<groupSets>
<groupSet name="All Users" groupCount="1">
<group name="group-one"/>
</groupSet>
<groupSet name="active-directory-group-import">
<group name="group-two"
</groupSet>
<groupSet name="local-group-license-on-login">
<group name="group-three"
</groupSet>
</groupSets>
</tsResponse>{
"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’tGET. |
| 409 | 409120 | Group set not found | The group set ID in the URI doesn't correspond with an existing group set. |
For more information, seeHandling 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
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.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
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 theData 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_categories:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 theData Labels in the REST API(Link opens in a new window) topic.
AData 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 as3.27. For more information, seeREST 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 categorieswarning,certification, andsensitivity, 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_values:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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/> </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 definition measurement periods
Gets the measurement periods for the specified metric definition.
Version: Available in API 3.25 (Tableau Cloud March 2025 / Server 2025.1) and later. Not available for Tableau Server.Version Overview
Permissions: Can only be called by users with site or server administrator permissions.Permissions OverviewPermissions Overview
License: No additional license required.
Access Scope: `tableau:content:read`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
POST {server}/api/-/pulse/measurementPeriods
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.Version Overview
Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view.Permissions OverviewPermissions Overview
License: No additional license required.
Access Scope: tableau:insight_definitions_metrics:read
AccessTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/definitions
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 methodswill 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 as3.27. For more information, seeREST 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 metricname, or attributes of the associatedowner orproject. You can include multiple filter expressions. For more information, seeFiltering 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, seeFiltering 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 caninclude multiple field expressions in a request. For more information, seeUsing Fields in the REST API. |
Note: Thefilter andsort parameters can be combined with each other and with paging parameters andfields parameters using an ampersand (&).
Request Body
None
Permissions
Users who are not administrators can get only the metrics for which they have implicit or explicitRead (view) permissions.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="total-available" /> <metrics> <metricapi-placeholder">metric-id"name="name"description="metric-description"webpageurl="metric-webpageurl" createdAt="datetime-created" updatedAt="datetime-updated" suspended="suspended-flag" > <projectapi-placeholder">project-id" name="project-name" /> <ownerapi-placeholder">user-id" /> <tags> <tag label="tag"/> ... additional tags ... </tags><underlyingView"api-placeholder">view-id" /> </metric> ... additional metrics ... </metrics></tsResponse>Thedatetime-created anddatetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.9 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response body:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="27"/> <metrics> <metricname="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 name="Tableau Samples"/> <owner/> <tags/>underlyingView="29dae0cd-1862-4a20-a638-e2c2dfa682d4" </metric> <metric 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 name="default"/> <owner/> <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.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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/definitions/{definition_id}/metrics
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.
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 as3.27. For more information, seeREST 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.27/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
<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>{
"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, seeHandling Errors.
List 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 as3.27. For more information, seeREST 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:readResponse Code
200
Response Body
<tsResponse> <permissions> <project name="project-name" /> <granteeCapabilities> <user /> <capabilities> <capability name="capability" mode="capability-mode" /> <capability name="capability" mode="capability-mode" /> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <group /> <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, seeREST 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. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <permissions> <project name="default"> <owner/> </project> <granteeCapabilities> <group/> <capabilities> <capability name="Read" mode="Allow"/> <capability name="Write" mode="Allow"/> </capabilities> </granteeCapabilities> </permissions></tsResponse>List Pulse user preferences
Gets the signed in user's preferences for notifications channels and cadence, and for grouping and sorting followed metrics in REST responses and UI.
Version: Available in API 3.24 (Tableau Cloud December 2024) and later. Not available for Tableau Server.Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of subscriptions.Permissions Overview
License: No additional license required.
Access Scope: `tableau:user_preferences:read`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/user/preferences
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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| eas-id | The unique ID of the registered EAS. |
Request Body
None
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:external_authorization_servers:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 in Tableau Cloud June 2022 (API 3.16). Introduced in Tableau Server 2024.2 (API 3.23).
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 SCIM Configurations
Returns the System for Cross-domain Identity Management Configuration (SCIM) configurations on the Tableau Cloud site.
Version: Available in API 3.26 (Tableau Cloud August 2025) and later.
License: No additional license required.
Permissions: Tableau Cloud site admins only.
Access Scope:tableau:scim_configurations:read
Scope added in API 3.27 (Tableau Cloud December 2025)
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window);access scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window).
URI
GET /api/api-version/sites/site-luid/scimConfigurations
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
None
cURL Request Example
GET request: curl --location 'https://prod-ca-a.online.tableau.com/api/3.27/sites/0f04ea64-0d72-424a-afd8-ee7d758dc9b8/scimConfigurations'
Response Code
200
Response Body
<tsResponse> <scimConfigurations> <scimConfiguration> <id>3400f62c-7569-4608-89c9-98c4194390ee</id> <idpConfigurationId>cf73f5a0-8483-42f8-89ac-91a5aeed0bcc</idpConfigurationId> <isApiTokenActive>true</isApiTokenActive> <isOwner>true</isOwner> <name>SCIM Employees</name> <createdAt>2025-08-09 15:15:02.100</createdAt> </scimConfiguration> <scimConfiguration> <id>065693d8-436a-4738-a8f1-375953a2a888</id> <idpConfigurationId>95dcdf3b-30eb-42ae-b938-7ffca3e11fdc</idpConfigurationId> <isApiTokenActive>false</isApiTokenActive> <isOwner>false</isOwner> <name>SCIM Contractors</name> <createdAt>2025-03-27 11:07:49.129</createdAt> </scimConfiguration> </scimConfigurations><tsResponse>
{ "scimConfigurations": { "scimConfiguration": [ { "id": "3400f62c-7569-4608-89c9-98c4194390ee", "idpConfigurationId": "cf73f5a0-8483-42f8-89ac-91a5aeed0bcc", "isApiTokenActive": true, "isOwner": true, "name": "SCIM Employees", "createdAt": "2025-08-09 15:15:02.100" }, { "id": "065693d8-436a-4738-a8f1-375953a2a888", "idpConfigurationId": "95dcdf3b-30eb-42ae-b938-7ffca3e11fdc", "isApiTokenActive": false, "isOwner": false, "name": "SCIM Contractors", "createdAt": "2025-03-27 11:07:49.129" } ] }}
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header is invalid or has expired. |
For more information, seeHandling Errors.
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 namelocal.
URI
GET /api/api-version/domains/
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
Request Body
None
Permissions
This method can only be called by server administrators.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:domains:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsRequest> <domainList> <domainapi-placeholder">domain-id-int" name="domain-name" shortName="domain-nickname" /> </domainList></tsRequest>Version
Version 3.11 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 405 | 405000 | Invalid request method | Request type was notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/domains" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response body:
<tsRequest> <domainList> <domain 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, seeCreate 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 as2.2. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
Request Body
None
Permissions
On Tableau Server, any user able to schedule extract refreshes and any site or server administrator can get schedules.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:schedules:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size"totalAvailable="total-available" /> <schedules> <scheduleapi-placeholder">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>Thedatetime-created,datetime-last-updated,datetime-next-run-time, anddatetime-expiration attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Example
curl "http://MY-SERVER/api/3.27/schedules" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings > <pagination pageNumber="1" pageSize="100" totalAvailable="3" /> <schedules><schedule 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 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 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, seeREST 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 notGET. |
For more information, seeHandling 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 withTableau 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
List site alerts
List the alerts for the authorized user user on a specified site.
Version: Available in API 3.25 (Tableau Cloud March 2025 / Server 2025.1) and later. Not available for Tableau Server.Version Overview
Permissions: Any users can list the alerts for sites that they administer.Permissions OverviewPermissions Overview
License: No additional license required.
Access Scope: `tableau:insights_alerts:read`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/alerts
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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 unified access token (UAT) or connected app. For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud) or access scopes for connected apps:Tableau Cloud connected app scopes(Link opens in a new window) orTableau Server connected apps scopes(Link opens in a new window).Available in API 3.20 (Tableau Cloud June 2023 / Tableau Server 2023.3.
Request Body
None
Curl Example
curl "http://MY-SERVER/api/3.27/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.
<tsResponse>
<pagination pageNumber="pageNumber"
pageSize="page-size"
totalAvailable="total-available" />
<subscriptions>
<subscription
subject="subscription-subject"
attachImage="attach-image-flag"
attachPdf="attach-pdf-flag"
suspended="suspended-flag"
pageOrientation="page-orientation"
pageSizeOption="page-size-option" >
<content
type="content-type"
sendIfViewEmpty="send-view-if-empty-flag"/>
<schedule name="schedule-name"/>
<user name="user-name" />
</subscription>
<!-- ... additional subscriptions ... -->
</subscriptions>
</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"
}
}
}
}Tableau Cloud Request
For Tableau Cloud, a task with frequency is returned.
<tsResponse>
<pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
<subscriptions>
<subscription
subject="Subscription - postman"
message="weekly report"
attachImage="true"
attachPdf="false"
suspended="false">
<content
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
name="me@mysite.com"/>
</subscription>
</subscriptions>
</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" }
]
}
}
},
"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, seeREST 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 notGET. |
For more information, seeHandling 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.Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can list subscriptions.Permissions Overview
License: No additional license required.
Access Scope: tableau:metric_subscriptions:read
Access ScopesTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
GET {server}/api/-/pulse/subscriptions
List Table Permissions
Get information about the permissions on a table asset.
URI
GET api/api-version/sites/site-id/tables/table-id/permissions
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 throughData 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 name="_WarehouseConfig"/><granteeCapabilities> <user/> <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 type="Database"/> <table name="BigMachines"/> </permissions></tsResponse>Version
Version 3.5 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400120 | Bad request | Permissions could not be returned because support for explicit permissions is available for table assets associated with published data sources (not embedded data sources) only. |
| 401 | 401000 | Unauthorized access | No authorization credentials were provided. |
| 401 | 401002 | Unauthorized access | Invalid authorization credentials were provided. |
| 404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404032 | Table not found | The requested table asset could not be found. |
| 409 | 409052 | Table error | An unknown table asset error occurred. |
| 409 | 409053 | Unknown table query error | An unknown error occurred and the table query could not complete. |
List Tableau extensions server settings
Lists the settings for extensions of a server.
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:tableau:extensions_server_settings:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
GET /api/api-version/settings/extensions
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
Request Body
None
cURL Request Example
curl -X GET "http://MY-SERVER/api/3.27/settings/extensions" -H "Content-Type: application/xml" -H "X-Tableau-Auth: SBGBfOYRSN2JoFe866wpIg|hLI0ZzWmK3xfMtwD8WoztCMqfWaFdcCj|a946d998-2ead-4894-bb50-1054a91dcab3"
Response Code
200
Response Body
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 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, seeHandling 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: Any authenticated user can list the extension settings for a site using this method. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:extensions_site_settings:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
GET /api/api-version/sites/site-luid/settings/extensions
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
None
cURL Request Example
curl --location "http://MY-SERVER/api/3.27/sites/a946d998-2ead-4894-bb50-1054a91dcab3/settings/extensions " --header "X-Tableau-Auth: SBGBfOYRSN2JoFe866wpIg|hLI0ZzWmK3xfMtwD8WoztCMqfWaFdcCj|a946d998-2ead-4894-bb50-1054a91dcab3"
Response Code
200
Response Body
<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>{
"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, seeHandling Errors.
List Users with Custom View as Default
Gets the list of users whose default view is the specified custom view.
Version:Available in 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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
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, seeHandling Errors.
List 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 as3.27. For more information, seeREST 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 haveRead (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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:readResponse Code
200
Response Body
<tsResponse> <parent type="Project"api-placeholder">project-id" /> <permissions> <view/> <owner/> </view> <granteeCapabilities> <user/> <capabilities> <capability name="capability-name" mode="capability-mode"/> <capability name="capability-name" mode="capability-mode"/> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <user/> <capabilities> <capability name="capability-name" mode="capability-mode"/> <capability name="capability-name" mode="capability-mode"/> ... additional capabilities ... </capabilities> </granteeCapabilities> <granteeCapabilities> <group/> <capabilities> <capability name="capability-name" mode="capability-mode"/> ... additional capabilities ... </capabilities> </granteeCapabilities> </permissions></tsResponse>Note: Theparent 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 callCreate Project or for an existing project by callingUpdate Project. For more information, seeLock Content Permissions to the Project(Link opens in a new window).
Version
Version 3.2 and later. For more information, seeREST 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. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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/> <owner/> </view> <granteeCapabilities> <group/> <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/> <capabilities> <capability name="ExportImage" mode=mode="Allow"/> <capability name="AddComment" mode=mode="Allow"/> </capabilities> </granteeCapabilities> <granteeCapabilities> <user/> <capabilities> <capability name="AddComment" mode=mode="Allow"/> </capabilities> </granteeCapabilities> </permissions></tsResponse>List Virtual Connection Database Connections
Returns information about database connections in the specified virtual connection
Version:Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1) and later.Version Overview
License:RequiresTableau 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:tableau:content:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 notGET. |
For more information, seeHandling Errors.
List Virtual Connection Permissions
Returns a list of permissions for a specific virtual connection.
URI
GET /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the virtual connection. |
| virtualconnection‑id | The ID of the virtual connection to get permissions for. |
Request Body
None
Permissions
You must be an administrator or have theRead (View) permission for the virtual connection (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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:readResponse Code
200
Response Body
<tsResponse> <permissions> <parentapi-placeholder">project-luid" type="Project"/> <virtualConnectionapi-placeholder">virtualconnection-luid" name="virtualconnection-name"> <ownerapi-placeholder">owner-luid"/> </virtualConnection> <granteeCapabilities> <groupapi-placeholder">group-luid"/> <capabilities> <capability name="capability-name" mode="capability-mode"/> <!-- ...additional capabilities... --> </capabilities> </granteeCapabilities> <granteeCapabilities> <userapi-placeholder">user-luid"/> <capabilities> <capability name="capability-name" mode="capability-mode"/> <!-- ...additional capabilities... --> </capabilities> </granteeCapabilities> <!-- ...additional granteeCapability sets... --> </permissions></tsResponse>Note: Theparent 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 callCreate Project or for an existing project by callingUpdate Project. For more information, seeLock Content Permissions to the Project(Link opens in a new window).
Version
Version 3.23 and later. For more information, seeREST 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 | Virtual Connection not found | The virtual connection ID in the URI doesn't correspond to an existing virtual connection. |
| 405 | 405000 | Invalid request method | Request type was notGET. |
For more information, seeHandling Errors.
Example
curl --location 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
List Virtual Connection Revisions
Lists revisions for a virtual connection.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:You must have theOverwrite permission for the virtual connection and your site role must be at leastCreator. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:virtual_connections:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Note: This method can only succeed if version history is enabled for the specified site. For more information, seeMaintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.
URI
GET /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/revisions
GET /api/api-version/sites/site-luid/virtualconnections/virtual-connection-luid/revisions/?pageSize=page-size&pageNumber=page-number
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| virtual-connection-luid | The LUID for 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
Request Body
None
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/revisions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3 '
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="page-count"/> <revisions> <revision revisionNumber="revision-number" publishedAt="datetime" deleted="deleted-flag" current="current-flag"> <publisher name="publisher-username"/> </revision> <revision revisionNumber="revision-number" publishedAt="datetime" deleted="deleted-flag" current="current-flag"> <publisher name="publisher-username"/> </revision> <!-- ...Additional revisions... --></revisions></tsResponse>"pagination": { "pageNumber": "page-number", "pageSize": "page-size", "totalAvailable": "page-count" }, "revisions": { "revision": [ { "publisher": { "id": "publisher-luid", "name": "publisher-username" }, "revisionNumber": "revision-number", "publishedAt": "datetime", "deleted": deleted-flag, "current": current-flag }, { "publisher": { "id": "publisher-luid", "name": "publisher-username" }, "revisionNumber": "revision-number", "publishedAt": "datetime", "deleted": deleted-flag, "current": current-flag }, { ...Additional revisions... } ] }}Thecurrent property of a revision showsfalse for all revisions except for the currently active virtual connection revision, in which case it showstrue.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400058 | Generic error | An unknown error occurred. |
| 403 | 403054 | User not authorized. | User doesn't have permissions to revisions on this virtual connection. Check the user's permissions. |
| 403 | 403173 | User not authorized. | User forbidden from listing virtual connection revisions. Check the user's permissions and site role. |
| 403 | 403053 | Revision history is disabled on the site. | Check the revision history setting. |
| 404 | 404049 | Virtual connection not found | Check the virtual connection LUID. |
For more information, seeHandling 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:RequiresTableau Data Management(Link opens in a new window).
Permissions:By default, all users can view virtual connections. Permissions Overview
JWT Access Scope:tableau:content:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
| filter-expression | (Optional) An expression that lets you specify a subset of virtual connections to return. You can filter on predefined fields such asname,tags, andcreatedAt. You can include multiple filter expressions. For more information, seeFiltering 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, seeFiltering 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 notGET. |
For more information, seeHandling 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:webhooks:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <webhooks> <webhook 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 name="webhook_owner_name"/> </webhook> <!-- ... additional webhooks ... --> </webhooks></tsResponse>
List 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 as3.27. For more information, seeREST 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 by including this scope in the JSON Web Token (JWT). For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help orAccess Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:readResponse Code
200
Response Body
<tsResponse> <parent type="Project"api-placeholder">project-id" /> <permissions> <workbookapi-placeholder">workbook-id" name="workbook-name > <owner="owner-user-id" /> </workbook> <granteeCapabilities> <userapi-placeholder">user-id" /> <capabilities> <capability name="capability" mode="capability-mode" /> ... additional capabilities for users ... </capabilities> </granteeCapabilities> <granteeCapabilities> <groupapi-placeholder">group-id" /> <capabilities> <capability name="capability" mode="capability-mode" /> ... additional capabilities for groups ... </capabilities> </granteeCapabilities> ... additional grantee capability sets ... </permissions></tsResponse>Note: Theparent 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 callCreate Project or for an existing project by callingUpdate Project. For more information, seeLock Content Permissions to the Project(Link opens in a new window).
Version
Version 2.0 and later. For more information, seeREST 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. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <parent type="Project" /> <permissions> <workbook name="Finance"> <owner/> </workbook> <granteeCapabilities> <group/> <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>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 theMove 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID of the site that contains the database. |
Request Body
<tsRequest> <contentLocationRequest> <location type="location-type" /> <contentAction action="action-type" /> <resourceList> <resource contentType="asset-type"/> <!-- ... more database resources ... --> </resourceList> </contentLocationRequest></tsRequest>ThecontentAction element is optional.
- If thecontentAction element is not included, moving the database will also move its tables.
- If thecontentAction element is included and the action attribute is set toMoveDatabaseOnly, moving the database will not move its tables.
TheresourceList element can contain a minimum of 1 and a maximum of 1000resource 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 databasewithout its tables, you must haveread andchangeHierarchy permissions for the database, andwrite permission for the target project.
If you are moving both a database and its tables, you must haveread andchangeHierarchy permissions for both the database and its tables, andwrite permission for the target project.
Note: Currently, you can only set theChangeHierarchy permission for databases and tables using the REST API. SeeAdd Database Permissions andAdd Table Permissions for information on adding this permission.
Setting the required database and table permissions depends on whether the database is in a project or not.
- If the database is in a project, the database and table permissions will follow the rules for permissions on content inside of projects. SeeSet Permissions(Link opens in a new window) for information on these rules.
- If the database is not in a project, the database and table permissions will follow the rules for permissions on external assets. SeeSet permissions on individual external assets(Link opens in a new window) for information on these rules.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:database_projects:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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." errorCode="404031"/> </warnings></tsResponse>Version
Introduced Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17). For more information, seeREST 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 | Thelocation element's type attribute must be "PROJECT". |
| 400 | 409103 | Invalid content type | Theresource element'scontentType 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, seeHandling 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 type="PROJECT" /> <resourceList> <resource 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID of the site that contains the table. |
Request Body
<tsRequest> <contentLocationRequest> <location type="location-type" /> <resourceList> <resource contentType="asset-type"/> <!-- ...more resources... --> </resourceList> </contentLocationRequest></tsRequest>TheresourceList element can contain a minimum of 1 and a maximum of 1000resource 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 haveread andchangeHierarchy permissions for the table, andwrite permission for the target project.
If you are moving both a database and its tables, you must haveread andchangeHierarchy permissions for both the database and its tables, andwrite permission for the target project.
Note: Currently, you can only set theChangeHierarchy permission for databases and tables using the REST API. SeeAdd Database Permissions andAdd Table Permissions for information on adding this permission.
Setting the required table permissions depends on whether the parent database is in a project or not.
- If the table is in a project, the table permissions will follow the rules for permissions on content inside of projects. SeeSet Permissions(Link opens in a new window) for information on these rules.
- If the table is not in a project, the table permissions will follow the rules for permissions on external assets. SeeSet permissions on individual external assets(Link opens in a new window) for information on these rules.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:table_projects:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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." errorCode="404032"/> </warnings></tsResponse>Version
Introduced Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17). For more information, seeREST 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 | Thelocation element's type attribute must be "PROJECT". |
| 400 | 409103 | Invalid content type | Theresource element'scontentType 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, seeHandling 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 type="PROJECT" /> <resourceList> <resource 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 as3.27. For more information, seeREST 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:
|
| 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:favorites:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.8 and later. For more information, seeREST 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, seeHandling 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 publisheddata source, callUpdate Data Source orUpdate 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 explicitPublish permissions for the data source, or are a Tableau administrator.Note: ThequeryTaggingEnabled attribute is returned only for administrator users.Permissions Overview
JWT Access Scope:tableau:datasources:create
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 theasJob 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 callingInitiate File Upload, send portions of the file to the server usingAppend to File Upload, and then commit the upload by callingPublish 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 theHyper API(Link opens in a new window).The data must include a singlefact 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, butdoes not perform any validation, such as referential integrity checking. If the Hyper API can’t infer the data object model of aHyper 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 thecomponents that are required in order for other users to see and interact with the data source. For example, if the datasource is based on an Excel spreadsheet, you typically publish a packaged data source (.tdsx file) that containsall 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 notconverted to Hyper.
For more information, seePublishing 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 as3.27. For more information, seeREST 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, orfalse to fail if the specified data source already exists. The default isfalse. Ifoverwrite-flag is set totrue but the data source doesn't already exist, the operation succeeds. You can include both theoverwrite andappend parameters in a request, but they cannot both betrue. |
| asJob-value | A Boolean value that is used to publish data sources asynchronously. If you set this value tofalse (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 totrue, 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 callingQuery Job. |
| append-flag | true to append the data being published to an existing data source that has the same name. The default isfalse. Ifappend-flag is set totrue 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 bean extract with the file extension If an extract was stored using the multiple tables option, you can't append data to it. You can include both theoverwrite andappend parameters in a request, but they cannot both betrue. |
| 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 toInitiate 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, ortde the kind of file that you are uploading. This value is required if you are callingPublish Data Source in order to commit a file that was previously uploaded usingAppend 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-stringContent-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 /> </datasource></tsRequest>--boundary-stringContent-Disposition: name="tableau_datasource"; filename="Sales.TDSX"Content-Type: application/octet-streamcontent-of-datasource-file--boundary-string--Committing a file previously uploaded
--boundary-stringContent-Disposition: name="request_payload"Content-Type: text/xml<tsRequest><datasource name="Sales" ><connectionCredentials name="janedoe" password="xxxxxx"embed="False" oAuth="True" /><project /> </datasource></tsRequest>--boundary-string--Publishing a file in the request body
Content-Length: 16301Content-Type: multipart/form-data; boundary=----------------------my_boundary_string----------------------my_boundary_stringContent-Disposition: form-data; name="part1.json"Content-Type: application/json{ "the_JSON" : {"foo" : "bar" }}----------------------my_boundary_stringContent-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: 16301Content-Type: multipart/form-data; boundary=----------------------my_boundary_stringContent-Disposition: form-data; name="part1.json"Content-Type: application/json{ "the_JSON" : {"foo" : "bar" }}----------------------my_boundary_stringContent-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:
|
datasource name | (Required) The name to assign to the data source when it is saved on the server. |
datasource useRemoteQueryAgent | (Optional) Whentrue, this flag willallow 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.
|
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 /> </datasource></tsRequest>Response Code
201
Response Body
<tsResponse> <datasourceid="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"> <projectid="56c86f04-b834-4a08-a561-86497bb4b2df"name="Visualization"/> <owner/> <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": [] }}ThecreatedAt andupdatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Response Headers
Location: /api/3.27/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 theContent-Length value is set. |
| 400 | 400000 | Missing data source | There is no attachment in the request for the data source. |
| 400 | 400008 | Invalidoverwrite value | Theoverwrite parameter must be set totrue orfalse. |
| 400 | 400008 | Invalidappend value | Theappend parameter must be set totrue orfalse. |
| 400 | 400008 | Invalidembed value | The request body contains a<connectionCredentials> element and it has anembed attribute whose value is nottrue 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 anuploadSessionId parameter but no file type, or the file type was something other thanhyper,tds,tdsx, ortde. |
| 400 | 400010 | Unexpected attachments | The message had both auploadSessionId 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 theContent-Length value is set. |
| 400 | 400055 | Incompatibleoverwrite andappend values | Theoverwrite andappend parameter cannot both be set totrue. |
| 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 theoverwrite parameter was not set totrue. |
| 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 | Theappend parameter istrue 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 notPOST. |
For more information, seeHandling 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 callingInitiate File Upload(Link opens in a new window), send portions of the file to the server usingAppend 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 theuploadSessionId and theflowType 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 as3.27. For more information, seeREST 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, orfalse to fail if the specified flow already exists. The default isfalse. If overwrite-flag is set totrue 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 ortflx 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 /></flow><connections> <connection serverAddress="server-address" serverPort="port-number"> <connectionCredentials name="connection-username" password="connection-password" embed="embed-flag" oAuth="oauth-flag" /></connection></connections></tsRequest>--boundary-stringContent-Disposition: name="tableau_flow"; filename="flow-file-name"Content-Type: application/octet-streamcontent-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 toTrueinstructs 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).
tableau:flows:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
201
Response Body
<tsResponse> <flow name="ShortTermRentalNola222" description="" webpageUrl="http://localhost/#/flows/3" fileType="tflx" createdAt="2018-11-20T19:28:58Z" updatedAt="2018-11-20T19:28:58Z"> <project name="Default" /> <owner /> </flow></tsResponse>Version
Version 3.3 and later. For more information, seeREST 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 totrue. |
| 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 notPOST. |
For more information, seeHandling Errors.
Publish Virtual Connection
Publishes a downloaded JSON-representation of a virtual connection.
If the virtual connection does not exist, it will be published as a new virtual connection. If it already exists, and you've chosen to overwrite it, the virtual connection will be published as a revision of the existing virtual connection.
The virtual connection can be published as a draft or as an active virtual connection.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:You must have theOverwrite permission for the virtual connection and your site role must be at leastCreator. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:virtual_connections:create
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/virtualconnections
POST /api/api-version/sites/site-luid/virtualconnections?publishAsDraft=publish-as-draft-flag
POST /api/api-version/sites/site-luid/virtualconnections?overwrite=overwrite-flag
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| publish-as-draft-flag | (Optional, boolean) Defaults to true.
Note: ThepublishAsDraft URI parameter is case sensitive. If the virtual connection contains an extract, thepublishAsDraft parameter value is ignored and the virtual connection is published as a draft. Note: If you are using the REST API to publish a virtual connection as a draft, note the virtual connection's LUID ( |
| overwrite-flag | (Optional, boolean) Defaults to false.
|
Request Body
(Use the icon in the top right corner to copy the text.)
<tsRequest> <virtualConnection name="virtualconnection-name"> <project/> <owner/> <content>virtualconnection-as-json</content> </virtualConnection></tsRequest>
(Use the icon in the top right corner to copy the text.)
{ "virtualConnection": { "project": { "id": "project-luid" }, "owner": { "id": "owner-luid" }, "content": "virtualconnection-as-json", "name": "virtualconnection-name" }}
Request Attributes
| virtualconnection-name | The name of the virtual connection you are publishing.If publishing an existing virtual connection as a revision, the virtual connection name is ignored. |
| project-luid | The LUID of the project you are publishing to. |
| owner-luid | This attribute is required, but is ignored. |
| virtualconnection-as-json | The virtual connection schema rendered as JSON, as obtained using theDownload Virtual Connection orDownload Virtual Connection Revision method. The schema appears in thecontent element (for XML output) orcontent property (for JSON output). Note: Changing the downloaded schema and then using it with this method isn't supported. When using the Publish Virtual Connection method, we recommend using the virtual connection schema format that matches the format you used for downloading it. This is important because the virtual connection schema returned by the download methods have escape characters in them if the output was JSON. If you download and publish using different formats, you will have to make changes to JSON representation of the virtual connection. In other words:
For more information on the difference between using XML and using JSON with the REST API, seeFundamentals of the Tableau Server REST API. |
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl --location 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections?overwrite=true&publishAsDraft=false' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml
Content of data.xml:
(Use the icon in the top right corner to copy the text.)
<tsRequest> <virtualConnection name="Batters"> <project/> <owner/> <content>virtualconnection-as-json</content> </virtualConnection></tsRequest>
Note: Replacevirtualconnection-as-json content in the above example with the virtual connection schema you downloaded using theDownload Virtual Connection method.
Response Code
201
Response Body
<tsResponse> <virtualConnection name="virtualconnection-name"> <project/> </virtualConnection></tsResponse>{ "virtualConnection": { "project": { "id": "project-luid" }, "id": "virtualconnection-luid", "name": "virtualconnection-name" }}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400201 | Generic error | An unknown error occurred. |
| 403 | 403175 | User not authorized. | Check to make sure the user has the required permissions. |
For more information, seeHandling Errors.
Publish Workbook
Publishes a workbook on the specified site. To make changes to a published workbook, callUpdate Workbook orUpdate Workbook Connection.
Version: Available in API 2.0 and later.
License: No additional license required.
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.
Access Scope:tableau:workbooks:create
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 theasJob parameter to make workbook publication asynchronous.
Alternatively, you can publish a workbook in multiple parts. To do that, you initiate a file upload by callingInitiate File Upload, send portions of the file to the server usingAppend to File Upload, and then commit the upload by callingPublish 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 ashidden. 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, seePublishing 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 as3.27. For more information, seeREST 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, orfalse to fail if the specified workbook already exists. The default isfalse. Ifoverwrite-flag is set totrue but the workbook doesn't already exist, the operation succeeds. |
| asJob-value | (Optional, boolean) Iffalse, 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 totrue, 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 callingQuery Job. Default value isfalse. |
| skip-connection-check-flag | (Optional, boolean) Iftrue, 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, followKeep Data Fresh guidelines(Link opens in a new window). Default value isfalse. |
| 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 toInitiate 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 ortwbx to indicate whether you have uploaded a workbook file (twb) or a packaged workbook file (twbx). This value is required if you are callingPublish Workbook in order to commit a file that was previously uploaded usingAppend 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 multi-part 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-stringContent-Disposition: name="request_payload"Content-Type: text/xml<tsRequest> <workbook name="workbook-name" showTabs="show-tabs-flag" description="workbook-description" thumbnailsUserId="user-luid"> <connections> <connection serverAddress="server-address" serverPort="port-number"> <connectionCredentials name="connection-username" password="connection-password" embed="embed-flag" /> </connection> </connections> <projectapi-placeholder">project-id"/> </workbook></tsRequest>--boundary-stringContent-Disposition: name="tableau_workbook"; filename="workbook-file-name"Content-Type: application/octet-streamcontent-of-workbook-file--boundary-string--Committing a file previously uploaded
--boundary-stringContent-Disposition: name="request_payload"Content-Type: text/xml<tsRequest> <workbook name="workbook-name" showTabs="show-tabs-flag" description="workbook-description" 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> <projectapi-placeholder">project-id"/> </workbook></tsRequest>--boundary-string--
Hiding a view when publishing a workbook
--boundary-stringContent-Disposition: name="request_payload"Content-Type: text/xml<tsRequest> <workbook name="workbook-name" showTabs="show-tabs-flag" description="workbook-description" 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><projectapi-placeholder">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:
|
| workbook-name | The name to assign to the workbook when it is saved on the server. |
| workbook-description | (Optional) Starting in API 3.20, the description for the workbook. |
| show-tabs-flag | (Optional) Specifytrue to have the published workbook show views in tabs; otherwise,false. The default isfalse. |
| user-luid | (Optional) The LUID of the user to generate thumbnails as. You can get the user LUID by callingGet 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 specifiesthe 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 toa 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 specifiesthe 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 toa 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 totrue 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 totrue to specify that the value of thename attribute in the<connectionCredentials> element is an OAuth username. In that case, no password is required and the value of theembed attribute specifies whether to embed the OAuth credential with the workbook, and the server address and port number are not required. For more information, seeOAuth Connections(Link opens in a new window) in the Tableau Server documentation. |
| hide-view-flag | Setting this flag totrue will cause the named view to be hidden in the published workbook. The default value isfalse.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 orfalse to not encrypt extracts. For more information, seeExtract and Encryption Methods. |
Response Code
201
Response Body
<tsResponse> <workbook api-placeholder">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" > <projectapi-placeholder">project-id" name="project-name"/> <ownerapi-placeholder">workbook-owner-id"/> <tags/> <views> <view api-placeholder">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>Thedatetime-created anddatetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
cURL Request 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/><views><view name="Test Sheet 1" hidden="true" /></views></workbook></tsRequest>Example response:
<tsResponse><workbookid="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 name="Default"/> <owner/> <tags/> <views><view 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>Response Headers
Location: /api/3.27/sites/site-id/workbooks/workbook-id
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 nouploadSessionID parameter. |
| 400 | 400000 | Unexpected attachments | The message had both anuploadSessionId parameter and an attachment, or the request body contained more than one attachment. |
| 400 | 400008 | Invalidembed value | The request body contains a<connectionCredentials> element and it has anembed attribute whose value is nottrue or false. |
| 400 | 400008 | Invalid overwrite value | The overwrite parameter must betrue orfalse. |
| 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 anuploadSessionId 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 theoverwrite parameter was not set totrue. |
| 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 astrue but no workbook with the specified name exists on the site. |
| 404 | 404015 | File upload not found | The file upload session ID in theuploadSessionId parameter doesn't correspond to an existing file upload on the site. |
| 405 | 405000 | Invalid request method | Request type was notPOST. |
For more information, seeHandling Errors.
Query All Quality Warning Triggers by Content
Get information about all quality warning triggers for a content item.
URI
GET api/api-version/sites/site-id/dataQualityTriggers/content-type/content-luid
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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:
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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response
<tsResponse> <dataQualityTriggerList><dataQualityTrigger 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, seeREST 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 as3.27. For more information, seeREST 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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:columns:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 name="StateProvinceID" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219"> <site/></column></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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 as3.27. For more information, seeREST 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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:columns:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 name="AddressID" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219"><site/></column><column name="AddressLine1" remoteType="WSTR" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219"><site/></column> </columns></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theGet Label method instead.
URI
GET api/api-version/sites/site-id/dataQualityCertifications/certification-luid
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theGet Labels method instead.
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 as3.27. For more information, seeREST 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:
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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theGet Labels method instead.
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 as3.27. For more information, seeREST 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:
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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response:
<tsResponse> <dataQualityWarningList><dataQualityWarning 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/> <owner/></dataQualityWarning> </dataQualityWarningList></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theGet Label method instead.
URI
GET api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response:
<tsResponse> <dataQualityWarning 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/><owner/> </dataQualityWarning></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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 as3.27. For more information, seeREST 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 haveConnect 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).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <datasourceapi-placeholder">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" > <projectapi-placeholder">project-id" name="project-name" /> <ownerapi-placeholder">datasource-owner-id" /> <tags> <tag label="tag"/> ... additional tags ... </tags> <askData enablement="enablement-setting"/> </datasource></tsResponse>Thedatetime-created anddatetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 1.0 and later. For more information, seeREST 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 haveConnect 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <datasource 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 name="default"/> <owner/> <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, seeMapping 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 as3.27. For more information, seeREST 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 haveRead (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).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <connections> <connectionapi-placeholder">connection-id" type="connection-type" serverAddress="server-address" serverPort="port" userName="connection-user-name" queryTaggingEnabled="query-tagging-enabled" authenticationType="authentication-type" useOAuthManagedKeychain="using-OAuth-managed-keychain-or-not /> />< ... additional connections ... > </connections></tsResponse>Version
Version 2.3 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <connections> <connection type="dataengine" /> <connection type="dataengine" /> <connection 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, seeMapping ConnectionType Names for more information.
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 theQuery 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.
Version: Available in API 1.0 and later.
License: No additional license required.
Permissions: Tableau Server users who are not server administrators or site administrators can view a data source only if they haveConnect permissions for the data source (either explicitly or implicitly).
Access Scope:tableau:content:read
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
| filter-expression | (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such asname andupdatedAt. You caninclude multiple filter expressions. For more information, seeFiltering 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 theinformation that's returned is undefined. For more information, seeFiltering 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 caninclude multiple field expressions in a request. For more information, seeUsing Fields in the Rest API. |
Note: Thefilter andsort parameters can be combined with each other and with paging parameters andfields parameters using an ampersand (&).
Request Body
None
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" /> <datasources> <datasourceapi-placeholder">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" > <projectapi-placeholder">project-id" name="project-name" /> <ownerapi-placeholder">datasource-owner-id" /> <tags> <tag label="tag"/> <!-- potential additional tags --> </tags> </datasource> <!-- potential additional data sources --> </datasources></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": [{ "label": "tag" }] }] }}
cURL Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"Example response:
<tsResponseversion-and-name-space-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="2"/> <datasources> <datasource name="Sample - Coffee Chain (Access)" size="1" type="googledrive" 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 name="Default"/> <owner/> <tags> <tag label="test"/> </tags> </datasource> </datasources></tsResponse>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 notGET. |
For more information, seeHandling Errors.
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 as3.27. For more information, seeREST 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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:databases:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response:
<tsResponse> <database name="dataengine_42020_789079537040lea.hyper" connectionType="hyper" isEmbedded="true" isCertified="true" certificationNote="Verified" type="File" filePath="dataengine_42020_789079537040lea.hyper" contentPermissions="ManagedByOwner"> <site/> <contact name="fsuzuki"/> <certifier name="snguyen"/> <location 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, seeMapping ConnectionType Names for more information.
Version
Version 3.5 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 401 | 401000 | Unauthorized access | No authorization credentials were provided. |
| 401 | 401002 | Unauthorized access | Invalid authorization credentials were provided. |
| 404 | 404000 | Resource not found | The site LUID in the URI doesn't correspond to an existing site. |
| 404 | 404031 | Database not found | The requested database could not be found. |
| 409 | 409045 | Database error | An unknown database asset error occurred. |
| 409 | 409046 | Unknown database query error | An unknown error occurred and the database query could not complete. |
Query Databases
Get information about all database assets for a site.
URI
GET api/api-version/sites/site-luid/databases
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID of the site asset. |
Request Body
None
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:databases:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response:
<tsResponse> <databases><pagination pageNumber="1" pageSize="100" totalAvailable="496"><database 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/><contact name="jsmith"/> <certifier name="snguyen"/> <location type="PROJECT"/> <tags/></database><database name="small.csv" connectionType="textscan" isEmbedded="true" isCertified="false" type="File" filePath="small.csv" contentPermissions="ManagedByOwner"><site/><contact name="fsuzuki"/> <tags/></database><database name="ows.json" connectionType="semistructpassivestore-direct" isEmbedded="true" isCertified="false" type="File" filePath="ows.json" contentPermissions="ManagedByOwner"><site/> <tags/></database><database 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/> <location type="PROJECT"/> <tags/></database><database name="911_calls_short.csv" connectionType="textscan" isEmbedded="true" isCertified="false" type="File" filePath="911_calls_short.csv" contentPermissions="ManagedByOwner"><site/> <tags/></database><database name="Prince.xlsx" connectionType="excel-direct" isEmbedded="true" isCertified="false" type="File" filePath="Prince.xlsx" contentPermissions="ManagedByOwner"><site/> <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, seeMapping ConnectionType Names for more information.
Version
Version 3.5 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 401 | 401000 | Unauthorized access | No authorization credentials were provided. |
| 401 | 401002 | Unauthorized access | Invalid authorization credentials were provided. |
| 404 | 404000 | Resource not found | The site LUID in the URI doesn't correspond to an existing site. |
| 404 | 404031 | Database not found | The requested databases could not be found. |
| 409 | 409045 | Database error | An unknown database asset error occurred. |
| 409 | 409046 | Unknown database query error | An unknown error occurred and the database query could not complete. |
Query Flow
Returns information about the specified flow, including information about the project, owner, and output steps.
Note: After you create a resource, the server updates its search index. If you make aquery 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 as3.27. For more information, seeREST 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 haveRead(view) permission for the flow (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flows:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 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, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 name="CoffeeChainOutputCSV"/> <flowOutputStep name="CoffeeChainOutputHyper"/> <flowOutputStep name="CoffeeChainOutputTDE"/> </flowOutputSteps> <flow name="SQLServerUserNamePassword Good" description="" webpageUrl="http://tpqawin01/#/flows/3" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z"> <project name="Default"/> <owner/> <tags/><parameters><parameter 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 as3.27. For more information, seeREST 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 haveRead(view) permission for the flow (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flow_connections:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse > <connections> <connection 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, seeREST 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 haveReadpermission. |
| 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 type="sqlserver" serverAddress="mySQLServer" userName="test" embedPassword="true"/> <connection type="tableau-server-site" serverAddress="http://testserver01" userName="" embedPassword="false"/> </connections></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 as3.27. For more information, seeREST 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, seeFiltering 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, seeFiltering 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
Note: Thefilter andsort 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).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flows:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="total-available"/> <flows> <flow name="flow-name" description="flow-description" webpageUrl="web-page-url" fileType="file-type" createdAt="datetime-created" updatedAt="datetime-updated"> <project name="project-name"/> <owner/> <tags/> <parameters> <parameter 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>Thedatetime-created anddatetime-updatedattribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.3 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 name="SQLServerUserNamePassword Good" description="" webpageUrl="http://tpqawin01/#/flows/3" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z"> <project name="Default"/> <owner/> <tags/> <parameters/> </flow> <flow 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 name="Default"/> <owner/> <tags/> <parameters><parameter type="string" name="String Param" description="String parameter test" value="string 2" isRequired="false"> <domain xsi:type="flowParameterListDomainType" domainType="all"></parameter> </parameters> </flow> <flow 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 name="Default"/> <owner/> <tags/> <parameters/> </flow> <flow 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 name="Default"/> <owner/> <tags> <parameters/> </flow> <flow 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 name="Default"/> <owner/> <tags/> <parameters/> </flow> <flow name="Flow1" description="" webpageUrl="http://tpqawin01/#/flows/40" fileType="tfl" createdAt="2018-11-07T00:38:48Z" updatedAt="2018-11-07T00:38:48Z"> <project name="Default"/> <owner/> </flow> <flow 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 name="Default"/> <owner/> <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 as3.27. For more information, seeREST 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, orfalseto return all flows that the specified user has at least read access to. The default isfalse. |
| 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 theisOwnerparameter istrue, users who are not server or site administrators see the flows that they own on the site. IfisOwnerparameter isfalse, users who are not server administrators see the flows that they haveRead(view) permissions for.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flows:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="total-available"/> <flows> <flow name="flow-name" description="flow-description" webpageUrl="URL" fileType="flow-file-type" createdAt="Datetime-created" updatedAt="Datetime-updated"> <project name="project-name"/> <owner/> <tags/> <parameters> <parameter 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>Thedatetime-created anddatetime-updatedattribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.3 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 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 name="Default"/> <owner/> </flow> <flow 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 name="Default"/> <owner/> <tags/> <parameters><parameter 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 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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
| filter-expression | (Optional) An expression that lets you specify a subset of groups to return. You can filter on predefined fields such asname. You caninclude multiple filter expressions. For more information, seeFiltering 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 theinformation that's returned is undefined. For more information, seeFiltering 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).
tableau:groups:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" /> <groups> <groupapi-placeholder">group-id" name="group-name"> <domain name="domain-for-group" /> </group> <groupapi-placeholder">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, thename attribute of the<domain> element contains the group's Active Directory domain. For a group thatuses local authentication, the value of that attribute islocal.
The response body for a local group that has enabledonLogin for its grant license mode will have animport element with a domain name oflocal. Local groups with grant license mode unset,have noimport element in their response.
Version
Version 2.0 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X GET -H "X-Tableau-Auth:e35Z608JMPHgZfVyJncnedlUeXSX8bmb"
Example response:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="3"/> <groups> <group name="All Users"> <domain name="local"/> </group> <group name="active-directory-group-import"> <domain name="MYDOMAIN.net"/> <import domainName="MYDOMAIN.net" siteRole="ExplorerCanPublish" grantLicenseMode="onLogin"/> </group> <group 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:
- Import users from Active Directory (the result of a call toCreate Group).
- Synchronize an existing Tableau Server group with Active Directory (the result of a call toUpdate Group).
- Run extract refresh tasks (the result of a call toRun Extract Refresh Task).
- Publish a workbook asynchronously (the result of a call toPublish Workbook).
- Run workbook or view subscriptions (the result of a call toCreate Subscription orUpdate Subscription)
- Run a flow task (the result of a call toRun Flow Task)
- Status of Tableau Server site deletion (the result of a call to asynchronousDelete Site(Link opens in a new window) beginning API 3.18)
Note: To query a site deletion job, the server administrator must be first signed into the default site (contentUrl=" ").
Version: Available in API 2.0 and later.
License: No additional license required.
Permissions: This method can only be called by server administrators and site administrators.
Access Scope:tableau:jobs:read
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
GET /api/api-version/sites/site-id/jobs/job-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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
Response Code
200
Response Body
<tsResponse> <jobapi-placeholder">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>ThecreatedAt,updatedAt, andCompletedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).
ThefinishCode indicates the status of the job.
- For most jobs, the
finishCodeindicates the status of the job:0for success,1for error, or2for canceled. - For bridge extract refresh jobs, a
finishCodeof0indicates that the bridge client is assigned to execute the job, while a3indicates that the job completed. - Forasynchronous workbook publishing jobs, progress will switch from
0when the job is in-progress to100when it is complete.finishCodewill switch from1when the job is in-progress to0when it is complete, and nostatusNoteselements are provided.
ThestatusNotes 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 thetype 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 orerrorCode=9 when a site can't be deleted. |
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 notGET. |
For more information, seeHandling 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 theQuery Job method. To cancel an active job, pass a job ID returned by this method to theCancel Job method.
Calls to this method can be filtered, as shown in the URI examples shown below. To learn more about filtering, seeFiltering and Sorting in the REST API.
Version: Available in API 3.1 and later.
License: No additional license required.
Permissions: This method can only be called by server administrators and site administrators.
Access Scope:tableau:jobs:read
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site where the job is running. |
Request Body
None
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="page-number" pageSize="page-size"/> <backgroundJobs> <backgroundJob status="status-value" createdAt="date-time" startedAt="date-time" endedAt="date-time" priority="priority-value" jobType="type-value"/><!-- . . . more backgroundJobs . . . --> </backgroundJobs></tsResponse>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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 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 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 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 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 aquery 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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
| filter-expression | (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such asname,ownerName, andparentProjectId. You caninclude multiple filter expressions. For more information, seeFiltering 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 theinformation that's returned is undefined. For more information, seeFiltering and Sorting. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can call this method only if they haveRead (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).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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" api-placeholder">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> <projectapi-placeholder">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, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example: Filter query by project ID
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?filter=parentProjectId:eq:711d4c5d-60b7-4f77-a9a6-bbf05021b6ec" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings><pagination pageNumber="1" pageSize="100" totalAvailable="1"/> <projects> <project name="TestNestProject" description="" createdAt="2018-11-15T17:14:45Z" updatedAt="2018-11-15T17:14:45Z" contentPermissions="LockedToProject" parentProjectId="711d4c5d-60b7-4f77-a9a6-bbf05021b6ec"> <owner/> </project> </projects></tsResponse>Example: Show all fields in the first ten query results
curl "https://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?pageSize=10&fields=_all_" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="1"/> <projects> <project 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 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 as3.27. For more information, seeREST 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:
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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response
<tsResponse> <dataQualityTriggerList><dataQualityTrigger 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, seeREST 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 aquery 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 thekey 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 as3.27. For more information, seeREST 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 parameterkey=name. |
| content-url | The URL of the site to get information for. If you specify a content URL, you must also include the parameterkey=contentUrl. |
| include-usage-flag | The boolean flag to include site usage metrics in the response body. Iftrue, then the site element of the response will contain ausage node with the attributesnumUsers (number of users) andstorage (storage in megabytes).To set the flag to include usage in the response, append |
Request Body
None
Permissions
This method can only be called by server administrators and site administrators.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:sites:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <siteapi-placeholder">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 present in the response body for Tableau Cloud starting from API version 3.19 (March 2023) and Tableau Server starting from API version 3.25 (Tableau Server 2025.1).
Version
Version 1.0 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
Command:
curl "http://MY-SERVER/api/3.27/sites/1234abcd-12ab-12ab-12ab-1234abcd1234?includeUsage=true" -X GET \-H "X-Tableau-Auth:ABCD1234abcdABCD|ABCD1234abcdABCDABCD1234abcd-1"Example response:
<tsResponse> <site 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.27/sites/Default?key=name" -X GET \-H "X-Tableau-Auth:ABCD1234abcdABCD|ABCD1234abcdABCDABCD1234abcd-1"Example response:
<tsResponse> <site 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 as3.27. For more information, seeREST 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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).
tableau:sites:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber"pageSize="page-size"totalAvailable="total-available" /> <sites><site 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 ="request-access-enabled-flag" runNowEnabled="run-now-enabled-flag" 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 siteid,name, andcontent-url attributes.
Version
Version 1.0 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites?pageSize=1&pageNumber=1" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"Example response:
<tsResponse> <pagination pageNumber="1" pageSize="1" totalAvailable="2"/> <sites> <site 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 as3.27. For more information, seeREST 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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:tables:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 name="[Orders$]" isEmbedded="true" isCertified="false"><site/> </tsResponse>Version
Version 3.5 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 401 | 401000 | Unauthorized access | No authorization credentials were provided. |
| 401 | 401002 | Unauthorized access | Invalid authorization credentials were provided. |
| 404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404032 | Table not found | The requested table could not be found. |
| 409 | 409052 | Unknown table error | An unknown table asset error occurred. |
| 409 | 409053 | Unknown table query error | An unknown error occurred and the table query could not complete. |
Query Tables
Get information about all table assets for a site.
URI
GET api/api-version/sites/site-id/tables
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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 throughData 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:tables:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 name="Culture" isEmbedded="false" isCertified="false"> <site/> </table><table name="[Orders$]" isEmbedded="true" isCertified="false"> <site/></table><table name="Batters" isEmbedded="false" isCertified="false"> <site/></table><table name="[911_calls_short#csv]" isEmbedded="false" isCertified="false"> <site/></table> </tables></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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 as3.27. For more information, seeREST 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 directlyor through the various ways that data is used throughout Tableau. Use of this methodby 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 theCreate Site orUpdate Site methods, you can change user visibility settings of a Site. For more information, seeManage 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).
tableau:users:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <userapi-placeholder">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" idpConfigurationId="idp-configuration-id" email="email-address" domain name="user-domain" /></tsResponse>Notes:
ThelastLogin attribute value is returned as a date in UTC format (YYYY-MM-DDTHH:MM:SSZ).
ThesiteRole value is returned as one of the followingvalues:Creator,Explorer,ExplorerCanPublish,ServerAdministrator,SiteAdministratorExplorer,SiteAdministratorCreator,Unlicensed,ReadOnly, orViewer.
TheexternalAuthUserId 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.
In Tableau Server version 9.0.1 or API version 2.0.1 and later - if SAML is enabled, and the user was imported from Active Directory, thename attribute of the<domain> element contains the user's Active Directory domain.
Starting in API 3.24,idpConfigurationId indicates the authentication configuration assigned to the user in Tableau Cloud only.
Starting in API 3.26 (July 2025),email indicates an email address that is different from the username.
Version
Version 2.0 and later. For more information, seeREST 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <user name="Alan" siteRole="ExplorerCanPublish" fullName="Alan Wang" authSetting="ServerDefault" lastLogin="2015-01-05T03:24:36Z"language="en-GB"locale="GB"idpConfigurationId="00000000-0000-0000-0000-0000000000" /></tsResponse>Query View Data
Returns a specified view rendered as data in comma separated value (CSV) format.
Version: Available in API 2.8 and later.
License: No additional license required.
Permissions:Tableau Server users who are not server administrators or site administrators can query workbook viewsonly if they haveRead (view) permission for the views (either explicitly or implicitly).
Access Scope:tableau:views:download
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 themaxAge parameter. Default age of data is 60 minutes.
For Tableau Cloud, concurrent requests to endpoints that start long-running jobs, including this one, are limited to20 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,seeFiltering 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 as3.27. For more information, seeREST 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, seeView filter queries. |
Request Body
None
cURL Request
curl "http://MY-SERVER/api/3.27/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/views/2474164d-8d37-4a4c-abc7-c2070fd25fd5/data?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
The response body contains view data in CSV format no more than 60 minutes old.
Month of Date,Year of Date,Above Median?,Avg. MedianJanuary,1893,below median,-1.0January,1864,below median,-0.9January,1861,below median,-0.9December,1862,below median,-0.9March,1917,below median,-0.8December,1892,below median,-0.8February,1862,below median,-0.8February,1911,below median,-0.8February,1917,below median,-0.8May,1861,below median,-0.8November,1862,below median,-0.8March,1898,below median,-0.8December,1860,below median,-0.8January,1862,below median,-0.7March,1850,below median,-0.7February,1893,below median,-0.7December,1870,below median,-0.7Errors
| 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 haveRead 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 notGET. |
| 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, seeHandling Errors.
Query View Image
Returns an image of the specified view.
Version: Available in API 2.5 and later.
License: No additional license required.
Permissions: Tableau Server users who are not server administrators or site administrators can query workbook views only if they haveRead (view) permission for the views (either explicitly or implicitly).
Access Scope:tableau:views:download
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 themaxAge parameter.
This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views,seeFiltering and Sorting in the REST API.
Note: If you want to disable this endpoint, use TSM to set thesheet_image.enabled setting to false. For more information, seetsm 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
Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later:
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?vizHeight=viz-height&vizWidth=viz-width
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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. |
| viz-height | Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later: (Optional) The height of the rendered pdf image in pixels that, along with the value of |
| viz-width | Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later: (Optional) The width of the rendered pdf image in pixels that, along with the value of |
| 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 tohigh 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, seeView filter queries. |
Request Body
None
Response Code
200
Response Body
The view's image in PNG format (MIME media typeimage/png).
cURL Request Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/image?resolution=high&maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
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 haveRead permission. |
| 403 | 403068 | Forbidden | The endpoint has been disabled on the server. To enable the endpoint, a server administrator must use tsm to configure thesheet_image.enabled setting. For more information, seetsm 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 notGET. |
For more information, seeHandling Errors.
Query View PDF
Returns a specified view rendered as a .pdf file.
Version: Available in API 2.8 and later.
License: No additional license required.
Permissions: Tableau Server users who are not server administrators or site administrators can query workbook viewsonly if they haveRead (view) permission for the views (either explicitly or implicitly).
Access Scope:tableau:views:download
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 themaxAge parameter.
This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views,seeFiltering 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=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 as3.27. For more information, seeREST 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, seeView filter queries. |
| viz-height | (Optional) The height of the rendered pdf image in pixels that, along with the value ofvizWidth, determines itsresolution and aspect ratio. |
| viz-width | (Optional) The width of the rendered pdf image in pixels that, along with the value ofvizHeight, determines itsresolution 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. |
| orientation | (Optional) The orientation of the pages in the .pdf file produced. The value can bePortraitorLandscape. If this parameter is not present the page orientation will default toPortrait. |
| page-type | (Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be: If this parameter is not present the page type will default to |
Request Body
None
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 haveContent-Type:application/pdf.
cURL Example
curl "http://MY-SERVER/api/3.27/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.
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 haveRead 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 notGET. |
For more information, seeHandling Errors.
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 as3.27. For more information, seeREST 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 haveRead (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).
tableau:views:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
The view's preview image in PNG format (MIME media typeimage/png).
Version
Version 1.0 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling 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.
Version: Available in API 2.2 and later.
License: No additional license required.
Permissions: For users who are not server administrators or site administrators, the method returns only the views that the user owns or hasRead permissions for (either explicitly or implicitly).
Access Scope:tableau:content:read
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 as2.2. For more information, seeREST 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 isfalse. |
| 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
| filter-expression | (Optional) Fields and operators that you can use to filter results. For more information, seeFilter expressions. |
| sort-expression | (Optional) Field and direction to sort results. For more information, seeSorting. |
| 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 caninclude multiple field expressions in a request. For more information, seeUsing Fields in the REST API. |
Note: Thefilter andsort parameters can be combined with each other and with paging parameters andfields parameters using an ampersand (&).
Request Body
None
cURL Request
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views" -X GET -H "X-Tableau-Auth:1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="1" pageSize="100" totalAvailable="2" /> <views> <view name="Economic Indicators" contentUrl="Finance/sheets/EconomicIndicators"> <workbook /> <owner /> </view> <view name="Investing in the Dow" contentUrl="Finance/sheets/InvestingintheDow"> <workbook /> <owner /> </view> </views></tsResponse>
{ "pagination": { "pageNumber": "1", "pageSize": "100", "totalAvailable": "2" }, "views": [ { "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" } }, { "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" } } ]}
The<usage> element is included in the response only if the method hasincludeUsageStatistics=true in the URI.
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 | TheincludeUsageStatistics was provided with a value other thantrue orfalse. |
| 403 | 403004 | Read forbidden | A non-administrator user attempted to query workbook views, but the caller doesn't haveRead 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 notGET. |
For more information, seeHandling Errors.
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 as3.27. For more information, seeREST 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 isfalse. |
Request Body
None
Permissions
Tableau Server users who are not server administrators or site administrators can query workbook views only if they haveRead (view) permission for the views (either explicitly or implicitly).
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <views> <viewapi-placeholder">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 hasincludeUsageStatistics=true in the URI.
Version
Version 1.0 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400008 | Invalid parameter value | TheincludeUsageStatistics was provided with a value other thantrue orfalse. |
| 403 | 403004 | Read forbidden | A non-administrator user attempted to query workbook views, but the caller doesn't haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/views" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <views> <view name="Tale of 100 Start-ups" contentUrl="Finance/sheets/Taleof100Start-ups"/> <view name="Economic Indicators" contentUrl="Finance/sheets/EconomicIndicators"/> <view 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 as3.27. For more information, seeREST 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 haveRead (view) permission for the workbook (either explicitly or implicitly).queryTaggingEnabled is returned only for administrator users.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <connections> <connectionapi-placeholder">connection-id" type="connection-type" serverAddress="server-address" serverPort="port" userName="connection-user-name" queryTaggingEnabled="query-tagging-enabled" authenticationType="authentication-type" useOAuthManagedKeychain="using-OAuth-managed-keychain-or-not /> < ... additional connections ... > </connections></tsResponse>Version
Version 2.0 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <connections> <connection type="dataengine" /> <connection type="dataengine" /> <connection type="dataengine" /> <connection type="dataengine" /> <connection 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, seeMapping ConnectionType Names for more information.
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 as3.27. For more information, seeREST 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 haveRead (view) permission for the workbook (either explicitly or implicitly) and also haveRead (view) permission for the view that is used as the preview image. If the user doesn't haveRead permissions to that view, the preview image for another view might be used. If the user doesn't haveRead 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).
tableau:workbooks:downloadFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
The workbook's preview image in PNG format (MIME media typeimage/png).
Version
Version 1.0 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 as3.27. For more information, seeREST 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 asname,tags, andcreatedAt. You can include multiple filter expressions. For more information, seeFiltering 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, seeFiltering 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 caninclude multiple field expressions in a request. For more information, seeUsing Fields in the REST API. |
Note: Thefilter andsort parameters can be combined with each other and with paging parameters andfields parameters using an ampersand (&).
Request Body
None
Permissions
Users who are not server administrators or site administrators can get workbooks that they haveRead (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).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="total-available" /> <workbooks> <workbookapi-placeholder">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" > <projectapi-placeholder">project-id" name="project-name" /> <ownerapi-placeholder">user-id" /> <tags> <tag label="tag"/> ... additional tags ... </tags><dataAccelerationConfig accelerationEnabled="accelerationEnabled" lastUpdatedAt="update-date-time" accelerationStatus="accelerationStatus" /> </workbook> ... additional workbooks ... </workbooks></tsResponse>Thedatetime-created anddatetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Response Attribute Values
| accelerationEnabled | true if data acceleration is enabled, otherwisefalse. For more information, seeData Acceleration.(Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. SeeView Acceleration(Link opens in a new window).) |
| accelerationStatus | The status can be:
|
Version
Version 2.3 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example: Get workbooks without filter
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="27"/> <workbooks> <workbookname="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 name="Tableau Samples"/> <owner/> <tags/> </workbook> <workbook 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 name="default"/> <owner/> <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.27/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 hasRead (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 as3.27. For more information, seeREST 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, orfalse to return all workbooks that the specified user has at least read access to. The default isfalse. |
| 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating 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 theisOwner parameter istrue,users who are not server or site administrators see the workbooks that they own on the site.IfisOwner parameter isfalse,users who are not server administrators see the workbooks that they haveRead (view) permissions for.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" /> <workbooks> <workbookapi-placeholder">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" > <projectapi-placeholder">project-id" name="project-name" /> <ownerapi-placeholder">user-id" /> <tags> <tag label="tag"/> ... additional tags ... </tags> </workbook> ... additional workbooks ...</tsResponse>Thedatetime-created anddatetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 1.0 and later. For more information, seeREST 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 haveRead 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 notGET. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/workbooks" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="2"/> <workbooks> <workbook 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 name="Tableau Samples"/> <owner/> <tags></tags> </workbook> <workbook 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 name="default"/> <owner/> <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, seeExtract 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site. |
Request Body
None
Permissions
Tableau Server administrators can call this method.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:extract_encryption:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
None
Version
Version 3.5 and later. For more information, seeREST 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 notPOST. |
For more information, seeHandling 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 Server site or Tableau Cloud site and EAS using the OAuth 2.0 standard protocol. By establishing a trust relationship, you’re able to provide your users with a single sign-on (SSO) experience to Tableau content embedded in your custom applications or REST API authorization through an identity provider (IdP) you've already configured.
Notes:
- Beginning in API version 3.22, you can register multiple EASs per site for Tableau Cloud.
- Beginning in API version 3.23, Tableau Server supports site-level EAS (and multiple registrations of EASs per site).
For more information, see one of the following:
- For Tableau Server:Register EAS to Enable SSO for Embedded Content(Link opens in a new window)
- For Tableau Cloud:Register EAS to Enable SSO for Embedded Content
URI
POST api/api-version/sites/site-id/connected-apps/external-authorization-servers
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
Request Body
<tsRequest> <externalAuthorizationServerissuerUrl="URL" jwksUri="URI" name="name"/></tsRequest>Attribute Values
A combination of attributes inside the<externalAuthorizationServer> element is valid, howeverissuerUrl is required.
| URL | The entity id of your identity provider (IdP) or URL that uniquely identifies your IdP. |
| URI | (Optional) The JSON Web Key (JKWS) of the EAS. |
| name | (Optional) The name of the connected app. If the name attribute is not specified, the connected app name defaults to "External Authorization Server." This attribute is available starting from API version 3.22 (February 2024). |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:external_authorization_servers:createFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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>) inUpdate EAS andDelete 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). Introduced in Tableau Server 2024.1 (API 3.23).
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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:columns:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.5 and later. For more information, seeREST 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) and later.Version Overview
Permissions: This method can be called by users that have permissions to the specified workbook.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
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 usingDownload Data Source Revision. If you callGet Data Source Revisions, the revision that's been removed is listed with the attributeIsDeleted="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 as3.27. For more information, seeREST 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, callGet 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 ofExplorerCanPublish.
- Read (view),Write (save), andDownload (save as) permissions for the specified data source.
- Save (write) permissions for the project that contains the data source.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:datasources:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.3 and later. For more information, seeREST 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, callDelete 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 notDELETE. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:databases:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.5 and later. For more information, seeREST 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 (Tableau Cloud February 2024 / Server 2024.2) 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
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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.27/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’tDELETE. |
| 409 | 409120 | Group set not found | The group set ID in the URI doesn't correspond to an existing user. |
For more information, seeHandling 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.
URI
PUT /api/api-version/sites/site-luid/disable-site-oidc-configuration?idpConfigurationId=idp-configuration-id
Note: The resource, PUT /api/api-version/sites/site-luid/disable-site-oidc-configuration?idpConfigurationId=idpConfigurationId, was added in version 3.24. The original resource, PUT /api/api-version/sites/site-luid/disable-site-oidc-configuration, continues to be a supported resource if your site is configured with only one OIDC authentication configuration. If you don’t specify anidpConfigurationId value starting in API 3.24, the initial (default) OIDC configuration on the site is removed. If there is no initial OIDC configuration on the site, then no OIDC configuration is removed.
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| idp-configuration-id | The ID of the configuration. To get theidpConfigurationId value, use theList Authentication Configurations for Site method. |
Request Body
None
cURL Request Example
curl "https://us-west-2a.online.tableau.com/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/disable-site-oidc-configuration?idpConfigurationId=b2207590-024c-4a6e-ac4a-eca6eefabb2e" -X PUT -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, seeHandling 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:tables:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.5 and later. For more information, seeREST 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 as3.27. For more information, seeREST 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><userapi-placeholder">user-id1" /><userapi-placeholder">user-id2" /><userapi-placeholder">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 callingGet 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).
tableau:groups:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
Example
Remove a single user from a group
curl "http://MY-SERVER/api/3.27/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.27/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 /><user /> </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: tableau:identity_pools_users:delete
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(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 as3.27. For more information, seeREST 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 theList 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.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/7ad8f89e-c2a1-44b4-9413-ac8a62286a7a/identityPool/" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
MY-SERVERis the name or IP address of your server.9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4dis the ID of the site, as returned by a previous call toSign In.7ad8f89e-c2a1-44b4-9413-ac8a62286a7ais the ID of the user to remove.df47cf24-5ed3-11ed-9b6a-0242ac12000is the ID of the identity pool.12ab34cd56ef78ab90cd12ef34ab56cdis the credentials token returned by a previous call toSign 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, seeREST 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 notDELETE. |
| 429 | 429003 | Can't remove user | There was a problem and the user couldn't be removed from the identity pool. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 nomapAssetsTo is provided, the value of the owner is changed tounknown user. If a user owns only subscriptions, you can delete them from either server or site without having to setmapAssetsTo 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 themapAssetsTo 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).
tableau:users:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, seeREST 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 notDELETE. |
| 409 | 409003 | User asset conflict | The specified user still owns content on Tableau Server and cannot be deleted. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 usingDownload Workbook Revision. If you callGet Workbook Revisions, the revision that's been removed is listed with the attributeIsDeleted="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 as3.27. For more information, seeREST 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, callGet 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 ofExplorerCanPublish.
- Read (view),Write (save), andDownload (save as) permissions for the specified workbook.
- Save (write) permissions for the project that contains the workbook.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:workbooks:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 2.0 and later. For more information, seeREST 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, callDelete 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 notDELETE. |
For more information, seeHandling Errors.
Replace Content Permissions
Replaces existing permissions in the specified content. You can specify multiple sets of permissions using one call.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License: No additional license required
Permissions:Users who are not server administrators or site administrators can add permissions only to content for which they haveChangePermissions permission. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:permissions:update For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/datasources/datasource-luid/permissions
POST /api/api-version/sites/site-luid/flows/flow-luid/permissions
POST /api/api-version/sites/site-luid/projects/project-luid/permissions
POST /api/api-version/sites/site-luid/views/view-luid/permissions
POST /api/api-version/sites/site-luid/workbooks/workbook-luid/permissions
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| datasourc-luid | The LUID for the data source. |
| flow-luid | The LUID for the flow. |
| project-luid | The LUID for the project. |
| view-luid | The LUID for the view. |
| workbook-luid | The LUID for the workbook. (Optional, but can be included for compatibility with older versions.) |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user />
<capabilities>
<capability name="AddComment" mode="Allow" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group />
<capabilities>
<capability name="ViewComments" mode="Allow" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<!-- ... additional grantee capability sets ... -->
</permissions>
</tsRequest>{
"permissions": {
"granteeCapabilities": [
{
"user": {
"@id": "user-luid"
},
"capabilities": {
"capability": {
"@name": "capability-name",
"@mode": "capability-mode"
},
"#text": "... additional capabilities ..."
}
},
{
"group": {
"@id": "group-luid"
},
"capabilities": {
"capability": {
"@name": "capability-name",
"@mode": "capability-mode"
},
"#text": "... additional capabilities ..."
}
}
],
"#text": "... additional grantee capability sets ..."
}
}Request Attributes
| 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, theworkbook-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. |
cURL Request Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @replace-view-permissions.xml
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. |
| 400 | 400009 | Invalid capability | The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook areAddComment,ChangeHierarchy,ChangePermissions,CreateRefreshMetrics,Delete,ExportData,ExportImage,ExportXml,Filter,Read (view),RunExplainData,ShareView,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. |
| 403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the workbook. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | A user ID in the request body doesn't correspond to an existing user. |
| 404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
| 404 | 404005 | Project not found | The project ID in the URI doesn't correspond to an existing project. |
| 404 | 404006 | Workbook not found | The workbook ID in the URI doesn't correspond to an existing workbook. |
| 404 | 404011 | View not found | The view ID in the ID doesn't correspond to an existing view. |
| 404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
| 404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other thanAllow orDeny for any mode value. |
| 404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
| 405 | 405000 | Invalid request method | The request type was notPOST. |
For more information, seeHandling Errors.
Replace Project's Default Permissions
Replaces default permissions in the specified content. If Tableau Catalog is enabled, it also adds default permission rules for database or table resources in a project. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions arelocked 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, seePermissions(Link opens in a new window).
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: Users who are not server administrators, project owners, or project leaders can replace permissions defaults for a project only if they have effectiveChangePermissions permission. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:permissions:update
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables
POST /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| project-luid | The LUID for the project. |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user />
<capabilities>
<capability name="AddComment" mode="Allow" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group />
<capabilities>
<capability name="ViewComments" mode="Allow" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<!-- ... additional grantee capability sets ... -->
</permissions>
</tsRequest>{
"permissions": [
{
"user": {
"id": "user-luid"
},
"capabilities": [
{
"name": "capability-name",
"mode": "capability-mode"
}
]
},
{
"group": {
"id": "group-luid"
},
"capabilities": [
{
"name": "capability-name",
"mode": "capability-mode"
}
]
}
]
}Request Attributes
| 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 areAddComment,ChangeHierarchy,ChangePermissions,Delete,ExportData,ExportImage,ExportXml,Filter,Read (view),RunExplainData,ShareView,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. Valid capabilities for a data source areChangePermissions,Connect,Delete,ExportXml,SaveAs,Read (view), andWrite. For more information, seePermissions. |
cURL Request Example
curl --location "http://MY-SERVER/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/default-permissions/dataroles" --header "Content-Type: application/xml" --data @replace-default-permissions-workbook.xml
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. |
| 400 | 400009 | Invalid capability | The capability in the URI is invalid for a data source. Valid capabilities for a workbook areAddComment,ChangeHierarchy,ChangePermissions,Delete,ExportData,ExportImage,ExportXml,Filter,Read (view),RunExplainData,ShareView,ViewComments,ViewUnderlyingData,WebAuthoring, andWrite. Valid capabilities for a data source areChangePermissions,Connect,Delete,ExportXml,Read (view), andWrite. For detailed information about capabilities for each content type, seeCapabilities. |
| 400 | 400042 | Malformed permissions qualifier | The request body includes a<workbook> or<datasource> element. |
| 403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to add permissions on the project. |
| 404 | 404000 | Site not found | The site LUID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | A user LUID in the request body as the grantee doesn't correspond to an existing user. |
| 404 | 404005 | Project not found | The project LUID in the URI doesn't correspond to an existing project. |
| 404 | 404009 | Project ID mismatch | A project LUID specified in the URI doesn’t match the project ID specified in the request body. (You don’t have to specify a project ID in the request body.) |
| 404 | 404012 | Group not found | A group LUID in the request body doesn't correspond to an existing group. |
| 404 | 404013 | Capability not found | The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other thanAllow orDeny for any mode value. |
| 405 | 405000 | Invalid request method | The request type wasn’tPOST. |
For more information, seeHandling Errors.
Revoke Administrator Personal Access Tokens
Revokes allpersonal 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 as3.27. For more information, seeREST API and Resource Versions. |
Request Body
None
Permissions
Only Tableau Server users with server administrator permissions can use this method.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:server_admin_tokens:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 3.11 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling 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.
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 as3.27. For more information, seeREST 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.27/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:
|
For more information, seeHandling 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 theRunNow setting for the site. For more information, seeTableau 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 theCreate Schedule method to create the task. To get information about the extract refresh task, use theGet Extract Refresh Tasks method, which returns theextractRefresh ID that you use as thetask-id.
Note: This method doesn't work for scheduled tasks associated with virtual connection extracts.
The method adds the refresh task to the backgrounder queue. Depending upon the backgrounder load, the task might not run immediately. The method returns information about the backgrounder job responsible for running the extract refresh task, including ajob id that can be used with theQuery 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 as3.27. For more information, seeREST 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
Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
tableau:tasks:run (this scope is included in the scope:tableau:tasks)
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 mode="MODE" type="RefreshExtract" /></tsResponse>Version
Version 2.6 and later. For more information, seeREST API and Resource Versions.
Errors
| 403 | 403004 | Operation unauthorized | The user is not authorized to get the task, or the extract isn't associated with a workbook or published data source. |
| 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 notPOST. |
| 409 | 409093 | Operation already in Queue | The extract refresh job is already in the queue. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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:
<tsResponseversion-and-namespace-settings> <job 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 theList 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 selectingRun 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 haveData Management. For more information, seeTableau Prep Conductor(Link opens in a new window).
- This method will fail and result in an error if your Server Administrator has disabled theRunNow setting for the site. For more information, seeTableau 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 as3.27. For more information, seeREST 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 api-placeholder">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 api-placeholder">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 theList 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 theList 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, seeRun flows with parameters. |
| overrideValue | The run-time value for the flow parameter. You must specify this if the parameter is required. Use theList 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, seeRun flows with parameters. |
Note: You must specify theflow-id value in the URI. If you are using a request body to specify the attributes, you must also include theflow-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 withintheir scope. Users with a creator or explorer license that have been granted permissions by an administrator, leader or owner for aflow may also run it.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flows:runFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <job mode="Asynchronous" type="RunFlow" createdAt="DateTime-CreatedAt"> <runFlowJobType flowRunId="flow-run-id"> <flow name="flow-name"/> </runFlowJobType> </job></tsResponse>Version
Version 3.3 and later. For more information, seeREST 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 theAllow 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 notPOST. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/flows/ d00700fe-28a0-4ece-a7af-5543ddf38a82/run?flowRunMode=incremental" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings> <job mode="Asynchronous" type="RunFlow" createdAt="2018-11-12T19:14:08Z"> <runFlowJobType flowRunId="34b9f6d3-222a-2f2f-6a22-dd2f228a6ff2"> <flow 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, seeTableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled theRunNow setting for the site. For more information, seeTableau 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 theCreate 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 theQuery 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 code403102, 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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flow_tasks:runFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse > <job mode="Asynchronous" type="RunFlow" createdAt="Datetime-CreatedAt"> <runFlowJobType flowRunId="flow-run-id"> <flow name="flow-name"/> </runFlowJobType> </job></tsResponse>Version
Version 3.3 and later. For more information, seeREST 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, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/runFlow/9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c/runNow" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponse version-and-namespace-settings> <job mode="Asynchronous" type="RunFlow" createdAt="2018-11-12T19:43:00Z"> <runFlowJobType flowRunId="34b9f6d3-222a-2f2f-6a22-dd2f228a6ff2"> <flow 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, seeschedule linked tasks.
Version: Available in API 3.15 and later.
License: Data Management required. For more information, seeTableau Prep Conductor.
TheRunNow setting for the site must be enabled by a site administrator for run linked tasks requests to succeed. For more information, seeTableau Server Settings(Link opens in a new window).
Permissions: Tableau server administrators, site administrators, and project leaders can run linked tasks withintheir scope. Tableau users can run a linked task if they own the task or have permissions to run all the flows included in the linked task.
Access Scope: tableau:linked_tasks:run
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-id/tasks/linked/linked-task-id/runNow
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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
cURL Example
curl "http://MY-SERVER/api/3.27/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/tasks/linked/d00700fe-28a0-4ece-a7af-5543ddf38a82/runNow -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<tsResponse> <linkedTaskJob linkedTaskId="cde24429-6217-48e5-8ff5-f5dcd6a7006b" status="InProgress" createdAt="2022-02-15T00:22:22Z"/></tsResponse>.
{ "linkedTaskJob": {"id": "765dfdfc-26ec-47ea-b53b-54419c8f6b61","linkedTaskId": "cde24429-6217-48e5-8ff5-f5dcd6a7006b","status": "InProgress","createdAt": "2022-02-15T00:22:22Z"}}
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 notPOST. |
| 409 | 409082 | Run now forbidden | Run now setting has been disabled. |
For more information, seeHandling Errors.
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 |
Request Body
None
Permissions
This method can be called by all users and does not require authentication.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:server:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 405 | 405000 | Invalid request method | Request type was notGET. |
For more information, seeHandling Errors.
Set Custom View as Default for Users
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.
Version:Available in 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| custom-view-luid | The LUID for the custom view being updated. |
Request Body
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 '<tsRequest><users><user /></users></tsRequest>'Response Code
200
Response Body
<tsResponse>
<customViewAsUserDefaultResults>
<customViewAsUserDefaultViewResult success="true">
<user/>
</customViewAsUserDefaultViewResult>
</customViewAsUserDefaultResults>
</tsResponse>{
"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, seeHandling 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. For more information about authentication, seeSigning 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 HTTP403 (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.
Tableau Server
Typically, a credentials token is valid for 240 minutes. With administrator permissions on Tableau Server, you can change this timeout by using thetsm configuration set(Link opens in a new window)command and setting thewgserver.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.
Tableau Cloud
A credentials token is valid for 120 minutes on 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 prod-ca-a or us-east-1. For example, the URI to sign in to a site in the 10ay pod would be:https://prod-ca-a.online.tableau.com/api/api-version/auth/signin. For more information, seeAbout the pod name.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
Request Body
PAT
Signing in with a user's personal access token (PAT):
- For Tableau Server, seepersonal access token(Link opens in a new window).
- For Tableau Cloud, seepersonal access token(Link opens in a new window).
<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 (Tableau Server only):
<tsRequest> <credentials name="username" password="password" ><site contentUrl="content-url" /><userapi-placeholder">user-to-impersonate" /> </credentials></tsRequest>Impersonating user using PAT
Signing in with server administrator'spersonal access token(Link opens in a new window) (PAT) to impersonate a user (Tableau Server only):
<tsRequest> <credentials personalAccessTokenName="personal-access-token-name" personalAccessTokenSecret="personal-access-token-secret" > <site contentUrl="content-url" /> <userapi-placeholder">user-to-impersonate" /> </credentials></tsRequest>Connected apps JWT
Signing in with a JSON Web Token (JWT), from aconnected app(Link opens in a new window) (added 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 methodsthe connected app can access. You can find the scope for a JWT-supported method in a method's properties block or references details under theAccess 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 inREST API methods that support JWT authorization(Link opens in a new window) (Tableau Cloud Help) orREST 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.
About connected app errors
If you encounter issues with signing in with a JWT, the response body is appended with an additional error code that you can reference inTroubleshoot scopes(Link opens in a new window) (Tableau Cloud Help) orTroubleshoot 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>
Unified access tokens JWT
Signing in with a JSON Web Token (JWT) using a unified access token (added in Tableau Cloud December 2025 (API 3.27)):
XML
<tsRequest> <credentials jwt="json-web-token"isUat="true" <site contentUrl="content-url" /> </credentials></tsRequest>JSON
{"credentials": {"jwt": "json-web-token","isUat": is-uat,"site": {"contentUrl": ""}}}When a JWT sign-in is used, the JWT must be configured with the scopes for the REST API capabilities that should be available to the unified access token (UAT). You can find the scope for a JWT-supported method in a method's properties block. The properties block shows the scope declaration to use in the JWT that calls that method. If a scope is not listed in the method's properties block, access to that method can't be limited by a JWT.
For more information about UATs, seeUnified Access Tokens(Link opens in a new window) in the Tableau Cloud Manager REST API Help.
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 usercreates 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) associated with a Tableau connected app or unified access token (Tableau Cloud only). Tableau connected apps JWT: If using Tableau connected apps, the JWT uses a shared secret provided by the Tableauconnected 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 includeaccess scopes(Link opens in a new window)that determine which REST methods the external app can call. Unified access tokens: Starting in December 2025, if using unified access tokens (UATs), the JWT uses a shared secret as part of the UAT configuration. Added in API 3.27, Tableau Cloud only. |
| is-uat | Enables JWT authorization using a unified access token (UAT) when set totrue. Added in API 3.27, Tableau Cloud only. |
| 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.
For Tableau Server, to specify the default site, omit For Tableau Cloud, a sign-in request must have a |
| 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" > <siteapi-placeholder">site-id" contentUrl="content-url" /> <userapi-placeholder">user-id-of-signed-in-user" </credentials></tsResponse>AnestimatedTimeToExpiration value is returned when you sign in using a PAT. The value represents the approximate timeuntil the token returned from the PAT sign in will expire and need to be refreshed. The estimated time is based on regular usage of thetoken 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, seeREST 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 notPOST. 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, seeHandling Errors.
Example
curl "https://MY-SERVER/api/3.27/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:
<tsResponseversion-and-namespace-settings> <credentials token="HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3"> <site 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 toSign 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, seeJWT.
URI
POST /api/api-version/auth/signout
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
Request Body
None
Permissions
Any user can call this method.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:*:*For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 405 | 405000 | Invalid request method | Request type was notPOST. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 thetsm 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 as3.27. For more information, seeREST 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.
For Tableau Server, to specify the default site, omit For Tableau Cloud, a sign-in request must have a |
Permissions
Tableau Server users who are not server administrators can switch sites, provided that they have access to the destination site.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:sites:switchFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <credentials token="authentication-token" > <siteapi-placeholder">site-id" contentUrl="content-url" /> <userapi-placeholder">user-id-of-signed-in-user" /> </credentials></tsResponse>Version
Version 2.6 and later. For more information, seeREST 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 notPOST. |
For more information, seeHandling Errors.
Example
curl "https://MY-SERVER/api/3.27/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:
<tsResponseversion-and-namespace-settings> <credentials token="HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3"> <site 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:webhooks:testFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 withTableau 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}
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 as3.27. For more information, seeREST 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:recommendation_dismissals:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, seeREST 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 notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 is204.
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. Iftrue (default), the newly created webhook is enabled. Iffalse then the webhook will be disabled. |
| reason-for-disablement | The reason a webhook is disabled.
|
Permissions
This method can only be called by server and site administrators.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:webhooks:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <webhook 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 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, seeHandling Errors.
Response Headers
Location: /api/3.27/sites/site-id/webhooks/new-webhook-idUpdate 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) and later.Version Overview
Permissions: Can only be called by users with site or 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/site/extensions/analytics/connections/{connection_luid}
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 to the specified workbook.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
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.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}
Update Cloud Extract Refresh Task
Updates a custom schedule for an extract refresh task on Tableau Cloud.
For Tableau Server, seeUpdate 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:tasks:update
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-luid/tasks/extractRefreshes/task-luid
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| task-luid | The LUID of the extract refresh task. UseGet extract refresh tasks on site to find tasks by name. |
Request Body
<tsRequest>
<extractRefresh type="FullRefresh">
<workbook />
</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>{
"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 areoptional to update a custom schedule for a subscription.
extractRefresh type | enumeration: The type of extract refresh being scheduled. Valid values include:
| ||||||||||
workbook idor 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:
| ||||||||||
frequencyDetails start | time: If the schedule frequency isDaily, Weekly, or Monthly, thenstart is the time of day onwhich scheduled jobs should run. If the frequency isHourly, thenstart is the beginning of thetime range during which jobs should be started. The valid format isHH:MM:SS. | ||||||||||
frequencyDetails end | time: If the schedule frequency is | ||||||||||
interval{interval type} | string: Defines when and how often a scheduled job executes within the time parameters set in thestart andend values of thefrequencyDetails of theschedule. The type and valid values foran interval expression depend on the declaredfrequency of theschedule as follows:
|
cURL Request Example
curl --location --request POST "qa-near.tsi.lan/api/3.27/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
<tsResponse>
<extractRefresh
id="13237fd-6365-44d5-925b-644e5281b605"
consecutiveFailedCount="0"
type="IncrementalRefresh" >
<datasource />
</extractRefresh>
<schedule
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>{
"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 betweenstart andend times are not increments of one hour,this error will result. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:columns:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 name="StateProvinceID" description="Validated against maps" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219"><site/> </column></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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: Theconnected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| client-id | The unique ID of the connected app. |
Request Body
For Tableau Cloud and Tableau Server using API 3.23 or later
<tsRequest> <connectedApplicationname="name"enabled="enabled"domainSafelist="domainSafelist"unrestrictedEmbedding="unrestrictedEmbedding"><projectIds><projectId>project_id</projectId><projectId>project_id</projectId><projectId>project_id</projectId></projectIds> </connectedApplication></tsRequest>For Tableau Server (or Tableau Cloud) using API 3.21 or earlier
<tsRequest> <connectedApplicationname="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, seeQuery Projects. You can specify one project, multiple projects, and all projects on a site.
Note: The stand-aloneprojectId attribute will be retired in a future release so we recommend usingprojectIds 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 inDomain allowlist rules(Link opens in a new window) in the Tableau Server Help orDomain allowlist rules(Link opens in a new window) in the Tableau Cloud Help. Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. For example: |
| 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:connected_apps_direct_trust:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeQuery Connected App Secret.
- When the scope of the connected app's access is set to all projects, the request does not return the
projectIdattribute.
Version
Version 3.14 and later. For more information, seeREST API and Resource Versions.
The resource, PUT api/api-version/sites/site-id/connected-apps/direct-trust/client-id, was added in version 3.17. The original resource, PUT api/api-version/sites/site-id/connected-applications/client-id, was deprecated in API 3.17 and will be retired in a future release.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400109 | Bad request | The request body can't be empty. |
| 400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
| 403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
| 404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404041 | Connected app not found | The requested connected app could not be found. |
Update custom domain settings
Updates the custom domain setup for a Tableau site.
Version: Available in API 3.26 (Tableau Cloud June 2025) and later. Not available for Tableau Server.Versioning OverviewVersion Overview
Permissions: Only users with administrator permissions can update a site's custom domain settings.Permissions OverviewPermissions Overview
License: No additional license required.
Access Scope: Not available.
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
PUT {server}/api/-/customdomains/settings/site/{site_luid}
Update Custom View
Changes the owner or name of an existing custom view.
Version:Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1).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 attributesof any custom view that they own. Permissions Overview
JWT Access Scope:tableau:views:update
- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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 /> </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. |
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
<tsResponse> <customView name="new-name_2514e471-95ed-4d22-92c0-da648c23891b" createdAt="2016-02-03T23:35:09Z" updatedAt="2022-10-21T04:41:27Z" lastAccessedAt="2022-10-21T04:43:55Z" shared="false"> <view name="circle"/> <workbook name="my workbook"/> <owner name="workgroupuser"/> </customView></tsResponse>{ "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", "lastAccessedAt": "2022-10-21T04:43:55Z", "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 orRead 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, seeHandling 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 withTableau 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) 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/dashboard
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 withTableau 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
Update Data in Hyper Connection
Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from alive-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 theUpdate Data in Hyper Data Source method without specifying theconnection-id.
A request for this method must include an upload-session-id for a Hyper file payload containing an upload of the mostcurrent data from the data source for your published live-to-Hyper data. UseInitiate File Upload(Link opens in a new window) andAppend to File Upload(Link opens in a new window) methodsto form the payload and acquire upload-session-id.
For details and examples, seeUpdate Data in PublishedLive-to-Hyper Data Sources.
Note:While Hyper Update REST API methods make incremental changes much more efficient, multiple simultaneous update requests and largechanges in large datasets can overwhelm Tableau server background processes. To mitigate this issue, Hyper Update requests arelimited by the server configuration settingapi.server.update_uploaded_file.max_size_in_mb. Starting inTableau 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, andfine tunemax_size_in_mb value to optimize performance for your exact conditions.
URI
PATCH /api/api-version/sites/site-id/datasources/datasource-id/connections/connection-id/data?uploadSessionId=upload-session-id
Parameter Values
| api-version | The version of the API to use, such as3.27.For more information, seeREST 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 requestwith the same ID within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be usedto 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 multipleschemas 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 requiredunless 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 forinsert,upsert, anddelete)A declaration that defines acomparison operation between source and target data or between source or target data and a user provided constant.For details and examples, seeUpdate Data in PublishedLive-to-Hyper Data Sources. |
Anaction is an operation to be performed on specified target data. Multiple different actions can bedefined 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-tablein your published Hyper. A simplified example is:{"action": "insert", "source-table": "added_users", "target-table": "current_users"}update– Updates existing tuples from a namedsource-tablein your data source into a namedtarget-tablein 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 thetarget-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 atarget-tableand inserts all data from asource-tablewith 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, seeUpdate Data in Published Live-to-Hyper Data Sources.
Permissions
The user calling this method must be the data source owner and must have the overwrite permission on it.
Request Header
In addition to the typical authentication token, the following fields must be specified as part of the request header:
content-type: application/json- This endpoint accepts JSON only.RequestID- A user-generated identifier that uniquely identifies a request. If the server receives more than onerequest 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 causedby network anomalies or client crashes.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:hyper_data:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 theaction batch. This returned "job-id" can be used toquery the status of the update job(Link opens in a new window) or tocancel a scheduled job(Link opens in a new window).
(job-id: "scheduled-job-luid"}Version
Version 2o21.2 and later. For more information, seeREST 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 usingUpdate 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 haveWrite 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 mustbe 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 notPATCH. |
| 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, seeHandling Errors.
Update Data in Hyper Data Source
Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from alive-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 theUpdate 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 mostcurrent data from the data source for your published live-to-Hyper data. UseInitiate File Upload(Link opens in a new window) andAppend to File Upload(Link opens in a new window) methodsto form the payload and acquire upload-session-id.
For details and examples, seeUpdate Data in PublishedLive-to-Hyper Data Sources.
Note:While Hyper Update REST API methods make incremental changes much more efficient, multiple simultaneous update requests and largechanges in large datasets can overwhelm Tableau server background processes. To mitigate this issue, Hyper Update requests arelimited by the server configuration settingapi.server.update_uploaded_file.max_size_in_mb. Starting inTableau 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, andfine tunemax_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 notconverted 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 as3.27.For more information, seeREST 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 requestwith the same ID within 24 hours, all subsequent requests will be treated as duplicates and ignored by the server. This can be usedto 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 multipleschemas 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 requiredunless 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 forinsert,upsert, anddelete)A declaration that defines acomparison operation between source and target data or between source or target data and a user provided constant.For details and examples, seeUpdate Data in PublishedLive-to-Hyper Data Sources. |
Anaction is an operation to be performed on specified target data. Multiple different actions can bedefined 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-tablein your published Hyper. A simplified example is:{"action": "insert", "source-table": "added_users", "target-table": "current_users"}update– Updates existing tuples from a namedsource-tablein your data source into a namedtarget-tablein 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 thetarget-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 atarget-tableand inserts all data from asource-tablewith 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, seeUpdate Data in Published Live-to-Hyper Data Sources.
Permissions
The user calling this method must be the data source owner and must have the overwrite permission on it.
Request Header
In addition to the typical authentication token, the following fields must be specified as part of the request header:
content-type: application/json- This endpoint accepts JSON only.RequestID- A user-generated identifier that uniquely identifies a request. If the server receives more than onerequest 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 causedby network anomalies or client crashes.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:hyper_data:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 theaction batch. This returned "job-id" can be used toquery the status of the update job(Link opens in a new window) or tocancel a scheduled job(Link opens in a new window).
(job-id: "scheduled-job-luid"}Version
Version 2o21.2 and later. For more information, seeREST 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 usingUpdate 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 haveWrite 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 mustbe 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 notPATCH. |
| 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, seeHandling Errors.
Update Data Quality Warning
Update the warning type, status, and message of a data quality warning.
Note: Data quality warnings and certifications can be more generally managed through the newerLabels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try theUpdate Label method instead.
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 as3.27. For more information, seeREST 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:
Note: In Tableau Server 2023.1 and earlier,SENSITIVE_DATA is another type of data quality warning. Starting in Tableau Cloud June 2023 and Tableau Server 2023.3, it's a sensitivity label instead. These values are not case sensitive. |
| status | (Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default. |
| message | (Optional. Was required in Tableau Server 2023.3 and earlier.) A custom message to accompany the data quality warning. |
| severity | (Optional) Enables high visibility for the data quality warning when set to "true". Values can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in theServer Help orCloud Help. |
Permissions
If Tableau Server or Tableau Cloud is licensed throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response:
<tsResponse> <dataQualityWarning 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 /><owner /> </dataQualityWarning></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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 2.0 and later.
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 usersdepending on the type of update action and the permissions granted to the user.
Users who are not server administrators can move a data source from one project to another if they own the data source orthe current (source) project, or are a project leader for the current project, and they haveWrite 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 Creatoror higher and access to the data source with the overwrite capability.
Access Scope:tableau:datasources:update
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-id/datasources/datasource-id
Note: Starting in 2021.2, you can also modify (insert, update, upsert, replace, and delete) data in a published data source that is alive-to-Hyper connection. To do this, use theUpdate Data in Hyper Data Source method,or for data sources with multiple connections, use theUpdate Data in Hyper Connectionmethod. For more information, seeUpdateData in Published Live-to-Hyper Data Sources.
Path Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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/> <owner/> <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, seeUse 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 orfalse to not encrypt extracts. For more information, seeExtract 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 If |
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 nestedelements are included, no update is made.
If the<project> element is included, theidattribute must be included, and any other attributes of the<project> element are ignored.
If the<owner> element is included, theid attribute must be included, and any otherattributes of theowner are ignored.
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" 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 /> <owner /> <job /> <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]" } }}ThecreatedAt andupdatedAtattribute 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'thaveWrite permission for the project. |
| 403 | 403032 | Update forbidden | A non-administrator user tried to update a data source, but the caller doesn't haveWrite 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 correspondto an existing project. |
| 405 | 405000 | Invalid request method | Request type was notPUT orPATCH. |
| 409 | 409015 | Data source name conflict | The data source name in the request already belongsto the specified site. For the purpose of uniqueness checks, data source names are case-insensitive. |
For more information, seeHandling Errors.
Update Data Source Connection
Updates the server address, port, authentication type, username, or password for the specified data source connection.
If the data source contains multiple connections, all the connections are updated. To update specific connections in a data source containing multiple connections, seeUpdate Data Source Connections(Link opens in a new window).
Version: Available in API 2.3 and later.
License: No additional license required.
Permissions: Users who are server administrators or site administrators can change the connection for a data source orenablequery tagging(Link opens in a new window).Users who are not server administrators can only update a data source. If they haveWrite (save)permission for the data source and if they havewrite permission for the project.
Access Scope:tableau:datasources:update
- Access scope introduced in API 3.16 (Tableau Cloud June 2022 / Server 2022.3)
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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, callQuery Data Source Connections. |
Request Body
<tsRequest> <connectionserverAddress="newAddress"serverPort="newPort"authenticationType="new Auth Type"userName="Jane Doe"password="xxxxxx"embedPassword="false"queryTaggingEnabled="false" /></tsRequest>
{ "connection": {"serverAddress": "newAddress","serverPort": "newPort","userName": "Jane Doe","authenticationType": "new Auth Type","password": "xxxxxx","embedPassword": "false","queryTaggingEnabled": "false" }}
Request Attributes
| connection serverAddress | The new server for the connection. |
| connection serverPort | The new port for the connection |
| connection authenticationType | Added in version 3.27. The new authentication type for the connection. Standard values:
Connector-specific values:
If you are unsure of the value for authenticationType for the target connection, there are two ways to determine the value. First, if you have a data source or workbook that is currently using the target authentication type, you can query for it using the REST API methodsQuery Datasource Connections(Link opens in a new window) orQuery Workbook Connections(Link opens in a new window), which returns the authentication type string in the response. Alternatively, you can inspect the |
| connection userName | The new username for the connection. |
| connection password | The new password for the connection. |
| embedPassword | True to embed the password; otherwise,False. |
| queryTaggingEnabled | Starting with API 3.23 (Tableau Cloud June 2024 / Server 2024.2), the For API 3.22 (Tableau Cloud February 2024 / Server 2024.1) and earlier: If For more information on query tagging, seeUnderstand Workbook Impact on Your Database Using Query Tagging(Link opens in a new window). |
Any combination of the attributes inside the<connection> element is valid. If no attributes are included, no update is made.
cURL Request Example
curl --location --request PUT "/api/api-version/sites/site-id/datasources/datasource-id/connections/connection-id" \ --header "Content-Type: application/json" \ --header "X-Tableau-Auth: ZOjZ-2-xRfmShEJLk3LCKQ|KVZTJA7K1YeNuuJwXSKUKSatWRn9Vbpe|11e4e373-9777-44d1-ac04-5363d6e8092e" \ --data "{ 'connection': { 'serverAddress': 'newAddress', 'serverPort': 'newPort', 'userName': 'Jane Doe', 'authenticationType': 'new Auth Type','password': 'xxxxxx', 'embedPassword': 'false', 'queryTaggingEnabled': 'false' }"
Response Code
200
Response Body
<tsResponse> <connectionserverAddress="database.example.com"serverPort="12345"authenticationType="new Auth Type"userName="jajohnson"queryTaggingEnabled="false" /></tsResponse>{ "connection": {"id": "12ab34cd-56ef-78ab-90cd-12ef34ab56cd","serverAddress": "database.example.com","serverPort": "12345","authenticationType": "new Auth Type","userName": "jajohnson","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 haveWrite permission. |
| 403 | 403027 | Owner update forbidden | A non-administrator user tried to change connection information, but the caller doesn't haveWrite 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 notPUT. |
For more information, seeHandling Errors.
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 theRunNow setting for the site. For more information, seeTableau Server Settings(Link opens in a new window).
Version: Available in API 2.8 and later.
License: No additional license required.
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.
Access Scope:tableau:tasks:run
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(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 selectingRefresh 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, seeExtract 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 as3.27. For more information, seeREST 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>
None
Response Code
202
Response Body
<tsResponse> <job mode="Asynchronous" type="RefreshExtract" createdAt="date-time"> <extractRefreshJob> <datasource name="datasource-name" /> </extractRefreshJob></tsResponse>
{ "job": { "id": "job-id", "mode": "Asynchronous", "type": "RefreshExtract", "createdAt": "date-time", "extractRefreshJob": { "datasource": { "id": "datasource-id", "name": "datasource-name" } } }}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 notPOST. |
| 409 | 409093 | Operation already in Queue | The extract refresh job is already in the queue. |
For more information, seeHandling Errors.
cURL Example
curl "http://MY-SERVER/api/3.27/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 mode="Asynchronous" type="RefreshExtract" createdAt="2017-12-06T22:58:52Z"> <extractRefreshJob> <datasource 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 as3.27. For more information, seeREST 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 callingQuery 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Request Body
<tsRequest> <dataAlert subject="data-alert-subject" frequency="data-alert-frequency" public="is-public-flag"> <ownerapi-placeholder">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, orweekly. |
| 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> <dataAlertapi-placeholder">data-alert-id" subject="data-alert-subject" creatorId="user-id" createdAt="created-date" updatedAt="updated-date" frequency="data-alert-frequency" public="is-public-flag"> <ownerapi-placeholder">user-id" name="user-name" /> <viewapi-placeholder">view-id" name="view-name" > <workbookapi-placeholder">workbook-id" name="workbook-name" /> <projectapi-placeholder">project-id" name="project-name" /> </view> </dataAlert></tsResponse>ThecreatedAt andupdatedAt 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 notPUT. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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/> </dataAlert></tsRequest>Example response:
<tsResponse> <dataAlert 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 name="admin"/> <view name="Shipping"> <workbook name="Superstore"/> <project name="Default"/> </view> </dataAlert></tsResponse>Update Database
Update the database description, certify a database, set database permissions, or assign a Tableau Cloud or Server user as the database contact.
This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.
URI
PUT api/api-version/sites/site-luid/databases/database-luid
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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"> <contactapi-placeholder">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:
|
| 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:
The default permissions setting isManagedByOwner. 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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:databases:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response:
<tsResponse> <database 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/><contact name="fsuzuki"/><certifier name="admin"/> </database></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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.
Notes:
- Beginning in API version 3.22, you can register multiple EASs per site for Tableau Cloud.
- Beginning in API version 3.23, Tableau Server supports site-level EAS (and multiple registrations of EASs per site).
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 as3.27. For more information, seeREST 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> <externalAuthorizationServerissuerUrl="URL"jwksUri="URI"name="name" /></tsRequest>Attribute Values
A combination of attributes inside the<externalAuthorizationServer> element is valid.
| URL | (Optional) The entity id of your identity provider (IdP) or URL that uniquely identifies your IdP. |
| URI | (Optional) The JSON Web Key (JKWS) of the EAS. |
| name | (Optional) The name of the connected app. If the name attribute is not specified, the connected app name defaults to "External Authorization Server." This attribute is available starting from API version 3.22 (February 2024). |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:external_authorization_servers:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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). Introduced in Tableau Server 2024.2 (API 3.23).
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, seeTableau 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 theTableau Cloud Help(Link opens in a new window) orTableau 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 as3.27. For more information, seeREST 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 |
| allow-list | (Optional) Specifies the domains where Tableau views on this site can be embedded. Use this setting with Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. You can use wildcards in domain names and you can also list multiple domain names separated by spaces. |
Permissions
Any Tableau Cloud or Tableau Server user can call this method.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:embedding_site_settings:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <siteapi-placeholder">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, seeREST 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.27/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, seeHandling 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
Update Flow
Updates the project and/or owner of the specified flow.
To change the flow owner with fewer limitations on who the new owner can be, use theUpdate Flow Owner method instead.
URI
PUT /api/api-version/sites/site-id/flows/flow-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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> <flow> <project/><owner/> </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. The new owner must be the user calling this method. |
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, theid attribute must be included, and any other attributes of the<project> element are ignored.
If the<owner> element is included, theid 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 haveWrite permission for the destination project.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flows:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse > <flow name="flow-name" description="flow-description" webpageUrl="flow-url" fileType="flow-file-type" createdAt="Datetime-created" updatedAt="Datetime-updated"> <project name="project-name"/> <owner/> </flow></tsResponse>Thedatetime-created anddatetime-updatedattribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.3 and later. For more information, seeREST 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 haveWrite 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, seeHandling Errors.
Example
Example response:
<tsResponse version-and-namespace-settings> <flow 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 name="testproject"/> <owner/> </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 as3.27. For more information, seeREST 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 haveWrite(save) permission for the flow and if they havewrite permission for the project.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:flow_connections:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <connection serverAddress="serverAddress" serverPort="port" userName="connection-user-name" /></tsResponse>Version
Version 3.3 and later. For more information, seeREST 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 haveWrite permission. |
| 403 | 403098 | Owner update forbidden | A non-administrator user tried to change connection information for the flow, but the caller doesn't haveWrite 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 notPUT. |
For more information, seeHandling Errors.
Update Flow Owner
Updates a flow's owner.
If the same user owns all the flows in a linked task, this method also changes the ownership of the linked task to that user.
This method overlaps in function withUpdate Flow method, but has fewer limitations on who the new owner can be. If you're changing the owner of a flow, Tableau recommends you use this method.
Version: Available in API 3.27 (Tableau Cloud December 2025 / Server 2025.3) and later.
License: Data Management or Tableau+.
Permissions: Server administrators, site administrators, or flow owner
Access Scope:tableau:flows:update
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-id/flows/flow-id/owner/user-id
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the flow. |
| flow-id | The ID of the flow. |
| user-id | The ID of the user. |
Request Body
None
cURL Request Example
curl -X PUT "https://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6/owner/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -H "Content-Type: application/xml" -H "X-Tableau-Auth: a1B2c3D4e5F6g7H8i9J0kL|a1B2c3D4e5F6g7H8i9J0kL1m2N3o4P5q|12345678-90ab-4cde-8f01-234567890abc"Response Code
200
Response Body
None
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 403 | 403184 | Ownership changes are disabled | On Tableau Server, a machine administrator can use TSM to to enable or disable content ownership changes. For more information, seewgserver.change_owner.enabled intsm configuration set Options |
| 403 | 403187 | Permission denied | You must be a site administrator, a server administrator, or the flow owner to change the ownership of a flow. |
| 404 | 404061 | Resource not found | The flow id and/or user id can't be found. |
For more information, seeHandling 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 as3.27. For more information, seeREST 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 totrue to synchronize with Active Directory as a background task, or set this value tofalse to synchronize immediately (synchronously). The default isfalse. 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 andminimumSiteRole is specified, users are granted alicense 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, theUpdate 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 animport element orgrantLicenseModeattribute are present in the request. The site role assigned to users who are imported from Active Directory (Tableau Server only) or granted alicense 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 onespecified in the request, based on the role that enables the most capabilities. This is true whether the group the user belongs to isimported from Active Directory (Tableau Server only) or local. Site roles that can be assigned, listed from the one enabling the least capabilities tothe most, are as follows.
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 isonLogin, a license is granted for each group member when they log in to a site. For local groups, the mode can be eitheronLogin or unset. If the attribute is omittedduring an update, the group will use the license grant mode configured prior to the update. A local group configuredto useonLogin can switch the mode to unset by updating the group using: For groups that import an Active Directory domain (Tableau Server only), thegrantLicenseModecan be updated to eitheronSyncoronLogin. If the attribute is omitted during an update, the group will use the license grant modeconfigured prior to the update. The minimum role granted to users throughgrantLicenseMode is specified in thesiteRole attribute of theimport 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 withEmbedded Analytics(Link opens in a new window) usage-based model. Set totrue to enable the capability for the group or set tofalse 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) orOn-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).
tableau:groups:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200 (immediate update)
202 (background update)
Response Body
Updating a local group:
<tsResponse> <groupapi-placeholder">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> <groupapi-placeholder">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 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 theQuery Job method, which returns status information about the job. A typical approach is to periodically callQuery Job method and get the value of theprogress attribute from the response body; when this value returns 100, the import process is complete.
Version
Version 3.9 and later. For more information, seeREST 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 theminimumSiteRole orsiteRole attribute must beExplorer,ExplorerCanPublish,SiteAdministratorCreator,SiteAdministratorExplorer,Unlicensed,orViewer. |
| 403 | 400019 | Malformed import element | If the body includes an<import> element, it must contain asource,domainName, andsiteRole attribute. If any of these attributes are missing, the element is malformed. In addition, thesource attribute must have a value ofActiveDirectory; 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 thename attribute of the<group> elementin the request body is different from the name of the group imported into Tableau Server as referenced by thegroup-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 notPUT. |
| 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, seeHandling Errors.
Update Group Set
Updates a group set name on a Tableau Server or Tableau Cloud site.
Version:Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-id/groupsets/group-set-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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
<tsRequest>
<groupSet name="Researchers-one" />
</tsRequest>{
"groupSet": {
"@name": "Researchers-one"
}
}Attribute Values
| name | The new name for the group set. |
Response Code
200
Response Body
<tsResponse>
<groupSet
name="Researchers-one"
groupCount="2"/>
<group
name="Internal"/>
<group
name="External"/>
</groupSet>
</tsResponse>{
"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"
}
]
}
}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 theminimumSiteRole orsiteRole attribute must beExplorer,ExplorerCanPublish,SiteAdministratorCreator,SiteAdministratorExplorer,Unlicensed,orViewer. |
| 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’tPUT. |
| 409 | 409120 | Group set not found. | The group set ID in the request body doesn't correspond to an existing group set. |
| 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, seeHandling 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}
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 theData Labels in the REST API(Link opens in a new window) topic.
You can't update extract refresh or flow run monitoring warnings (theextract_refresh_failure andflow_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 theTableau Server(Link opens in a new window) andTableau Cloud(Link opens in a new window) Help and the quality warning trigger methods inMetadata Methods.
All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires aData 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 as3.27. For more information, seeREST 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. SeeData Labels in the REST API for a list of built-in label values and categories. Choosing a monitoring quality warning value (extract_refresh_failure orflow_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 totrue, the label becomes active. If set tofalse, the label becomes inactive. If omitted, the default istrue. |
| elevated-flag | (Optional) Boolean. If set totrue, the label becomes elevated. If set tofalse, the label becomes not elevated. If omitted, the default isfalse. |
Permissions
- To add or update a data label other than a certification label, you must havewrite 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 assetnot in a project, you must have thechange permissions permission on the associated asset.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).
tableau:labels:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <label 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/> <owner/> </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 valuesextract_refresh_failure andflow_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 theData Labels in the REST API(Link opens in a new window) topic.
AData 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The unique LUID of the site asset. |
| label-category-name | The label category name. URL encode the label category name (as it appears in the Tableau web interface) if it has spaces or non-alphanumeric characters in it. |
Request Body
<tsRequest> <labelCategory name="label-category-name" description="label-category-description" /></tsRequest>
Attribute Values
| label-category-name | The label category name. Required, but not does not have to be different from the existing name. Must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.) |
| label-category-description | The label category description. Required, but not does not have to be different from the existing description. Must be 1-500 characters in length. |
Permissions
Only a site or server administrator can create, update, or delete label categories.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_categories:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 |
|
Update Labels
Creates or updates labels on one or more assets.
Each asset listed in the request body is updated to have a label with the specified value, message, active flag, and elevated flag.
If the request body specifies a label value that is already on the asset, the label on the asset is updated to match the request body. Otherwise, a label is created and attached to the asset.
Note: On Tableau Server 2023.3 and earlier, only one label of a category is allowed on an asset. If the request body specifies a label value withthe same category as a label already on the asset, the label on the asset is updated to match the request body. Otherwise, a label is created and attached to the asset.
Note that the label category is not an attribute in the request body, because you do not set it explicitly. Instead you implicitly set the category by using the label value name. For example, choosing a label value name ofstale means that the label value category will bewarning. 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 theData Labels in the REST API(Link opens in a new window) topic.
You can't update extract refresh or flow run monitoring warnings (theextract_refresh_failure andflow_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 theTableau Server(Link opens in a new window) andTableau Cloud(Link opens in a new window) Help and the quality warning trigger methods inMetadata Methods.
All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires aData Management license.
URI
PUT api/api-version/sites/site-luid/labels
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The unique LUID of the site asset. |
Request Body
<tsRequest> <contentList> <content contentType="asset-type" /> <!-- ... 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:
|
| asset-luid | The asset LUID. |
| label-value-name | The label value name. The built-in label value names are:
You can also use custom label value names that an administrator creates. (Custom label values were released with Tableau Cloud June 2023 and Tableau Server 2023.3.) If the request body specifies a label value that is already on the asset, the label on the asset is updated to match the request body. Otherwise, a label is created and attached to the asset. Note: On Tableau Server 2023.3 and earlier, only one label of a category is allowed on an asset. If the request body specifies a label value withthe 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. SeeData Labels in the REST API for a list of built-in label values and categories. Choosing a monitoring quality warning value (extract_refresh_failure orflow_run_failure) causes an error. |
| label-message | (Optional. Was required in Tableau Server 2023.3 and earlier.) The message text for the label. In the web interface, this is reflected as a certification note or a data quality warning message. |
| active-flag | (Optional) Boolean. If set totrue, the label becomes active. If set tofalse, the label becomes inactive. If omitted, the default istrue. |
| elevated-flag | (Optional) Boolean. If set totrue, the label becomes elevated. If set tofalse, the label becomes not elevated. If omitted, the default isfalse. |
Permissions
- To add or update a data label other than a certification label, you must havewrite 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 assetnot in a project, you must have thechange permissions permission on the associated asset.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2024 and Tableau Server 2024.2 (API 3.23).
tableau:labels:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 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/> <owner/> </label> <!-- ... additional label elements ... –-> </labelList></tsResponse>Errors
When more than one asset appears in the request (thecontentList element contains more than onecontent 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 | ThecontentType andcontentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrectcontentType, an incorrectcontentID, or both. |
| 409 | 409004 | Invalid parameter | One or more values in the request body are invalid, or one of the required attributes (active orelevated) is missing. This error can also occur if you try to create or change a monitoring quality warning (label values extract_refresh_failure andflow_run_failure). |
Update labelValue
Updates a label value.
Note: You can update an existing label value using either this method or theCreate 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 theData Labels in the REST API(Link opens in a new window) topic.
AData 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The unique LUID of the site asset. |
| label-value-name | The label value name. URL encode the label value name if it has spaces or non-alphanumeric characters in it. |
Request Body
<tsRequest> <labelValue name="label-value-name" category="label-value-category" description="label-value-description" /></tsRequest>Attribute Values
| label-value-name | The label value name. If the label value name is different than the one in the URI parameter, the label value name is changed to match the one in the request body. Required. Must be 1-128 characters long. (Must be 1-24 characters long in Tableau Server 2023.3 and earlier.) |
| label-value-category | The label value category. Required. You can't change the label value category, so this will always match the label value's existing category. |
| label-value-description | The label value description. Must be 1-500 characters in length. |
Permissions
Only a site or server administrator can create, update, or delete label values.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:label_values:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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/> </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 thecertification category. |
| 409 | 409004 | Invalid parameter |
|
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.Version Overview
Permissions: Any user can create a metric in a definition as long as the user has write and 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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
PATCH {server}/api/-/pulse/metrics/{metric_id}
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 methodswill 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 as3.27. For more information, seeREST 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> <metricdescription="updated-metric-description" name="updated-name"suspended="updated-suspended-flag" > <projectapi-placeholder">updated-project-id"/> <ownerapi-placeholder">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. Iftrue the metric is suspended. The default isfalse. |
| 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 nestedelements are included, no update is made.
If the<project> element is included, theidattribute must be included, and any other attributes of the<project> element are ignored.
If the<owner> element is included, theid attribute must be included, and any other attributes of theowner 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 haveWrite permission for the destination project.
tableau:metrics:updateAccess Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:metrics:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <metricapi-placeholder">metric-id"name="metric-name"description="metric-description"webpageUrl="webpageUrl-url"createdAt="datetime-created"updatedAt="datetime-updated"suspended="suspended-flag""> <projectapi-placeholder">new-project-id" /> <ownerapi-placeholder">new-owner-id" /> <tags> <tag label="tag"/> <!-- ... additional tags ... --> </tags></metric></tsResponse>Thedatetime-created anddatetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 2.0 and later. For more information, seeREST 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 haveWrite permission forthe 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 notPUT. |
| 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, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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/> <owner/> </metric></tsRequest>Example response body:
<tsResponse > <metric 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 name="Tableau Samples"/> <owner/> <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.Version Overview
Permissions: Any user can update a metric definition as long as the user has write and 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:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
PATCH {server}/api/-/pulse/definitions/{definition_id}
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:tableau:mobile_security_site_settings:read
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST API and Resource Versions. |
Request Body
{
"mobileSecuritySettingsList": {
"mobileSecuritySettings": [
{
"name": "mobile.security.jailbroken_device",
"enabled": true,
"iosConfig": {
"valueList": [
"true"
],
"severity": "warn"
},
"androidConfig": {
"valueList": [
"false"
],
"severity": "critical"
}
},
{
"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:
|
mobileSecuritySettings enabled | (Optional)Boolean. Iftrue, enables the Tableau mobile client to detect and respond tothe condition described in the setting'sname. Theenabled attribute for the Androidor iOS configuration element of the setting must also betrue for detection on that type of device.IfmobileSecuritySettings enabled = false, the Android and iOS configuration element attributesettings will be ignored. |
mobileSecuritySettings androidConfig / iosConfig | (Optional)Element. Security settings specific to the platform of the mobile device hosting the Tableau clientfor the setting being configured. Required attributes of this element are:
|
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
{
"mobileSecuritySettingsList": {
"mobileSecuritySettings": [
{
"name": "mobile.security.jailbroken_device",
"enabled": true,
"iosConfig": {
"valueList": [
"true"
],
"severity": "warn"
},
"androidConfig": {
"valueList": [
"false"
],
"severity": "critical"
}
},
{
"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 forenabled,iosConfig,androidConfig,severity, orenabled attributes are possible causes. |
| 400 | 400174 | Mobile security settings error | An uknown mobile security settings error has occurred. |
| 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 settingenabled,name or other value is missing or malformed. |
For more information, seeHandling Errors.
Update Monitoring Quality Warning
Update a monitoring quality warning.
This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.
URI
PUT api/api-version/sites/site-id/dataQualityTriggers/trigger-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| trigger-id | The unique ID of the monitoring quality warning. |
Request Body
<tsRequest> <dataQualityTrigger type="type" active="status" message="message" severe="severity"/></tsRequest>Attribute Values
| type | Type of monitoring quality warning. To specify the type, use one of the following values:
These values are not case sensitive. |
| status | Monitoring status. Values can be "true" or "false". If set to "true", the data source is monitored for extract refresh failures or the flow is monitored for flow run failures). If an extract refresh or flow run failure occurs, the specified data quality warning is attached to the data source or flow (depending ontype). The data quality warning is removed when the extract refresh or flow run is successful. For more information about monitoring quality warnings, see the monitoring quality warning section of the "Set a Data Quality Warning" topic in theServer Help orCloud Help. |
| message | (Optional) A custom message for the data quality warning. |
| severity | High visibility status of the data quality warning. Values can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in theServer Help orCloud Help. |
Permissions
If Tableau Server or Tableau Cloud is licensed throughData Management, the following users have permissions to update a monitoring quality warning:
- Tableau Server admins or Tableau Cloud site admins
- Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:labels:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response
<tsResponse> <dataQualityTriggerList><dataQualityTrigger 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, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400137 | Generic quality warning trigger error | The monitoring quality warning could not be updated for some other reason than those specified below. |
| 403 | 403004 | Unauthorized operation. | Insufficient permissions to perform the operation. |
| 409 | 409004 | Invalid parameter | One or more values in the request body are invalid. |
Update OpenID Connect Configuration
Update the Tableau Cloud site's OpenID Connect (OIDC) configuration.
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.
URI
PUT /api/api-version/sites/site-luid/site-oidc-configuration
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
<tsRequest>
<siteOIDCConfiguration
idpConfigurationId="idpConfigurationId"
enabled="enabled"
clientId="clientId"
clientSecret="clientSecret"
authorizationEndpoint="authorizationEndpoint"
tokenEndpoint="tokenEndpoint"
userinfoEndpoint="userinfoEndpoint"
jwksUri="jwksUri"
idpConfigurationName="idpConfigurationName"
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>{
"siteOIDCConfiguration": {
"idpConfigurationId": "idpConfigurationId",
"enabled": "enabled",
"clientId": "clientId",
"clientSecret": "clientSecret",
"authorizationEndpoint": "authorizationEndpoint",
"tokenEndpoint": "tokenEndpoint",
"userinfoEndpoint": "userinfoEndpoint",
"jwksUri": "jwksUri",
"idpConfigurationName": "idPConfigurationName",
"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.
idpConfigurationId | (Required)Starting in API 3.24, multiple authentication configurations can be created and enabled at the same time. Include theidpConfigurationId to identify which configuration to update. If noIdPConfigurationId is specified, the initial (default) OIDC configuration is updated if it exists. To get theidpConfigurationId value, use theList Authentication Configurations for Site method. For more information, seeAuthentication(Link opens in a new window) in the Tableau Cloud Help. |
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". |
jwksUri | (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". |
idpConfigurationName | (Optional) The name of the configuration. Starting in API 3.24, you can create and enable multiple authentication configurations. Authentication configurations that were enabled before API 3.24 are given a name and its name can't be updated. For example, "Initial OIDC". If this configuration was created after API 3.23 and no name is provided for the update, the name will stay the same. For more information, seeAuthentication(Link opens in a new window) in the Tableau Cloud Help. |
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 whenuseFullName 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 whenuseFullName 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 whenuseFullName 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.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuratioin" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-update-oidc-config.xml
Content of create-update-oidc-config.xml:
<tsRequest>
<siteOIDCConfiguration
idpConfigurationId="idpConfigurationId"
enabled="enabled"
clientId="clientId"
clientSecret="clientSecret"
authorizationEndpoint="authorizationEndpoint"
tokenEndpoint="tokenEndpoint"
userinfoEndpoint="userinfoEndpoint"
jwksUri="jwksUri"
idPConfigurationName="idPConfigurationName"
endSessionEndpoint="endSessionEndpoint"
allowEmbeddedAuthentication="allowEmbeddedAuthentication"
prompt="prompt"
customScope="customScope"
clientAuthentication="clientAuthentication"
essentialAcrValues="essentialAcrValues"
voluntaryAcrValues="voluntaryAcrValues"
emailMapping="emailMapping"
firstNameMapping="firstNameMapping"
lastNameMapping="lastNameMapping"
fullNameMapping="fullNameMapping"
useFullName="useFullName" />
</tsRequestResponse Code
200
Response Body
<tsResponse>
<siteOIDCConfiguration
idpConfigurationId="00000000-0000-0000-0000-000000000000"
enabled="true"
testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
allowEmbeddedAuthentication="false"
clientId="0oa111usf1gpUkVUt0h1"
clientSecret="<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"
idPConfigurationName="Initial OIDC"
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>{
"siteOIDCConfiguration": {
"idpConfigurationId":"00000000-0000-0000-0000-000000000000",
"enabled":"true",
"testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC",
"allowEmbeddedAuthentication":"false",
"clientId":"0oa111usf1gpUkVUt0h1",
"clientSecret":"<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",
"idPConfigurationName":"Initial OIDC",
"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"
}
}Notes:
The response hides the client secret and replaces it with
<omit>.You can use thetestloginURL to validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.
You can use theidpConfigurationId to assign authentication to a user using theAdd User to Site andUpdate User methods.
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, seeHandling 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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 thepublish-value is not specified in the request, or thepublishSamples parameter is missing, no samples will be published. To publish the sample workbooks, setpublishSamples parameter totrue. This option is equivalent to thetabcmd command-line utility option,publishsamples. For more information, seetabcmd(Link opens in a new window). |
Request Body
<tsRequest>
<project
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/>
</project>
</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"
}
}
}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 DefaultsWindows(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 theparentProjectId attribute.To move a project to the top of the project hierarchy, provide an empty string ("") fortheparentProjectId attribute. For information about how permissions are evaluated in project hierarchies, seeProject Permissions States and Defaults. |
project contentPermissions | (Optional) This value controls user permissions in a project, however, if the project is nested within a projectwith more restrictive policies, it will inherit those permissions and these settingswill have no effect. The functional permissions of a project, including those it inherits, are available in value ofcontentPermission in the response body from a request to create, update, or query a project.
The default isManagedByOwner. For more information, seeLock 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 theparentProjectId attribute.To move a project to the top of the project hierarchy, provide an empty string ("") fortheparentProjectId attribute. For information about how permissions are evaluated in project hierarchies, seeProject 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
<tsResponse>
<project
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/>
</project>
</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"
}
}
}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 toLockedToProjectWithoutNested 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 notPUT. |
| 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, seeHandling Errors.
Update Pulse user preferences
Updates the signed in user's preferences for notifications channels and cadence, and for grouping and sorting followed metrics in REST responses and UI.
Version: Available in API 3.24 (Tableau Cloud December 2024) and later. Not available for Tableau Server.Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of subscriptions.Permissions Overview
License: No additional license required.
Access Scope: `tableau:user_preferences:update`
Access Scopes Overview:CloudTableau Cloud |Tableau Server-Windows |Tableau Server-Linux
PATCH {server}/api/-/pulse/user/preferences
Update SCIM Configuration
Updates the System for Cross-domain Identity Management Configuration (SCIM) configuration on the Tableau Cloud site.
You must be the user that created the SCIM configuration to update the SCIM configuration unless the creator of the SCIM configuration is no longer a member of the site.
Version: Available in API 3.26 (Tableau Cloud August 2025) and later.
License: No additional license required.
Permissions: Tableau Cloud site admins only.
Access Scope:tableau:scim_configurations:read
Scope added in API 3.27 (Tableau Cloud December 2025)
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),access scopes for UATs(Link opens in a new window) (Cloud) and access scopes for connected appsCloud(Link opens in a new window).
URI
PATCH /api/api-version/sites/site-luid/scimConfigurations/scim-configuration-id
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| scim-configuration-id | The UUID of the SCIM configuration. To get the SCIM configuration UUID, seeList SCIM Configurations. |
Request Body
<tsRequest> <scimConfiguration> <name>SCIM Contractors Canada</name> <idpConfigurationId>d3b782da-0787-44ca-8585-6fd48dbfc658d3b782da-0787-44ca-8585-6fd48dbfc658</idpConfigurationId> </scimConfiguration></tsRequest>
{"scimConfiguration": { "name": "SCIM Contractors Canada", "idpConfigurationId": "d3b782da-0787-44ca-8585-6fd48dbfc658d3b782da-0787-44ca-8585-6fd48dbfc658" }}
cURL Request Example
POST request: curl --location 'https://prod-ca-a.online.tableau.com/api/3.27/sites/0f04ea64-0d72-424a-afd8-ee7d758dc9b8/scimConfigurations \ --data '{ "scimConfiguration":{ "name": "SCIM Contractors Canada", "idpConfigurationId": "d3b782da-0787-44ca-8585-6fd48dbfc658" } }'
Attribute Values
| name | (Required) Name of the SCIM configuration. |
| idpConfigurationId | (Required) SAML authentication configuration to associate with the SCIM configuration. Starting in API 3.26, you can have multiple SCIM configurations. Include theidpConfigurationId to identify which configuration to update. If a SCIM token is associated with SCIM configuration, updating theIdPConfigurationId deletes the SCIM token. Ensure the SCIM token's secret is removed from the identity provider's (IdP's) SCIM configuration. To get theidpConfigurationId, seeList Authentication Configurations for Site. |
Response Code
204
Response Body
<tsResponse> <scimConfiguration> <id>065693d8-436a-4738-a8f1-375953a2a888</id> <idpConfigurationId>d3b782da-0787-44ca-8585-6fd48dbfc658</idpConfigurationId> <isApiTokenActive>false</isApiTokenActive> <isOwner>true</isOwner> <name>SCIM Contractors Canada</name> <createdAt>2025-04-01 06:31:47.882</createdAt> </scimConfiguration></tsResponse>
{ "scimConfiguration": { "id": "065693d8-436a-4738-a8f1-375953a2a888", "idpConfigurationId": "d3b782da-0787-44ca-8585-6fd48dbfc658", "isApiTokenActive": false, "isOwner": true, "name": "SCIM Contractors Canada", "createdAt": "2025-04-01 06:31:47.882" }}
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400008 | Bad Request | The content of the request body contains unsupported attributes, the SCIM configuration name already exists, or theidpConfigurationId is missing or not valid. |
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header is invalid or has expired. |
| 403 | 403182 | Forbidden | The SCIM configuration can only be updated by the user who created the SCIM configuration. |
| 404 | 404050 | Resource Not Found | The SCIM configuration does not have an associated SCIM token. |
| 404 | 404057 | Resource Not Found | The SCIM configuration UUID is not valid or does not exist on this site. |
For more information, seeHandling Errors.
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 arecurrently 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, seeSupport for multiple domains(Link opens in a new window).
If the domain islocal, 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 as3.27. For more information, seeREST API and Resource Versions. |
| domain-id | The integer ID of the of the Active Directory domain being updated. Find a domain's ID usingList 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:domains:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
Example response:
<tsRequest> <domainapi-placeholder">domain-id-int" name="domain-name" shortName="domain-nickname" /></tsRequest>Version
Version 3.11 and later. For more information, seeREST 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, seeHandling Errors.
Example
For an Active Directory with the ID of1045, name ofmyOldDomainName, and a nickname ofmyOldDomainNickname:
curl "http://MY-SERVER/api/3.27/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 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, seeUpdate cloud extract refresh task andUpdate subscription.
URI
PUT /api/api-version/schedules/schedule-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| schedule-id | The ID of the schedule to update. To determine what schedules are available, callList 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> <intervalinterval-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, orSerial to require the jobs to run one after the other. |
| new-schedule-frequency | The granularity of the schedule. Valid values are:
The value you provide forschedule-frequency determines whether you must include anend-time value, and what is required in the contents of the<intervals> element. |
| new-state | Active to enable the schedule, orSuspended 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 formatHH: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 isHourly, the time of day on which scheduled jobs should stop being run, in the formatHH: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 ofschedule-frequency.
The interval expression is only one of the following:
You can specify an interval in hours or minutes, but not both.
If the schedule frequency is
The interval expression is 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.
The interval expression is 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:schedules:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <scheduleapi-placeholder">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"> <frequencyDetailsfrequency-expression > <intervals> <intervalinterval-expression /> </intervals> </frequencyDetails> </schedule></tsResponse>Version
Version 2.3 and later. For more information, seeREST 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 notPUT. |
| 409 | 409021 | Schedule name conflict | The schedule name in the request already belongs to an existing schedule. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 toHourly. Bothstart andend values are required. Theintervals element is required, and must include 1interval subelement that contains either anhours or aminutes attribute. Valid values forminutes are15 or30. Valid values forhours are1,2,4,6,8, or12.
<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>version-and-namespace-settings</span>> <schedule 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, seeCreate 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 withTableau 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) and later.Version Overview
Permissions: Can only be called by users with site or 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/site/extensions/dashboard/safeListItems/{safe_list_item_luid}
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.
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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site to update. |
Request Body
Updating individual settings
<tsRequest> <site name="new-site-name" contentUrl="new-content-url" adminMode="new-admin-mode" storageQuota="limit-in-megabytes" disableSubscriptions="new-disable-subscriptions" state="new-state" revisionHistoryEnabled="revision-history-enabled" revisionLimit="revision-limit" allowSubscriptionAttachments="allow-subcription-attachments-flag" subscribeOthersEnabled="subscribe-others-enabled-flag" guestAccessEnabled="guest-access-enabled-flag" cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]" commentingEnabled="commenting-enabled-flag" editingFlowsEnabled="editing-flows-enabled-flag" schedulingFlowsEnabled="scheduling-flows-enabled-flag" extractEncryptionMode="extractEncryptionMode" dataAccelerationMode="dataAccelerationMode" requestAccessEnabled="request-access-enabled-flag" runNowEnabled="run-now-enabled-flag" userQuota="all-license-limit-total" tierCreatorCapacity="creator-license-limit" tierExplorerCapacity="explorer-license-limit" tierViewerCapacity="viewer-license-limit" dataAlertsEnabled="data-alerts-enabled-flag" commentingMentionsEnabled="commenting-mentions-enabled-flag" catalogObfuscationEnabled="catalog-obfuscation-enabled-flag" flowAutoSaveEnabled="flow-auto-save-enabled-flag" runNowEnabled="run-now-enabled-flag" metricsContentTypeEnabled="metrics-content-type-enabled-flag" notifySiteAdminsOnThrottle="notify-site-admins-on-throttle-flag" authoringEnabled="authoring-enabled-flag" customSubscriptionEmailEnabled="custom-subscription-email-enabled-flag" customSubscriptionEmail="custom-subscription-email" customSubscriptionFooterEnabled="custom-subscription-footer-enabled-flag" customSubscriptionFooter="custom-subscription-footer" askDataMode="ask-data-mode" namedSharingEnabled="named-sharing-enabled-flag" catalogingEnabled="cataloging-enabled-flag" derivedPermissionsEnabled="derived-permissions-enabled-flag" userVisibilityMode="user-visibility-mode" useDefaultTimeZone="default-time-zone-flag" timeZone="time-zone" autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag" autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window" explainDataEnabled="explaindataenabled" dqwSubscriptionsEnabled="dqwsubscriptionsenabled" attributeCaptureEnabled="attribute-capture-enabled" groupAssertionsEnabled="group-assertions-enabled-flag" groupAssertionsSAMLEnabled="group-assertions-saml-enabled-flag" groupAssertionsOIDCEnabled="group-assertions-oidc-enabled-flag" groupAssertionsConnectedAppsEnabled="group-assertions-connected-apps-enabled-flag" groupSetsEnabled="group-sets-enabled-flag" recycleBinEnabled="recycle-bin-enabled-flag" /></tsRequest>Updating the site logo
To set a new site logo, you pass a multi-part payload to the site. In addition to setting theX-Tableau-Auth header to the sign-in token, you must set theContent-Type header tomultipart/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 setContent-Disposition header toform-data, and then aname value set tosite_logo and afilename value. You must also include aContent-Type header set toapplication/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 theContent-Type header in the body toapplication/octet-stream, you set the content type totext/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 astest.site, it's converted totestsite 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) SpecifyContentAndUsers to allow site administrators to use the server interface andtabcmd commands to add and remove users. (Specifying this option doesn't give site administrators permissions to manage users using the REST API.) SpecifyContentOnly to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.)Note: You cannot setadminMode toContentOnly and also set auserQuota value.The default value isContentAndUsers. |
| new-state | (Optional)Active to set the site to active mode, orSuspended to suspend the site. Default isActive. |
| 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 isfalse. |
| revision-history-enabled | (Optional)true if the site maintains revisions for changes to workbooks and data sources; otherwise,false. The default isfalse. |
| 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) Iftrue, 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 istrue. If subscription to attachments is disabled in the server settings, then making this valuetrue will have no effect.Default istrue. |
| subscribe-others-enabled-flag | (Optional) Specifytrue to enable andfalse to disable the ability for view owners to subscribe other users to a view.Default istrue. |
| editing-flows-enabled-flag | (Optional) Specifytrue to enable andfalse to disable editing flows for a site. For more information on flows, seeEnable and Configure Tableau Prep Conductor(Link opens in a new window). The default is set totrue, which means editing flows is enabled by default. For more information, seeImplication of disabling Tableau Prep Conductor. |
| scheduling-flows-enabled-flag | (Optional) Specifytrue to enable andfalse to disable scheduling flows for a site. For more information on flows, seeEnable and Configure Tableau Prep Conductor(Link opens in a new window). The default is set totrue, which means scheduling flows is enabled by default. For more information, seeImplication of disabling Tableau Prep Conductor. |
| flows-enabled-flag | TheflowsEnabled attribute is deprecated as of API 3.10. |
| guest-access-enabled-flag | (Optional) Specifytrue to enable andfalse to disable the ability for guests, users without specific site access permission, to access the site.Default isfalse. |
| cache-warmup-enabled-flag | This attribute was removed in API 3.19 and later. For currentmethods to improve Tableau performance see,View Acceleration(Link opens in a new window). (Optional) Set this value totrue to enable cache warm up toimprove workbook load times. Set the value tofalse to disable cache warmup.Default istrue. |
| commenting-enabled-flag | (Optional) Specifytrue to enable andfalse to disable the ability for user comments on views in the site.Default istrue. |
| extractEncryptionMode | (Optional) Specifyenforced,enabled, ordisabled.Default isdisabled. For more information, seeExtract and Encryption Methods. |
| dataAccelerationMode | (Optional) Specifyenable_selective ordisabled. The default isenable_selective, which lets you update particular workbooks to turn on data acceleration using theaccelerationEnabled attribute. For more information, seeData Acceleration.(Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. SeeView Acceleration(Link opens in a new window).) |
| requestAccessEnabled | (Optional) Specifytrue to allow users send access request emails to content or project owners. Specifyfalse if you don't want users to be able to request access. The default isfalse. |
| runNowEnabled | (Optional) Specifytrue to allow users to run flows, extract refreshes, and schedules manually. Specifyfalse if you don't want users to be able to run flows, extract refreshes, and subscriptions manually. The default istrue. If this attribute is set tofalse, the following methods will fail and will return an error message. Run Flow Task(Link opens in a new window) |
Licensing attributes | |
User quota all-license-limit-total | (Optional) The maximum total number of users with Creator, Explorer, or Viewer licenses currently allowed on a site. On-premises server administrators can set An administrator can revert the license limit to number of activated licenses on the site, or shift control of licenselimits to tiered capacities values, by omitting |
Tiered capacity attributes creator-license-limit | (Optional) The maximum number of licenses for users with the Creator,Explorer, or Viewer role, respectively, allowed on a site. On-premises server administrators can set tiered capacity attributes with the following rules: the number can'texceed the number of licenses of a given type that are activated for the site; a value must be supplied forevery 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 ofactivated licenses configured for the role. Setting the value of a tiered capacity to -1 will not automaticallyincrease the limit if more licenses are purchased and activated for the role in the future. To use role-specific license limits, the |
data-alerts-enabled-flag | (Optional, boolean) Iftrue, data alerts are enabled on the site. Default value istrue. |
commenting-mentions-enabled-flag | (Optional, boolean) Iftrue, mentions for commenting are enabled. Default value istrue. |
catalog-obfuscation-enabled-flag | (Optional, boolean) Iftrue, catalog obfuscation is enabled on the site. Default value istrue. |
flow-auto-save-enabled-flag | (Optional, boolean) Iftrue, flow auto save is enabled on the site. Default value istrue. |
run-now-enabled-flag | (Optional, boolean) Iftrue, run now for schedules is enabled which allows non-administrators to run schedules manually. Default value istrue. |
metrics-content-type-enabled-flag | (Optional, boolean) Iftrue, the metrics content type is enabled on the server. Default value isfalse. |
notify-site-admins-on-throttle-flag | (Optional, boolean) Iftrue, site admins will be notified if their background jobs are being throttled. Default value isfalse. |
authoring-enabled-flag | (Optional, boolean) Iftrue, web authoring is enabled. Default value isfalse. |
custom-subscription-email-enabled-flag | (Optional, boolean) Iftrue, sending custom subscription email is enabled. If set to false after being set true, the current custom subscription email is voided. Default value isfalse. |
custom-subscription-email | A valid custom email that will be sent ifcustomSubscriptionEmailEnabled is set to true. Default value isfalse. |
custom-subscription-footer-enabled-flag | (Optional, boolean) Iftrue, 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 isfalse. |
custom-subscription-footer | A custom subscription footer that will be added to subscription and data alerts ifcustomSubscriptionFooterEnabled is set to true. Default value isfalse. |
ask-data-mode | The mode of the ask data feature on the site. Can be set to one of two values:
DisabledByDefault. For more information, seeDisable or Enable Ask Data for a Site(Link opens in a new window). |
named-sharing-enabled-flag | (Optional, boolean) Iftrue, named sharing is enabled. Default value istrue. |
cataloging-enabled-flag | (Optional, boolean) Iftrue, data catalog is enabled for the site. Default value istrue. |
derived-permissions-enabled-flag | (Optional, boolean) Iftrue, derived permissions are enabled for the site. Default value isfalse. |
user-visibility-mode | (Optional, string) When the value isFULL users can see the user of other site users. If the value isLIMITED User information on the site is not visible to other users. Default value isFULL. For more information, seeUser Visibility(Link opens in a new window). |
| use-default-time-zone | (Optional, boolean) Set this totrue, if you want thetime-zone attribute use the Server time Zone at run time. This attribute is set to official IANA name. If this is set tofalse, thetime-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 onWikipedia. |
| 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 |
| dqwSubscriptionsEnabled | (Optional, boolean) Set this attribute to |
| attribute-capture-enabled | (Optional, boolean) Set this attribute to Starting in October 2025 (API version 3.27), you can also use this attribute to pass user information about your identity provider to Tableau Cloud. During single sign-on (SSO), user attribute functions in Tableau content can accept attributes from OIDC claims or SAML assertions. For more information, seeOIDC(Link opens in a new window) orSAML(Link opens in a new window) topics in the Tableau Cloud Help. |
| groupAssertionsEnabled | (Optional) Set totrue to allow assertions into group membership using session info. Set tofalse if you don't want users to be able to be asserted in to groups. The default isfalse. If this attribute is set to false, it will disable group assertions for the entire site, including the following settings:
|
| groupAssertionsSAMLEnabled | (Optional, boolean) Set totrueto allow assertions into group membership using SAML session info. Set tofalseif you don't want users to be able to be asserted in to groups. The default isfalse. If this attribute is set to false, it will disable group assertions for SAML sessions. |
| groupAssertionsOIDCEnabled | (Optional, boolean) Set totrueto allow assertions into group membership using OIDC session info. Set tofalseif you don't want users to be able to be asserted in to groups. The default isfalse. If this attribute is set to false, it will disable group assertions for OIDC sessions. |
| groupAssertionsConnectedAppsEnabled | (Optional, boolean) Set totrueto allow assertions into group membership using Connected App JWT tokens. Set tofalseif you don't want users to be able to be asserted into groups via connected apps. The default isfalse. If this attribute is set to false, it will disable group assertions for JWT connected app connections. |
| groupSetsEnabled | (Optional, boolean) Set totrue to allow groups sets. Set tofalse if you don't want group sets support for the site. The default isfalse. If this attribute is set to false, it will disable group sets for the site. |
| recycleBinEnabled | (Optional, boolean) Set totrue to enable the Recycle Bin. Set tofalse to disable it. The default istrue. |
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 callUpdate Site to upload a custom logo image for the site. (For information about custom logos, seeCustom 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.0Content-Type: multipart/mixed; boundary=boundary-stringX-Tableau-auth:authentication-token
The following example shows the request body for anUpdate Site request that updates the site with a new logo. For this example, the boundary string has been set in the header to6691a87289ac461bab2c945741f136e6. The<site> element can be empty if you're callingUpdate Site only to update the logo image.
--6691a87289ac461bab2c945741f136e6 Content-Disposition: name="request_payload" Content-Type: text/xml <tsRequest> <sitesite attributes > </site> </tsRequest> --6691a87289ac461bab2c945741f136e6 Content-Disposition: name="site_logo"; filename="MySiteLogo.png" Content-Type: application/octet-streamlogo stream here --6691a87289ac461bab2c945741f136e6--To clear a custom logo image and revert to using the default logo for the site, callUpdate 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, seePublishing 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).
tableau:sites:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <siteapi-placeholder">site-id" name="site-name" contentUrl="content-url" adminMode="admin-mode" storageQuota="limit-in-megabytes" disableSubscriptions="true-or-false" state="active-or-suspended" revisionHistoryEnabled="true-or-false" revisionLimit="revision-limit" allowSubscriptionAttachments="allow-subcription-attachments-flag" cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]" commentingEnabled="commenting-enabled-flag" editingFlowsEnabled="editing-flows-enabled-flag" schedulingFlowsEnabled="scheduling-flows-enabled-flag" catalogingEnabled="cataloging-enabled-flag" derivedPermissionsEnabled="derived-permissions-enabled-flag" requestAccessEnabled="request-access-enabled-flag" runNowEnabled="run-now-enabled-flag" userQuota="all-license-limit-total" tierCreatorCapacity="creator-license-limit" tierExplorerCapacity="explorer-license-limit" tierViewerCapacity="viewer-license-limit" askDataMode="ask-data-mode" useDefaultTimeZone="default-time-zone-flag" timeZone="time-zone" autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag" autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window" explainDataEnabled="explain-data-enabled" dqwSubscriptionsEnabled="dqw-subscriptions-enabled" attributeCaptureEnabled="attribute-capture-enabled" groupAssertionsEnabled="group-assertions-enabled-flag" groupAssertionsSAMLEnabled="group-assertions-saml-enabled-flag" groupAssertionsOIDCEnabled="group-assertions-oidc-enabled-flag" groupAssertionsConnectedAppsEnabled="group-assertions-connected-apps-enabled-flag" groupSetsEnabled="group-sets-enabled-flag" recycleBinEnabled="recycle-bin-enabled-flag" /> </site></tsResponse>Response Body Details:
- userQuota,storageQuota, and tiered capacity (tierCreatorCapacity,tierExplorerCapacity,tierViewerCapacity) attributes are only present in the response body if those quotas have been set for the site being queried.
Version
Version 1.0 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400008 | Invalid revision history limit | The value for the revision history limit isn't an integer. |
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400004 | Invalid administrator mode | An administrator mode parameter was provided in the request with an invalid value. The valid values areContentOnly andContentAndUsers. |
| 400 | 400004 | Invalid state | A state parameter was provided in the request with an invalid value |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type wasn'tPUT. |
| 409 | 409001 | Site name conflict | The new site name in the request already belongs to an existing site. |
| 409 | 409002 | Site URL conflict | The new content URL in the request already belongs to an existing site. |
| 409 | 409004 | User quota and tiered capacity conflict | The request can't set both tiered capacity attributes anduserQuota. One or the other must be null. |
| 409 | 409004 | License limit exceeded | The request can't set tiered capacity attributes oruserQuota values that are larger than the number of active licenses configured for the site. |
| 409 | 409004 | Administrator mode or user quota conflict | The request can't setadminMode toContentOnly and also specify auserQuota value. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 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 as3.27. For more information, seeREST 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 unified access token or connected app. For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud), orTableau Cloud connected app scopes(Link opens in a new window) orTableau Server connected apps scopes(Link opens in a new window).Available in API 3.20 (Tableau Cloud June 2023 / Tableau Server 2023.3.
Tableau Server Request
Update the attributes of a subscription task on a server schedule on Tableau Server.
For Tableau Cloud, seeTableau Cloud Request.
<tsRequest> <subscription subject="subscription-subject" attachImage="attach-image-flag" attachPdf="attach-pdf-flag" pageOrientation="page-orientation" pageSizeOption="page-size-option" suspended="suspended-flag"> <schedule <content sendIfViewEmpty="send-view-if-empty-flag" /> </subscription></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" } }}
Attribute Values
| new-subscription-subject | (Optional) A new subject for the subscription. |
| attach-image-flag | (Optional) Setting this If subscriptions to attachments are disabled in Tableau server or site settings,then making a request that sets |
| attach-pdf-flag | (Optional) Setting this If subscriptions to attachments are disabled in Tableau server or site settings,then making a request that sets |
| page-orientation | (Optional) The orientation of the pages produced whenattach-pdf-flagistrue. The value can bePortrait orLandscape. If this parameter is not present the page orientation will default toPortrait. |
| page-size-option | (Optional) The type of page produced, which determines the page dimensions whenattach-pdf-flag istrue. The value can be:A3,A4,A5,B5,Executive,Folio,Ledger,Legal,Letter,Note,Quarto, orTabloid. If this parameter is not present the page type will default toLetter. |
| suspended-flag | (Optional boolean) If |
| new-schedule-id | (Optional) The ID of a server schedule to associate this subscription with. To determine what schedules are available,callList Server Schedules. The type of the schedule must beSubscription. |
| send-view-if-empty-flag | (Optional) Applies to views only. Iftrue, an image is sent even if the view specified in a subscription is empty. Iffalse, 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 theyhave permission to create. For details, seeCreate Server Subscription.
Response Code
200
Response Body
<tsResponse> <subscription subject="subscription-subject" suspended="suspended-flag" pageOrientation="page-orientation" pageSizeOption="page-size-option" > <content type="content-type" sendIfViewEmpty="send-view-if-empty-flag"/> <schedule name="schedule-name" /> <user name="user-name" /> </subscription></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" } }}Version
Version 2.3 and later. For more information, seeREST 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 notWorkbook orView. |
| 400 | 400069 | Invalid schedule type | The schedule type is notSubscription. |
| 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 notPUT. |
For more information, seeHandling Errors.
Tableau Cloud Request
Update the attributes of a subscription task and its frequency on Tableau Cloud.
For Tableau Server, seeTableau 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| task-luid | The LUID of the extract refresh task. UseQuery subscriptions to find task IDs by subscription subject or user. |
Request Body
<tsRequest> <subscription subject="finance report" attachImage="true" attachPdf="true" pageOrientation="true" pageSizeOption="Folio" suspended="false" message="Daily finance report"> <content type="Workbook" sendIfViewEmpty="false"/> <user/> </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>
{ "subscription": { "subject": "finance report", "attachImage": "true", "attachPdf": "true", "pageOrientation": "true", "pageSizeOption": "Folio", "suspended": "false", "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 allschedule attributes arerequired 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 If subscriptions to attachments are disabled in Tableau server or site settings,then making a request that sets |
subscription attachPdf | boolean: Setting this If subscriptions to attachments are disabled in Tableau server or site settings,then making a request that sets |
subscription pageOrientation | enumeration: The orientation of the pages produced whenattach-pdf-flagistrue. The value can bePortrait orLandscape. If this parameter is not present the page orientation will default toPortrait. |
subscription pageSizeOption | enumeration: The type of page produced, which determines the page dimensions whenattach-pdf-flag istrue. The value can be:A3,A4,A5,B5,Executive,Folio,Ledger,Legal,Letter,Note,Quarto, orTabloid. If this parameter is not present the page type will default toLetter. |
subscription message | string: The text body of the subscription email message. |
subscription suspended | boolean: Iftrue, the subscription is disabled, meaning it won't run until it's enabled using theUpdate Subscription method orResume Subscription in the web UI. Iffalse, the subscription is enabled. |
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, orView to create a subscription for a view. |
content sendIfViewEmpty | boolean: Applies to views only. Iftrue, an image is sent even if the view specified in a subscription isempty. Iffalse, 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 task. Valid values include:
| ||||||||||
frequencyDetails start | (Required to create subscription) time: If the schedule frequency isDaily, Weekly, or Monthly, thenstartis the time of day on which scheduled jobs should run. If the frequency isHourly, thenstart is the beginning of thetime range during which jobs should be started. The valid format isHH:MM:SS. | ||||||||||
frequencyDetails end | (Required to create subscription) time: If the schedule frequency is | ||||||||||
interval{interval type} | (Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in thestart andend values of thefrequencyDetails of theschedule. The type and valid values foran interval expression depend on the declaredfrequency of theschedule as follows:
|
cURL Request Example
curl --location --request PUT "qa-near.tsi.lan/api/3.27/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 type="Workbook" sendIfViewEmpty="false"/><user/> </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
<tsResponse> <subscription subject="finance report" attachImage="true" attachPdf="true" pageOrientation="true" pageSizeOption="Folio" message="daily finance report"> <content type="Workbook" sendIfViewEmpty="false"/> <user/> </subscription> <schedule 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>{ "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 betweenstart andend times are not increments of one hour,this error will result. |
For more information, seeHandling 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 as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| table-id | The unique ID of the table asset. |
Request Body
<tsRequest> <table isCertified="certification-status" certificationNote="certification-note" description="new-description-value"> <contactapi-placeholder">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:
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 throughData 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
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:tables:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 name="Zoning.shp" description="Contact Susan Nguyen (database admin) for changes." isEmbedded="true" isCertified="false"><site/> </table></tsResponse>Version
Version 3.5 and later. For more information, seeREST 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:tableau:extensions_server_settings:update
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/settings/extensions
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
Request Body
<tsRequest>
<extensionsServerSettings>
<extensionsGloballyEnabled>true</extensionsGloballyEnabled>
<blockList>https://test.com</blockList>
</extensionsServerSettings>
</tsRequest>{
"extensionsServerSettings": {
"extensionsGloballyEnabled": "true",
"blockList": "https://test.com"
}
}Request Attributes
extensionsEnabled | Required. Boolean. If |
blocklist | (Optional) Array. A list of domains that are not allowed to serve extensions to the Tableau Server. Domains are in the form of (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.27/settings/extensions" --header "Content-Type: application/xml" --header "X-Tableau-Auth: YqB9_MHoTHO26HGsFBFEBg|bQDOIH4MsqFGvUDYTrRYh633vrZHBt6d|a946d998-2ead-4894-bb50-1054a91dcab3" --data "
Response Code
200
Response Body
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad Request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 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, seeHandling 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:tableau:extensions_site_settings:update
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-luid/settings/extensions
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
Request Body
<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>{
"extensionsSiteSettings": {
"extensionsEnabled": "true",
"useDefaultSetting": "false",
"safeList": {
"url": "http://localhost:9123/Dynamic.html",
"fullDataAllowed": "true",
"promptNeeded": "true"
}
}
}Request Attributes
extensionsEnabled | Required. Boolean. Iftrue, 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 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 totrue 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 totrue to give users the ability to allow or deny the extension from running. Set tofalse to hide this prompt from users, allowing the extension to run immediately. |
cURL Request Example
curl --location --request PUT http://MY-SERVER/api/3.27/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 "
Response Code
200
Response Body
<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>{
"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, seeHandling Errors.
Update User
Modifies information about the specified user.
Tableau Server
If Tableau Server is configured to use local authentication, you can update the user's name, email address, password, or site role.
If Tableau Server is configured to use Active Directory for authentication, you can change the user's display name (full name), email address, and site role. However, if you synchronize the user with Active Directory, the display name and email address will be overwritten with the information that's in Active Directory.
Tableau Cloud
For Tableau Cloud, you can update the site role for a user, but you cannot update or change a user's password, user name (email address), or full name.
URI
PUT /api/api-version/sites/site-id/users/user-id
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST 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"identityPoolName="identity-pool-name"idpConfigurationId="idp-configuration-id" /></tsRequest>
{"user": { "fullName":"new-full-name", "email":"new-email", "password":"new-password", "siteRole":"new-site-role", "authSetting":"new-auth-setting", "identityPoolName":"identity-pool-name", "idpConfigurationId":"idp-configuration-id" }}
Attribute Values
Any combination of the elements inside the<user> element is valid. Only those elements present will result inupdates 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 for the Tableau Server user. Starting in API 3.26 (July 2025), the email address where the Tableau Cloud user can receive notifications. If no value is provided, Tableau Cloud uses the |
| 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,orViewer. Note: Only a user in theServerAdministratorsite role can use the REST API to add or remove another user from theServerAdministrator site role. Users in theServerAdministrator site role can only be moved to theCreator site role if one or moreCreator licenses have been activated on the server; otherwise these users can only be moved to thePublisher site role. This method only supports theServerAdministrator site role in API 2.8 and later. |
| new-auth-setting | (Optional) The authentication type for the user. Tableau Server TheauthSetting attribute only applies when updating users on sites with site-specific SAML-enabled settings. Tableau Cloud The ability to create and enable multiple authentication methods simultaneously was introduced in API 3.25 (January 2025). As a result of this capability, consider the following:
Notes: You can assign the following values for theauthSetting attribute:
|
| identity-pool-name | (Optional, Tableau Server only) When identity pools are configured, the name of the identity pool. Starting in API 3.19, include the identity pool name when identity pools are configured and you need to add a user to an identity pool that uses the local identity store and OIDC authentication. For more information, seeIdentity Pools Methods. |
| idp-configuration-id | (Optional, Tableau Cloud only) The configuration to assign for user authentication. Added in API 3.25 (January 2025). To find theidpConfigurationId attribute value, use theList Authentication Configurations for Site method. Notes:
|
Permissions
This method can only be called by server administrators or site administrators.In addition, site administrators have some limitations in what changesthey can make to users:
- Site administrators cannot set thefullName value.
- On Tableau Server, site administrators can change theemailandpassword values only if the caller isa 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 thesiteRolevalue only if the site is configured to allow site administrators to add and remove site users. Site administrators on Tableau Cloud can change thesiteRole value because they have permission to add and remove site users. Starting in API 3.26 (July 2025), site administrators can update a user's email address that is different from the user's username. This email address is for receiving notifications only.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:users:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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"identityPoolName="identity-pool-name"idpConfigurationId="idp-configuration-id" /></tsResponse>Version
Version 1.0 and later. For more information, seeREST 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 | Theemail attribute does not contain a valid email address. |
| 400 | 400003 | Bad request | The user authentication settingServerDefault is not supported for you site. Try again usingTableauIDWithMFA instead. |
| 400 | 400012 | Bad request | The user cannot be assigned the Unlicensed role because they are still a member of a group that hasa 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 thesiteRole attribute must beCreator,Explorer,ExplorerCanPublish,ServerAdministrator,SiteAdministratorExplorer,SiteAdministratorCreator,Unlicensed,orViewer. |
| 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 notPUT. |
| 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, seeHandling Errors.
Update User Notification Preferences
Updates user notifications preferences to enabled or disabled on the specified site. For more information about notifications, seeManage 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 as3.27. For more information, seeREST 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) Iftrue, the specified site notifications will be on. Iffalse, 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, andslack. |
| 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.
Access Scope
Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
tableau:user_notifications:updateFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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, seeREST 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 notPATCH. |
For more information, seeHandling 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
Updates a virtual connection's name, owner, project, or certification status.
Version:Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:RequiresTableau Data Management(Link opens in a new window).
Permissions:You must have theOverwrite permission for the virtual connection and your site role must be at leastCreator. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:virtual_connections:update
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-luid/virtualconnections/virtualconnection-luid
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| virtualconnection-luid | The LUID for the virtual connection. |
Request Body
(Use the icon in the top right corner to copy the text.)
<tsRequest> <virtualConnection name="virtualconnection-name" isCertified="certified-flag" certificationNote="certification-message"> <project/> <owner/> </virtualConnection></tsRequest>
(Use the icon in the top right corner to copy the text.)
{ "virtualConnection": { "name": "virtualconnection-name", "isCertified": "certified-flag", "certificationNote": "certification-message", "project": { "id": "project-luid" }, "owner": { "id": "owner-luid" } }}
Request Attributes
| virtualconnection-name | The name of the virtual connection. |
| certification-flag | Boolean. If true, the virtual connection is certified. If false, it won't. |
| certification-message | The certification label's message. |
| project-luid | The LUID of the project the virtual connection is located in. |
| owner-luid | The LUID of the user that owns the virtual connection. |
Request attributes that are different from the virtual connection's current properties result in updating the virtual connection.
cURL Request Example
(Use the icon in the top right corner to copy the text.)
curl --request PUT 'http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml
Contents of data.xml.
(Use the icon in the top right corner to copy the text.)
<tsRequest> <virtualConnection name="Batters" isCertified="true" certificationNote="Approved by Marketing"> <project/> <owner/> </virtualConnection></tsRequest>
Response Code
200
Response Body
<tsResponse> <virtualConnection isCertified="certified-flag" name="virtualconnection-name"> <project/> <owner/> </virtualConnection></tsResponse>{ "virtualConnection": { "project": { "id": "project-luid" }, "owner": { "id": "owner-luid" }, "id": "virtualconnection-luid", "isCertified": certified-flag, "name": "virtualconnection-luid" }}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400203 | Generic error | An unknown error occurred. |
| 403 | 403004 | User not authorized to change virtual connection | Check to make sure the user has the required permissions. |
| 403 | 403176 | User not authorized to change virtual connection's owner | Check to make sure the user has the required permissions. |
| 403 | 403177 | User not authorized to move assets into the target project. | Check to make sure the user has the required permissions. |
| 403 | 403178 | User not authorized to move the virtual connection | Check to make sure the user has the required permissions. |
| 404 | 404049 | Virtual connection not found | Check the virtual connection LUID. |
| 409 | 409124 | A virtual connection with the chosen name already exists in the project. | Try a different virtual connection name. |
For more information, seeHandling Errors.
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:RequiresTableau 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:tableau:virtualconnectionconnections:update
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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, callList 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
<tsResponse>
<virtualConnectionConnections>
<connection
id="connection-id"
serverAddress="server-address"
serverPort="port-number"
userName="connection-user-name"
password="password"/>
</virtualConnectionConnections>
</tsResponse>
{
"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 notPUT. |
For more information, seeHandling Errors.
Update Workbook
Modifies an existing workbook, allowing you to change the owner or project that the workbook belongs to and whether the workbookshows views in tabs. Updated workbooks can optionally be marked to appear in the recently viewed list.
You can manageData Freshness Policy(Link opens in a new window)for a workbook, and enableView 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 haveWritepermission for the workbook and for the project.Tableau server and site administrators can change thedataAccelerationConfig accelerationEnable setting for a workbook.Workbook owners can change the setting if thesite 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
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-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 as3.27. For more information, seeREST 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: IfincludeViewAccelerationStatus=true then the list of views and the acceleration status of each view will be returned. |
Request Body
<tsRequest>
<workbook
name="Finance"
showTabs="false"
recentlyViewed="false"
encryptExtracts="false"
description="The finance workbook.">
<project />
<owner />
<views>
<view/>
</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>{
"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 onData Freshness Policy(Link opens in a new window) andView Acceleration(Link opens in a new window):
- Data Freshness Policy and View Acceleration are independent features.
- If a policy is set without view accelerationfor a workbook, then onlyquery 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 accelerationwill not impact the policy unless the update explicitly changes that.
- If a workbook has acceleratedviews enabled, but does not have a data freshness policy explicitly set for it, data will be refreshed onthe 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 workbookis set to refresh data more frequently than every 2 hours, refreshes for a view after the 12th one will not trigger thecomputation that accelerates that view until the first refresh of the next day.
- The preceding example shows the
freshAtdata freshness policy option.ThefreshEveryoption is illustrated in the following Attribute Values section.
Attribute Values
workbook name | (Optional) New name for the workbook being updated. | ||||
workbook showTabs | (Optional) Specifytrue to have the updated workbook show views in tabs; otherwise,false. The default isfalse. | ||||
workbook recentlyViewed | (Optional) Set this value totrue to have the updated workbook show in the site's recently viewed list.The default isfalse. Once the flag is set totrue, setting it tofalse will have no effect. When enough views or workbooks have populated the recently viewed list, theoldest item will fall off the list and itsrecently-viewed-flag will revert tofalse. | ||||
workbook encryptExtracts | (Optional)true to encrypt the extracts orfalse to not encrypt extracts. For more information, seeExtract and Encryption Methods. | ||||
workbook description | (Optional) Starting in API 3.20, 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: Iftrue, accelerate the specified view(s). Default isfalse. | ||||
dataAccelerationConfig accelerateNow | (Optional) Boolean: Iftrue, make view acceleration available as soon as possible.Default isfalse. Note, theview object in the response (visible by using the?includeViewAccelerationStatus=true query parameter) contains theaccelerationStatus attribute, which can have the following values:
| ||||
view id | (Optional) LUID: The LUID of a view being accelerated. If no views are listed in the request then allviews in the workbook will be accelerated. | ||||
dataFreshnessPolicy option | (Optional) Enum: The data freshness policy(Link opens in a new window) mode forscheduling refreshment of the workbook data specified in the request. A valid value is one of:
| ||||
freshAtSchedule frequency | (Optional) Enum: The interval of workbook data refresh. A valid value is one of:
| ||||
freshAtSchedule time | (Optional) Time inHH:MM:SS: The time of day that workbook data will be refreshed, inincrement of 15 minutes. Minutes must end in 00, 15, 30, or 45. for instancetime="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, thenthe 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 thevalue specified infreshAtSchedule frequency.
If the schedule frequency is
The interval expression is
The interval expression is | ||||
| freshEverySchedule frequency | (Optional) Enum: The time unit used for the cadence of view acceleration data refreshes. The count of the specifiedunit that occurs between refreshes is determined byfreshEverySchedule value.A valid value is one of:
| ||||
| freshEverySchedule value | (Optional) Integer: The quantity of frequency units between view acceleration data refreshes. For instance,to specify a refresh every 4 hours, thedataFreshnessPolicy would look like: | ||||
| |||||
With the exception ofdataFreshnessPolicy 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.
ThedataFreshnessPolicy 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, theid attribute must be included; other attributes of the<project> element are ignored.
If the<owner> element is included, theid 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
<tsResponse>
<workbook
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 name="Default"/>
<location type="Project" name="Default"/>
<owner name="test"/>
<tags/>
<views>
<view
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>{
"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"
}
}
}
}
}
}Thedatetime-created anddatetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).
A response for thedataFreshnessPolicy segment with theFreshEvery option configured for weekly refreshes, would look like:
| XML | JSON |
Copy | Copy n |
Version
Version 2.0 and later. For more information, seeREST 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 haveWrite 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 haveWrite 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 notPUT. |
For more information, seeHandling Errors.
Update Workbook Connection
Updates the server address, port, authentication type, 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. To update specific connections in a workbook containing multiple connections, seeUpdate Data Source Connections(Link opens in a new window).
Version:Available in API 2.0 (Tableau Cloud and later).
License:No additional license required.
Permissions:Users who are not server administrators or site administrators can update permissions only for a workbook for which they have theWritecapability (either explicitly or implicitly). Only users with administrator permissions can enable or disable query tagging. Permissions Overview(Link opens in a new window)
Access Scope:tableau:workbooks:update
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
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 as3.27. For more information, seeREST 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"authenticationType="auth-type"userName="connection-username" password="connection-password" embedPassword="embed-password" queryTaggingEnabled="query-tagging-enabled" /></tsRequest>>
{ "connection": { "serverAddress": "server-address", "serverPort": "port", "authenticationType": "auth-type", "userName": "connection-username", "password": "connection-password", "embedPassword": "embed-password", "queryTaggingEnabled": "query-tagging-enabled" }}
Attribute Values
| server-address | The new server for the connection. |
| port | The new port for the connection. |
| connection authenticationType | Added in version 3.27. The new authentication type for the connection. Standard values:
Connector-specific values:
If you are unsure of the value for authenticationType for the target connection, there are two ways to determine the value. First, if you have a data source or workbook that is currently using the target authentication type, you can query for it using the REST API methodsQuery Datasource Connections(Link opens in a new window) orQuery Workbook Connections(Link opens in a new window), which returns the authentication type string in the response. Alternatively, you can inspect the |
| 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 | Starting with API 3.23 (Tableau Cloud June 2024 / Server 2024.2), the For API 3.22 (Tableau Cloud February 2024 / Server 2024.1) or earlier: If For more information on query tagging, seeUnderstand Workbook Impact on Your Database Using Query Tagging(Link opens in a new window). |
Any combination of the attributes inside the<connection> element is valid. If no attributes are included, no update is made.
cURL Request Example
curl --location --request PUT "/api/api-version/sites/site-id/workbooks/workbook-id/connections/connection-id" \ --header "Content-Type: application/xml" \ --header "X-Tableau-Auth;" \ --data "{ 'connection': { 'serverAddress': 'server-address', 'serverPort': 'port', 'authenticationType': 'auth-type', 'userName': 'connection-username', 'password': 'connection-password', 'embedPassword': 'embed-password', 'queryTaggingEnabled': 'query-tagging-enabled' } }"
Response Code
200
Response Body
<tsResponse> <connectionapi-placeholder">connection-id"authenticationType="auth-type"serverAddress="server-address" serverPort="port"userName="connection-user-name"queryTaggingEnabled="query-tagging-enabled" /></tsResponse>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 haveWrite 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 notPUT. |
For more information, seeHandling 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 selectingRefresh 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 theRunNow setting for the site. For more information, seeTableau 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 as3.27. For more information, seeREST 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).
tableau:tasks:runFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
202
Response Body
<tsResponse> <job mode="Asynchronous" type="RefreshExtract" createdAt="date-time"> <extractRefreshJob> <workbook name="workbook-name" /> </extractRefreshJob> </job></tsResponse>Version
Version 2.8 and later. For more information, seeREST 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 notPOST. |
| 409 | 409093 | Operation already in Queue | The extract refresh job is already in the queue. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/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 mode="Asynchronous" type="RefreshExtract" createdAt="2017-12-06T22:58:52Z"> <extractRefreshJob> <workbook name="Regional" /> </extractRefreshJob> </job></tsResponse>Update Workbook Thumbnail Images
Updates a workbook's thumbnail images.
The method adds a task to the backgrounder queue. Depending upon the length of the queue, the task might not run immediately. The method returns information about the backgrounder job responsible for running the task, including thejob id that can be used with theQuery Job method.
Version: Available in API 3.27 (Tableau Cloud December 2025 / Server 2025.3) and later.
License: No additional license required.
Permissions: Server administrators, site administrators, or workbook owner
Access Scope:tableau:tasks:run
- For more information, seeVersions(Link opens in a new window),Permissions(Link opens in a new window),Access scopes for UATs(Link opens in a new window) (Cloud),and access scopes forCloud(Link opens in a new window),Server-Windows,(Link opens in a new window) orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-id/workbooks/workbook-id/refreshThumbnails
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the workbook. |
| workbook-id | The ID of the workbook. |
Request Body
None
cURL Request Example
curl -X PUT "https://MY-SERVER/api/3.27/sites/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/workbooks/08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6/refreshThumbnails" -H "X-Tableau-Auth: a1B2c3D4e5F6g7H8i9J0kL|a1B2c3D4e5F6g7H8i9J0kL1m2N3o4P5q|12345678-90ab-4cde-8f01-234567890abc"Response Code
202
Response Body
<tsResponse> <jobapi-placeholder">job-id" mode="Asynchronous" type="RefreshThumbnails" createdAt="date-time"> <thumbnailsRefreshJob> <workbookapi-placeholder">workbook-id" name="workbook-name" /> </thumbnailsRefreshJob> </job></tsResponse>{ "job": { "thumbnailsRefreshJob": { "workbook": { "id": "workbook-id", "name": "workbook-name" } }, "id": "job-id", "mode": "Asynchronous", "type": "RefreshThumbnails", "createdAt": "date-time" }}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Generic error | An unknown error occurred. The content of the request body may be missing or incomplete, or may contain malformed XML. |
| 403 | 403179 | Permissions error | The user calling the method isn't a site administrator, server administrator, or owner of the workbook. |
| 404 | 404006 | Workbook not found | The workbook LUID is invalid, or the user doesn't have permission to read the workbook. |
| 500 | 500000 | Internal server error | The server was unable to create the job. |
For more information, seeHandling Errors.
Upload Data Source Encrypted Keychain
Uploads the encrypted version of the embedded credentials. This method will only work if the credentials are encrypted with the latest public key used to link the source Tableau Server with the destination Tableau Cloud or Tableau Server site.
Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, seeMigrate Workbooks and Data Sources with Embedded Credentials.
Version:Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:No additional license required.
Permissions:This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:embedded_credentials:upload
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-luid/datasources/datasource-luid/applykeychain
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| datasource-luid | The LUID of the data source to download the encrypted keychain from. |
Request Body
<tsRequest> <associatedUserLuidMapping/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain> </encryptedKeychainList></tsRequest>
{"associatedUserLuidMapping": [],"encryptedKeychainList": { "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=" }}
Request Attributes
associatedUserLuidMapping | (Required) The user IDs from the source site mapped to destination site user IDs. |
encryptedKeychainList | (Required) List of encrypted keychains from the source Tableau Server. |
cURL Request Example
curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/applykeychain" --header "Content-Type: application/xml" --header "X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86" --data "<tsRequest> <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace> <destinationSiteLuid>9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</destinationSiteLuid> <destinationServerUrl>http://example.com</destinationServerUrl> </tsRequest>"
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. |
| 403 | 403054 | Unauthorized Access | A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404004 | Data source not found | The data source ID in the URI doesn't correspond to an existing data source. |
| 405 | 405000 | Invalid request method | Request type was notPUT. |
For more information, seeHandling Errors.
Upload User Credentials
Uploads user credentials to a site on a destination Tableau Cloud or Tableau Server.
Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, seeMigrate Workbooks and Data Sources with Embedded Credentials.
Version:Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:No additional license required.
Permissions:This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:oauth_credentials:upload
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-luid/users/user-luid/uploadSavedCreds
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| user-luid | The LUID of the user whose credentials you want to upload. |
Request Body
<tsRequest> <associatedUserLuidMapping/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y= <encryptedKeychain> </encryptedKeychainList></tsRequest>
{ "associatedUserLuidMapping": [], "encryptedKeychainList": { "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=" }}Request Attributes
associatedUserLuidMapping | (Required) The user IDs from the source site mapped to destination site user IDs. |
encryptedKeychainList | (Required) List of encrypted keychains from the source Tableau Server. |
cURL Request Example
curl --location --request GET "https://example.com/api/3.24/sites/a946d998-2ead-4894-bb50-1054a91dcab3/users/6ae4a163-d073-4ab2-9668-954bab4b029e/uploadSavedCreds" --header "Content-Type: application/json" --data "<associatedUserLuidMapping/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y= <encryptedKeychain> </encryptedKeychainList>"
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. |
| 403 | 403054 | Unauthorized Access | A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
| 405 | 405000 | Invalid request method | Request type was notPUT. |
For more information, seeHandling Errors.
Upload Workbook Encrypted Keychain
Uploads the encrypted version of the embedded credentials. This method will only work if the credentials are encrypted with the latest public key used to link the source Tableau Server with the destination Tableau Cloud or Tableau Server site.
Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, seeMigrate Workbooks and Data Sources with Embedded Credentials.
Version:Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later.Version Overview(Link opens in a new window)
License:No additional license required.
Permissions:This method can only be called by Tableau Cloud and Tableau Server admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:embedded_credentials:upload
- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-luid/workbooks/workbook-luid/applyKeychain
URI Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID for the site. |
| workbook-luid | The LUID of the workbook to download the encrypted keychain from. |
Request Body
<tsRequest> <associatedUserLuidMapping/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain> </encryptedKeychainList></tsRequest>
{"associatedUserLuidMapping": [],"encryptedKeychainList": { "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=" }}
Request Attributes
associatedUserLuidMapping | (Required) The user IDs from the source site mapped to destination site user IDs. |
encryptedKeychainList | (Required) List of encrypted keychains from the source Tableau Server. |
cURL Request Example
curl --location 'https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/applykeychain' \--header 'Content-Type: application/xml' \--header 'X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86' \--data '<tsRequest> <associatedUserLuidMapping/> <encryptedKeychainList> <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain> </encryptedKeychainList></tsRequest>'
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. |
| 403 | 403054 | Unauthorized Access | A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404006 | Workbook not found | The workbook ID in URI doesn't correspond to an existing workbook. |
| 405 | 405000 | Invalid request method | Request type was notPUT. |
For more information, seeHandling Errors.