API Reference—All Methods

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

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

API Method Categories

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

Analytics Extensions Settings Methods
Add analytics extension connection to site Adds an analytics extensions connection for an external service to a site.
Delete analytics extension connection from site Deletes a specific analytics extension connection for an external service from a site.
Enable or disable analytics extensions on server
- Not available for Tableau Cloud
Enables or disables analytics extensions on a server.
Get analytics extension details Get the details of a specified analytics extension connection to an external service.
Get current analytics extension for workbook Gets basic details, including connection type and name, of the analytics extension connection to an external service that the specified workbook is currently using.
Get enabled state of analytics extensions on server
- Not available for Tableau Cloud
Gets the enabled/disabled state of analytics extensions on a server.
Get enabled state of analytics extensions on site Gets the enabled/disabled state of analytics extensions on a site.
List analytics extension connections of workbook Lists basic details of each analytics extension connection available for a specified workbook, including connection type and name.
List analytics extension connections on site Lists a site's analytics extension connections for external services.
Remove current analytics extension connection for workbook Remove the currently used analytics extension connection to an external service from the specified workbook. The connection remains configured, and is available for further usage by the workbook.
Update analytics extension connection of site Updates the details of specified analytics extension connection for an external service to a site.
Update analytics extension for workbook Updates the analytics extension connection to external service currently used by a workbook.
Update enabled state of analytics extensions on site Enables or disables analytics extensions on a site.
Ask Data Lens Methods - Retired in API 3.22
Create ask data lens - Retired in API 3.22 Create an ask data lens.
Delete ask data lens - Retired in API 3.22 Delete an ask data lens.
Get ask data lens - Retired in API 3.22 Get the details of the specified ask data lens.
Import ask data lens - Retired in API 3.22 Import an existing ask data lens on a server to a site, and optionally transform the metadata of the lens in the process.
List ask data lenses in site - Retired in API 3.22 Returns a list of ask data lenses in a site.
Authentication Methods
List Personal Access Tokens
- Not available for Tableau Server.
List all personal access tokens (PATs). If you're a site admin, list PATs of a user when you are the site admin on all sites that the PAT owner is a member of.
Revoke Administrator Personal Access Tokens
- Not available for Tableau Cloud.
Revokes all personal access tokens(Link opens in a new window) (PATs) created by server administrators. This method is not available for Tableau Cloud.
Revoke Personal Access Token
- Not available for Tableau Server.
Revoke a personal access token (PAT). If you're a site admin, you can revoke a users PAT owhen you are the site admin on all sites that the PAT owner is a member of.
Sign In Signs you in as a user on the specified site on Tableau Server or Tableau Cloud.
Sign Out Signs you out of the current session. This call invalidates the authentication token that is created by a call to Sign In.
Switch Site
- Not available for Tableau Cloud.
Switches you onto another site without having to provide a user name and password again.
Connected App Methods
Create Connected App Create a connected app.
Create Connected App Secret Generate a secret for a connected app.
Delete Connected App Permanently remove a connected app.
Delete Connected App Secret Permanently remove a secret associated with a connected app.
Delete EAS
- Not available for Tableau Server.
Delete a registered external authorization server (EAS).
Get Connected App Query a connected app by its ID.
Get Connected App Secret Query a connected app secret and the token value using the connected app's ID.
List All Registered EAS
- Not available for Tableau Server.
Get all external authorization servers (EASs) registered to a site.
List Connected Apps Query all connected apps configured on a site.
List Registered EAS
- Not available for Tableau Server.
Get an external authorization server (EAS) registered to a site.
Register EAS
- Not available for Tableau Server.
Create a connected app with OAuth 2.0 trust by registering an external authorization server (EAS) to a site.
Update Connected App Update a connected app.
Update EAS
- Not available for Tableau Server.
Update a connected app with OAuth 2.0 trust.
Content Exploration Methods
Get batch content usage statistics
- Not available for Tableau Server
Gets usage statistics for multiple content items. The batch of can include multiple content types.
Get content search results Searches across all supported content types for objects relevant to the search expression specified in the querystring of the request URI.
Get Content Suggestions Returns a specified number of suggestions for auto-completion of user input as they type. You can specify content types of suggestions and prioritize recently viewed content.
Get usage statistics for content item
- Not available for Tableau Server
Gets the usage statistics for a Tableau content item, specified by LUID and content type, such as workbook, datasource, or flow.
Dashboard Extensions Settings Methods - Retired in API 3.21
Allow dashboard extension on site - Retired in API 3.21 Adds a dashboard extension to the safe list of the site you are signed into.
Block dashboard extension on server - Retired in API 3.21
- Not available for Tableau Cloud
Adds a dashboard extension to the block list of a server.
Disallow dashboard extension on site - Retired in API 3.21 Deletes a specific dashboard extension from the safe list of the site you are signed into.
Get allowed dashboard extension on site - Retired in API 3.21 Gets the details of a specific dashboard extension on the safe list of the site you are signed into.
Get blocked dashboard extension on server - Retired in API 3.21
- Not available for Tableau Cloud
Gets the details of a specific dashboard extension on the blocked list of a server.
List allowed dashboard extensions on site - Retired in API 3.21 Lists the dashboard extensions on the safe list of the site you are signed into.
List blocked dashboard extensions on server - Retired in API 3.21
- Not available for Tableau Cloud
Lists the dashboard extensions on the blocked list of a server.
List dashboard extension settings of site - Retired in API 3.21 Lists the dashboard extension settings of the site you are signed into.
List settings for dashboard extensions on server - Retired in API 3.21
- Not available for Tableau Cloud
Lists the dashboard extension settings of a server.
Unblock dashboard extension on server - Retired in API 3.21
- Not available for Tableau Cloud
Deletes a specific extension from the block list of a server.
Update dashboard extension settings of site - Retired in API 3.21 Updates the settings for dashboard extensions for the site you are signed into.
Update dashboard extensions settings of server - Retired in API 3.21
- Not available for Tableau Cloud
Updates the settings for dashboard extensions of a server.
Update settings for allowed dashboard extension on site - Retired in API 3.21 Updates the settings of a specific dashboard extension in the safe list of the site you are signed into.
Data Sources Methods
Add Tags to Data Source Adds one or more tags to the specified data source.
Delete Data Source Deletes the specified data source from a site. When a data source is deleted, its associated data connection is also deleted. Workbooks that use the data source are not deleted, but they will no longer work properly.
Delete Tag from Data Source Deletes a tag from the specified data source.
Download Data Source Downloads a data source in .tdsx format.
Download Data Source Revision Downloads a specific version of a data source prior to the current one in .tdsx format. To down load the current version of a data source use the Download Data Source method.
Get Data Source Revisions Returns a list of revision information (history) for the specified data source.
Publish Data Source Publishes a data source on the specified site, or appends data to an existing data source. To make other changes to a published data source, call Update Data Source or Update Data Source Connection.
Query Data Source Returns information about the specified data source.
Query Data Source Connections Returns a list of data connections for the specified data source.
Query Data Sources Returns a list of published data sources on the specified site, with optional parameters for specifying the paging of large results. To get a list of data sources embedded in a workbook, use the Query Workbook Connections method.
Remove Data Source Revision Removes a specific version of a data source from the specified site.
Update Data in Hyper Connection Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from a live-to-Hyper connection, where the data source has multiple connections.
Update Data in Hyper Data Source Incrementally updates data (insert, update, upsert, replace and delete) in a published data source from a live-to-Hyper connection, where the data source has a single connection.
Update Data Source Updates the owner, project or certification status of the specified data source.
Update Data Source Connection Updates the server address, port, username, or password for the specified data source connection.
Update Data Source Now Runs an extract refresh on the specified data source.
Extract and Encryption Methods
Create an Extract for a Data Source Create an extract for a data source in a site. Optionally, encrypt the extract if the site and workbooks using it are configured to allow it.
Create Cloud Extract Refresh Task
- Not available for Tableau Server.
Creates a custom schedule for an extract refresh on Tableau Cloud.
For Tableau Server, see Add data source to server schedule and Add workbook to server schedule.
Create Extracts for Embedded Data Sources in a Workbook Create extracts for all embedded data sources of a workbook. Optionally, encrypt the extracts if the site and workbook using them are configured to allow it.
Decrypt Extracts in a Site Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).
Delete Extract Refresh Task Deletes the specified extract refresh task on Tableau Server or Tableau Cloud.
Delete Extracts of Embedded Data Sources from a Workbook Delete all extracts of embedded data sources in a workbook.
Delete the Extract from a Data Source Delete the extract of a data source in a site.
Encrypt Extracts in a Site Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).
Get Extract Refresh Task Returns information about the specified extract refresh task.
List Extract Refresh Tasks in Server Schedule
- Not available for Tableau Cloud.
Returns a list of the extract refresh tasks for a specified server schedule on the specified site on Tableau Server.
List Extract Refresh Tasks in Site Returns a list of extract refresh tasks for the site.
Reencrypt Extracts in a Site Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see Extract Encryption at Rest(Link opens in a new window).
Run Extract Refresh Task Runs the specified extract refresh task.
Update Cloud extract refresh task
- Not available for Tableau Server.
Updates a custom schedule for an extract refresh task on Tableau Cloud.
For Tableau Server, see Update server schedule.
Favorites Methods
Add Data Source to Favorites Adds the specified data source to the user's favorites.
Add Flow to Favorites Adds the specified flow to the user's favorites.
Add Metric to Favorites - Retired in API 3.22 Adds the specified metric to the user's favorites.
Add Project to Favorites Adds the specified project to a user's favorites.
Add View to Favorites Adds the specified view to a user's favorites.
Add Workbook to Favorites Adds the specified workbook to a user's favorites.
Delete Data Source from Favorites Deletes the specified data source from the user's favorites. If the specified data source is not a favorite, the operation has no effect.
Delete Flow from Favorites Deletes the specified flow from the user's favorites. If the specified flow is not a favorite, the operation has no effect.
Delete Project from Favorites Deletes the specified project from the user's favorites. If the specified project is not a favorite, the operation has no effect.
Delete View from Favorites Deletes the specified view from user's favorites. If the specified view is not a favorite, the operation has no effect.
Delete Workbook from Favorites Deletes a workbook from a user's favorites. If the specified workbook is not a favorite of the specified user, this call has no effect.
Get Favorites for User Returns a list of favorite projects, data sources, views, workbooks, and flows for a user.
Organize Favorites Move an item to organize a user's favorites.
Flow Methods
Add Flow Permissions Adds permissions to the specified flow for a Tableau Server user or group. You can specify multiple sets of permissions using one call.
Add Flow Task to Server Schedule The Add Flow Task to Schedule method is renamed and retired for Tableau Cloud in API 3.22 (Tableau Cloud March 2024). It will remain available for Tableau Server only. For Tableau Cloud in March 2024, this method will be replaced with Create Flow Task with Custom Schedule method. Create Cloud Flow Task method.
Cancel Flow Run Cancels a flow run that is in progress.
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.
Publish Flow Publishes a flow on the specified site. To make other changes to a published flow, call Update Flow or Update Flow Connection.
Query Flow Returns information about the specified flow, including information about the project, owner, and output steps.
Query Flow Connections Returns a list of data connections for the specific flow.
Query Flow Permissions Returns a list of permissions for the specific flow.
Query Flows for a Site Returns the flows on a site. If the user is not an administrator, the method returns just the flows that the user has permissions to view.
Query Flows for User Returns the flows that the specified user owns in addition to those that the user has Read (view) permissions for.
Run Flow Now Runs the specified flow.
Run Flow Task Runs the specified flow run task.
Run Linked Task Now
- Available only with a Data Management license.
Runs the specified linked task.
Update Flow Updates the owner, project, of the specified flow.
Update Flow Connection Updates the server address, port, username, or password for the specified flow connection. The connection can be an input or an output connection.
Identity Pools Methods
Add User to Identity Pool
- Not available for Tableau Cloud.
Add a user to a specified identity pool.
Configure Identity Store
- Not available for Tableau Cloud
Configure a new local identity store to provision users.
Create Authentication Configuration
- Not available for Tableau Cloud
Create an instance of OpenID Connect (OIDC) authentication.
Create Identity Pool
- Not available for Tableau Cloud
Create an identity pool.
Delete Authentication Configuration
- Not available for Tableau Cloud
Delete an authentication instance.
Delete Identity Pool
- Not available for Tableau Cloud
Delete an identity pool.
Delete Identity Store
- Not available for Tableau Cloud
Delete an identity store.
Get Identity Pool
- Not available for Tableau Cloud
Get information about an identity pool.
List Authentication Configurations
- Not available for Tableau Cloud
List information about all authentication instances.
List Identity Pools
- Not available for Tableau Cloud
List all identity pools.
List Identity Stores
- Not available for Tableau Cloud
List information about all identity store instances used to provision users.
Remove User from Identity Pool
- Not available for Tableau Cloud.
Remove a user from a specified identity pool.
Update Authentication Configuration
- Not available for Tableau Cloud
Update an authentication instance.
Update Identity Pool
- Not available for Tableau Cloud
Update information about an identity pool.
Jobs, Tasks, and Schedules Methods
Add Data Source to Server Schedule
- Not available for Tableau Cloud.
Adds a task to refresh a data source to an existing server schedule on Tableau Server.
For Tableau Cloud, see Create 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.
Cancel Job Cancels a job specified by job ID. To get a list of job IDs for jobs that are currently queued or in-progress, use the Query Jobs method.
Create Server Schedule
- Not available for Tableau Cloud.
Creates a new server schedule on Tableau Server.
For Tableau Cloud, see Create Cloud Extract Refresh Task and Create subscription.
Delete Data Acceleration Task Deletes a data acceleration task.
Delete Server Schedule
- Not available for Tableau Cloud.
Deletes the specified schedule on Tableau Server.
For Tableau Cloud, see Delete Extract Refresh Task and Delete Subscription.
Get Data Acceleration Tasks in a Site Returns a list of data acceleration tasks for the site.
Get Server Schedule
- Not available for Tableau Cloud.
Returns detailed information about the specified server schedule on Tableau Server.
List Server Schedules
- Not available for Tableau Cloud.
Returns a list of flows, extract and subscription server schedules on Tableau Server. For each schedule, the API returns the name, frequency, priority, and other information.
Query Job Returns status information about an asynchronous process that is tracked using a job. This method can be used to query jobs that are used to do the following:.
Query Jobs Returns a list of active jobs on the specified site. To get details on a specific job, pass a job ID returned by this method to the Query Job method. To cancel an active job, pass a job ID returned by this method to the Cancel Job method.
Update Server Schedule
- Not available for Tableau Cloud.
Modifies settings for the specified server schedule, including the name, priority, and frequency details on Tableau Server.
For Tableau Cloud, see Update cloud extract refresh task and Update subscription .
Metadata Methods
Add (or Update) Quality Warning Trigger
- Available only with a Data Management license.
Create or update one or more quality warning triggers to monitor and display alerts for the following events: refresh failures on extract data sources and flow run failures on flows.
Add Data Quality Warning
- Available only with a Data Management license.
Add a data quality warning to a database, table, column, published data source, flow, virtual connection, or virtual connection table.
Add Database Permissions
- Available only with a Data Management license.
Add permissions to a database asset. To add permissions, the database asset must be associated with a published data source.
Add Default Database Permissions
- Available only with a Data Management license.
Adds default permission capabilities to a user or group for table resources in that database. These default permissions function as a permissions template for the database's table assets.
Add Table Permissions
- Available only with a Data Management license.
Add permissions to a table asset.
Add Tags to Column Add one or more tags to a column.
Add Tags to Database Add one or more tags to a database.
Add Tags to Table Add one or more tags to a table.
Batch Add or Update Data Quality Certifications
- Available only with a Data Management license.
Create or update one or more data quality certifications for different content and asset items.
Batch Add or Update Data Quality Warnings
- Available only with a Data Management license.
Add or update multiple data quality warnings on assets.
Batch Add Tags
- Available only with a Data Management license.
Add multiple tags to items that are different content and asset types.
Batch Delete Data Quality Warnings
- Available only with a Data Management license.
Delete multiple data quality warnings from assets.
Batch Delete Tags
- Available only with a Data Management license.
Delete multiple tags from items that are different content and asset types.
Create Label Category
- Available only with a Data Management license.
Creates a data label category.
Create or Update labelValue
- Available only with a Data Management license.
Creates a label value with the specified name if it doesn't exist, or updates the existing label value if the label value name already exists.
Delete Data Quality Certification by ID
- Available only with a Data Management license.
Delete a data quality certification from an asset using the data quality certification ID.
Delete Data Quality Certifications by Content
- Available only with a Data Management license.
Delete multiple data quality certifications from assets.
Delete Data Quality Warning by Content
- Available only with a Data Management license.
Delete the data quality warnings from an asset.
Delete Data Quality Warning by ID
- Available only with a Data Management license.
Delete a data quality warning from an asset using the data quality warning ID.
Delete Database Permissions
- Available only with a Data Management license.
Permanently remove the permissions applied to a database asset.
Delete Default Database Permissions
- Available only with a Data Management license.
Permanently remove the default permissions on a database asset.
Delete Label
- Available only with a Data Management license.
Deletes a data label by its LUID.
Delete Label Category
- Available only with a Data Management license.
Deletes a label category.
Delete Labels
- Available only with a Data Management license.
Deletes the data labels on one or more assets.
Delete labelValue
- Available only with a Data Management license.
Deletes a label value.
Delete Quality Warning Trigger by ID
- Available only with a Data Management license.
Permanently remove a quality warning trigger using the quality warning trigger ID.
Delete Quality Warning Triggers by Content
- Available only with a Data Management license.
Permanently remove all quality warning triggers for one or more data sources or flows, or both.
Delete Table Permissions
- Available only with a Data Management license.
Permanently remove the permissions applied to a table asset.
Delete Tag from Column Delete a tag from a column.
Delete Tag from Database Delete a tag from a database.
Delete Tag from Table Delete a tag from a table.
Get Databases and Tables from Connection Query databases and tables from the connection information in the data source (.tds or .tdsx) or workbook (.tws or .twbx) file's XML.
Get Label
- Available only with a Data Management license.
Gets a data label by its LUID.
Get Labels
- Available only with a Data Management license.
Displays information about the data labels on one or more assets.
Get labelValue
- Available only with a Data Management license.
Displays label value properties for a single label value.
List Label Categories on Site
- Available only with a Data Management license.
Lists all data label categories on the site.
List labelValues on Site
- Available only with a Data Management license.
Lists all label values on the site.
Move Database
- Available only with a Data Management license.
Move one or more databases to a project. You can move the database and its tables, or move only the database. To move a table independently of its database, use the Move Table method.
Move Table
- Available only with a Data Management license.
Moves one or more tables to a project.
Query All Quality Warning Triggers by Content Get information about all quality warning triggers for a content item.
Query Column in a Table Get information about a column in a table asset.
Query Columns in a Table Get information about the columns in a table asset.
Query Data Quality Certification by ID Get information about a data quality certification.
Query Data Quality Certifications by Content Get all data quality certifications for content or asset items.
Query Data Quality Warning by Content
- Available only with a Data Management license.
Get information about the data quality warning for the database, table, column, published data source, flow, virtual connection, or virtual connection table.
Query Data Quality Warning by ID Get information about a specific data quality warning.
Query Database Get information about a database asset.
Query Database Permissions Get information about the permissions on a database asset.
Query Databases Get information about all database assets for a site.
Query Default Database Permissions Get the default permissions applied to the database asset and its children tables.
Query Quality Warning Trigger Get information about a quality warning trigger.
Query Table Get information about a table asset.
Query Table Permissions Get information about the permissions on a table asset.
Query Tables Get information about all table assets for a site.
Remove Column
- Available only with a Data Management license.
Permanently remove the column from a table asset.
Remove Database
- Available only with a Data Management license.
Permanently remove the database asset.
Remove Table
- Available only with a Data Management license.
Permanently remove the table asset.
Update Column
- Available only with a Data Management license.
Update the description of the column.
Update Data Quality Warning
- Available only with a Data Management license.
Update the warning type, status, and message of a data quality warning.
Update Database
- Available only with a Data Management license.
Update the database description, certify a database, set content permissions, or assign a contact (must be a Tableau Server or Tableau Cloud user) to the database asset.
Update Label
- Available only with a Data Management license.
Updates a label by its LUID. This method can update the label value, message, active flag, and elevated flag.
Update Label Category
- Available only with a Data Management license.
Updates a data label category.
Update Labels
- Available only with a Data Management license.
Creates or updates labels on one or more assets. (An asset can be Tableau content or an external asset.) Each asset listed in the request body is updated to have a label with the specified value, message, active flag, and elevated flag.
Update labelValue
- Available only with a Data Management license.
Updates a label value.
Update Quality Warning Trigger
- Available only with a Data Management license.
Update a quality warning trigger.
Update Table
- Available only with a Data Management license.
Update the table description, certify a table, or a assign a user contact to the table asset.
Metrics Methods - Retired in API 3.22
Delete Metric - Retired in API 3.22 Deletes a specified metric from a site.
Get Metric - Retired in API 3.22 Returns the details of the specified metric.
Get Metric Data - Retired in API 3.22 Returns the data for the specified metric as comma separated (CSV) format. The maximum number of rows returned is 10,000.
List Metrics for Site - Retired in API 3.22 Returns the metrics configured for a site.
Update Metric - Retired in API 3.22 Updates the owner, project, suspended status, or name of the specified metric.
Mobile Settings Methods
Get Mobile Security Settings for Server Gets the mobile security settings for the server.
Get Mobile Security Settings for Site Gets the mobile security settings for the specified site.
Update Mobile Security Settings for Site Updates the mobile security sections for a specified site.
Notifications Methods
Add User to Data-Driven Alert Adds a specified user to the recipients list for a data-driven alert.
Create a Webhook Creates a new webhook for a site.
Create Data Driven Alert
- Not available for Tableau Server.
Create a data driven alert (DDA) for a view with a single data axis.
Delete a Webhook Deletes the specified webhook.
Delete Data-Driven Alert Deletes the specified data-driven alert from the specified site.
Delete User from Data-Driven Alert Removes a specified user from the recipients list for a data-driven alert.
Get a Webhook Returns information about the specified webhook.
Get Data-Driven Alert Returns details on a specified data-driven alert, including the recipients of the alert.
Get User Notification Preferences Returns the notification preferences for the specified site. You can filter by channel and notification type. For more information about notifications, see Manage Your Account Settings.
List Data-Driven Alerts on Site Returns a list of data-driven alerts in use on the specified site.
List Webhooks Returns a list of all the webhooks on the specified site.
Test a Webhook Tests the specified webhook. Sends an empty payload to the configured destination URL of the webhook and returns the response from the server. This is useful for testing, to ensure that things are being sent from Tableau and received back as expected.
Update a Webhook Modify the properties of an existing webhook.
Update Data-Driven Alert Update one or more settings for the specified data-driven alert; including the alert subject, frequency, and owner.
Update User Notification Preferences Updates user notifications preferences to enabled or disabled on the specified site. For more information about notifications, see Manage Your Account Settings.
OpenID Connect Methods
Create OpenID Connect Configuration
- Not available for Tableau Server.
Create the Tableau Cloud site's OpenID Connect (OIDC) configuration.
Get OpenID Connect Configuration
- Not available for Tableau Server.
Get details about the Tableau Cloud site's OpenID Connect (OIDC) configuration.
Remove OpenID Connect Configuration
- Not available for Tableau Server.
Disable and clear the Tableau Cloud site's OpenID Connect (OIDC) configuration.
Update OpenID Connect Configuration
- Not available for Tableau Server.
Update the Tableau Cloud site's OpenID Connect (OIDC) configuration.
Permissions Methods
Add Ask Data Lens Permissions - Retired in API 3.22 Adds permissions to the specified ask data lens for a user or group. You can specify multiple sets of permissions using one request.
Add Data Source Permissions Adds permissions to the specified data source for a user or group. You can specify multiple sets of permissions using one call.
Add Default Permissions Adds default permission rules for workbook, data source, data role, lens, flow, and metric resources in a project for a user or group. If Tableau Catalog is enabled, also adds default permission rules for database or table resources in a project for a user or group. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project. For more information, see Permissions(Link opens in a new window).
Add Project Permissions Adds permissions to the specified project for a user or group. You can specify multiple sets of permissions using one call.
Add View Permissions Adds permissions to the specified view (also known as a sheet) for a user or group. You can specify multiple sets of permissions using one call.
Add Workbook Permissions Adds permissions to the specified workbook for a user or group. You can specify multiple sets of permissions using one call.
Add Workbook to Server Schedule
- Not available for Tableau Cloud.
Adds a task to refresh or accelerate a workbook to an existing schedule on Tableau Server.
Delete Ask Data Lens Permission - Retired in API 3.22 Deletes the specified permissions to the specified ask data lens for a user or group.
Delete Data Source Permission Removes the specified data source permission for the specified group or user.
Delete Default Permission Removes default permission rules for workbook, data source, data role, lens, flow, and metric resources in a project for a user or group. If Tableau Catalog is enabled, also removes default permission rules for database or table resources in a project for a user or group. After removing default permission rules, new resources of the type you specify that are added to the project will no longer have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project.
Delete Project Permission Removes the specified project permission for the specified group or user.
Delete View Permission Deletes permission to the specified view (also known as a sheet) for a Tableau Server user or group.
Delete Workbook Permission Deletes the specified permission from the specified workbook for a group or user.
List Ask Data Lens Permissions List all permissions configured for the specified ask data lens that the user has read capability for.
Query Data Source Permissions Returns a list of permissions for a specific data source.
Query Default Permissions Returns details of default permission rules granted to users and groups for workbook, data source, data role, lens, flow, or metric resources in a project for a user or group. If Tableau Catalog is enabled, this method can also return details of default permission rules granted to users and groups for database or table resources in a project.
Query Project Permissions Returns information about the set of permissions allowed or denied for groups and users in a project.
Query View Permissions Returns a list of permissions for the specific view.
Query Workbook Permissions Returns a list of permissions for the specific workbook.
Projects Methods
Create Project Creates a project on the specified site. You can also create project hierarchies by creating a project under the specified parent project on the site. To make changes to an existing project, call Update Project.
Delete Project Deletes the specified project on a specific site. When a project is deleted, all Tableau assets inside of it are also deleted, including assets like associated workbooks, data sources, project view options, and rights.
Query Projects Returns a list of projects on the specified site, with optional parameters for specifying the paging of large results.
Update Project Updates the name, description, or project hierarchy of the specified project. You can create or update project hierarchies by specifying a parent project for the project that you are updating using this method.
Publishing Methods
Append to File Upload Uploads a block of data and appends it to the data that is already uploaded. This method is called after an upload has been initiated using Initiate File Upload.
Initiate File Upload Initiates the upload process for a file. After the upload has been initiated, you call Append to File Upload to send individual blocks of the file to the server. When the complete file has been sent to the server, you call Publish Data Source, Publish Flow, or Publish Workbook to commit the upload.
Publish Data Source Publishes a data source on the specified site, or appends data to an existing data source. To make other changes to a published data source, call Update Data Source or Update Data Source Connection.
Publish Flow Publishes a flow on the specified site. To make other changes to a published flow, call Update Flow or Update Flow Connection.
Publish Workbook Publishes a workbook on the specified site. To make changes to a published workbook, call Update Workbook or Update Workbook Connection.
Pulse Methods
Batch create subscriptions
- Not available for Tableau Server
Creates multiple subscriptions to a metric for specified users and/or groups.
Batch get subscriber counts
- Not available for Tableau Server
Gets the number of unique users subscribed to a set of metrics specified in a comma separated list of metric LUIDs.
Batch get subscriptions
- Not available for Tableau Server
Gets a batch of subscriptions, specified in a comma delimited list of subscriptions LUIDs.
Batch list metric definitions
- Not available for Tableau Server
Gets a batch of metric definitions and metrics available on a site.
Batch list metrics
- Not available for Tableau Server
Gets a batch of metrics from a definition, specified in a comma delimited list.
Create metric
- Not available for Tableau Server
Creates a metric.
Create metric definition
- Not available for Tableau Server
Creates a metric definition.
Create subscription
- Not available for Tableau Server
Creates a subscription to a specified metric for a specified user or group.
Delete metric
- Not available for Tableau Server
Deletes a metric.
Delete metric definition
- Not available for Tableau Server
Deletes a metric definition.
Delete subscription
- Not available for Tableau Server
Deletes a specified subscription to a metric.
Generate current metric value insight bundle
- Not available for Tableau Server
Generates a bundle the current aggregated value for each metric.
Generate detail insight bundle
- Not available for Tableau Server
Generates a detail insight bundle.
Generate springboard insight bundle
- Not available for Tableau Server
Generates a springboard insight bundle.
Get metric
- Not available for Tableau Server
Gets the details of the specified metric.
Get metric definition
- Not available for Tableau Server
Gets a metric definition and optionally metrics it contains.
Get or create metric
- Not available for Tableau Server
Returns the details of a metric in a definition if it exists, or creates a new metric if it does not. Also returns.
Get subscription
- Not available for Tableau Server
Gets a specified subscription to a metric.
List metric definitions
- Not available for Tableau Server
Lists the metric definitions configured for a site or, optionally, the details and definition for a specific metric.
List metrics in definition
- Not available for Tableau Server
Lists the metrics contained in a metric definition.
List subscriptions
- Not available for Tableau Server
Lists the subscriptions to a specified metric and/or for a specified user.
Update metric
- Not available for Tableau Server
Updates the specification of a metric.
Update metric definition
- Not available for Tableau Server
Updates a metric definition.
Revisions Methods
Download Data Source Revision Downloads a specific version of a data source prior to the current one in .tdsx format. To down load the current version of a data source use the Download Data Source method.
Download Workbook Revision
- Available only if version history is enabled for the specified site.
Downloads a specific version of a workbook in .twb or .twbx format.
Get Data Source Revisions Returns a list of revision information (history) for the specified data source.
Get Workbook Revisions Returns a list of revision information (history) for the specified workbook.
Remove Data Source Revision Removes a specific version of a data source from the specified site.
Remove Workbook Revision Removes a specific version of a workbook from the specified site.
Server Methods
Delete Server Session Deletes a specified session. This method is not available for Tableau Cloud and is typically used in programmatic management of the life cycles of embedded Tableau sessions.
Get Current Server Session Returns details of the current session of Tableau Server.
List Server Active Directory Domains
- Not available for Tableau Cloud.
Returns the details of the Active Directory domains that are in use on the server, including their full domain names, nicknames and IDs. If the server is configured to use local authentication, the command returns only the domain name local.
Server Info Returns the version of Tableau Server and the supported version of the REST API.
Update Server Active Directory Domain
- Not available for Tableau Cloud.
Changes the nickname or full domain name of an Active Directory domain on the server. This method is not available on Tableau Cloud.
Site Methods
Create Site
- Not available for Tableau Cloud.
Creates a site on Tableau Server. To make changes to an existing site, call Update Site. This method is not available for Tableau Cloud.
Delete Site
- Not available for Tableau Cloud.
Deletes the specified site.
Get Data Acceleration Report for a Site Returns a report about data acceleration for the site. It lets you compare page load times for before and after data acceleration is enabled.
Get Embedding Settings for a Site Returns the current embedding settings for a specific site.
Get Recently Viewed for Site Gets the details of the views and workbooks on a site that have been most recently created, updated, or accessed by the signed in user. The 24 most recently viewed items are returned, though it may take some minutes after being viewed for an item to appear in the results.
Query Site Returns information about the specified site, with the option to return information about the storage space and user count for the site.
Query Sites
- Not available for Tableau Cloud.
Returns a list of the sites on the server that the caller of this method has access to. This method is not available for Tableau Cloud.
Query Views for Site Returns all the views for the specified site, optionally including usage statistics.
Update Embedding Settings for Site Updates the embedding settings for a site. Embedding settings can be used to restrict embedding Tableau views to only certain domains.
Update Site
- Not available for Tableau Cloud.
Modifies settings for the specified site, including the content URL, administration mode, user quota, state (active or suspended), storage quota, whether flows are enabled, whether subscriptions are enabled, and whether revisions are enabled.
Subscriptions Methods
Create Subscription Creates a new, unsuspended subscription to a view or workbook for a specific user on Tableau Server and Tableau Cloud. When a user is subscribed to the content, Tableau sends the content to the user in email on the schedule that you define.
Delete Subscription Deletes the specified subscription on Tableau Server or Tableau Cloud.
Get Subscription Returns information about the specified subscription.
List Subscriptions Returns a list of all the subscriptions on the specified site.
Update Subscription Modifies an existing subscription on Tableau Server. You can change the subject, server schedule, and suspension state for the subscription.
Tableau Extensions Settings Methods
List Tableau extensions server settings
- Not available for Tableau Cloud.
Lists the settings for extensions of a server.
List Tableau extensions site settings Lists the settings for extensions of a site.
Update Tableau extensions server settings
- Not available for Tableau Cloud.
Updates the settings for extensions of a server.
Update Tableau extensions site settings Updates the settings for extensions of a site.
Users and Groups Methods
Add Group to Group Set Adds group to a group set.
Add User to Group Adds a user to the specified group.
Add User to Site Adds a user to Tableau Server or Tableau and assigns the user to the specified site.
Create Group Creates a group on Tableau Server or Tableau Cloud site.
Create Group Set Creates a group set with a specified name.
Delete Group Deletes the group on a specific site. Deleting a group does not delete the users in group, but users are no longer members of the group. Any permissions that were previously assigned to the group no longer apply.
Delete Group Set Deletes the group set on a specific site. Deleting a group set doesn’t delete the users in the group set, but users are no longer members of the group set. Any permissions that were previously assigned to the group set no longer apply.
Delete Users from Site with CSV Creates a job to remove a list of users, specified in a .csv file, from a site.
Get Group Set Returns information about the specified group set including ID, name, and member groups.
Get Groups for a User Gets a list of groups of which the specified user is a member.
Get Users in Group Gets a list of users in the specified group.
Get Users on Site Returns the users associated with the specified site.
Import Users to Site from CSV Creates a job to import the users listed in a specified .csv file to a site, and assign their roles and authorization settings.
Query Group Sets Lists all group sets matching optional filter and ordered by optional sort expression.
Query Groups Returns a list of groups on the specified site, with optional parameters for specifying the paging of large results.
Query User On Site Returns information about the specified user.
Remove Group from Group Set Removes a group from the specified group set.
Remove User from Group Removes a user from the specified group.
Remove User from Site Removes a user from the specified site. The user will be deleted if they do not own any other assets other than subscriptions. If a user still owns content (assets) on Tableau Server, the user cannot be deleted unless the ownership is reassigned first.
Update Group Updates a group on a Tableau Server or Tableau Cloud site.
Update Group Set Updates a group set name on a Tableau Server or Tableau Cloud site.
Update User Modifies information about the specified user.
Virtual Connections Methods
List Virtual Connection Database Connections
- Available only with a Data Management license.
Returns a list of database connections found in the specified virtual connection and information about them.
List Virtual Connections
- Available only with a Data Management license.
Returns a list of available virtual connection names and IDs.
Update Virtual Connection Database Connections
- Available only with a Data Management license.
Updates the server address, port, username, or password for the specified database connection in a virtual connection.
Workbooks and Views Methods
Add Tags to View Adds one or more tags to the specified view.
Add Tags to Workbook Adds one or more tags to the specified workbook.
Delete Custom View Deletes the specified custom view.
Delete Tag from View Deletes a tag from the specified view.
Delete Tag from Workbook Deletes a tag from the specified workbook.
Delete Workbook Deletes a workbook. When a workbook is deleted, all of its assets are also deleted, including associated views, data connections, and so on.
Download View Crosstab Excel Downloads an Excel (.xlsx) file containing crosstab data from a view that the user has permission to access in a workbook. If a crosstab is exported from a dashboard, data from only the first view in the dashboard will appear in the .xlsx file. Downloads of data from story dashboards are not supported at this time.
Download Workbook Downloads a workbook in .twb or .twbx format.
Download Workbook PDF Downloads a .pdf containing images of the sheets that the user has permission to view in a workbook. Download Images/PDF permissions must be enabled for the workbook (true by default). If Show sheets in tabs is not selected for the workbook, only the default tab will appear in the .pdf file.
Download Workbook PowerPoint Downloads a PowerPoint (.pptx) file containing slides with images of the sheets that the user has permission to view in a workbook. Download Images/PDF permissions must be enabled for the workbook (true by default). If Show sheets in tabs is not selected for the workbook, only the default tab will appear in the .pptx file.
Download Workbook Revision
- Available only if version history is enabled for the specified site.
Downloads a specific version of a workbook in .twb or .twbx format.
Get Custom View Gets the details of a specified custom view.
Get Custom View Image Downloads a .png format image file of a specified custom view.
Get Recommendations for Views Gets a list of views that are recommended for a user. Using machine learning, the server will match preferences between similar users and recommend content that is most popular and recently viewed. When a recommended view is selected and not marked as hidden, it appears on the server Home and Recommendations pages.
Get View Gets the details of a specific view.
Get View by Path Gets the details of all views in a site with a specified name.
Get Workbook Returns information about the specified workbook, including information about views and tags.
Get Workbook Downgrade Info Returns a list of the features that would be impacted, and the severity of the impact, when a workbook is exported as a downgraded version (for instance, exporting a v2019.3 workbook to a v10.5 version).
Get Workbook Revisions Returns a list of revision information (history) for the specified workbook.
Hide a Recommendation for a View Hides a view from being recommended by the server by adding it to a list of views that are dismissed for a user. If hidden, a view will not be displayed on the server Home or Recommendation pages.
List Custom Views Gets a list of custom views on a site. The list includes details of each custom view.
List Users with Custom View as Default - Preview Release
- Preview release only in some regions
Gets the list of users whose default view is the specified custom view.

Note: This method is currently available as a preview release in some regions. We will update this page when the method is generally available.
Publish Workbook Publishes a workbook on the specified site. To make changes to a published workbook, call Update Workbook or Update Workbook Connection.
Query View Data Returns a specified view rendered as data in comma-separated-value (CSV) format.
Query View Image Returns an image of the specified view.
Query View PDF Returns a specified view rendered as a .pdf file.
Query View Preview Image Returns the thumbnail image for the specified view.
Query Views for Site Returns all the views for the specified site, optionally including usage statistics.
Query Views for Workbook Returns all the views for the specified workbook, optionally including usage statistics.
Query Workbook Connections Returns a list of data connections for the specific workbook.
Query Workbook Preview Image Returns the thumbnail image as a PNG file for the specified workbook. Usually the image that is returned is for the first sheet in the workbook.
Query Workbooks for Site Returns the workbooks on a site.
Query Workbooks for User Returns the workbooks that the specified user owns in addition to those that the user has Read (view) permissions for.
Set Custom View as Default for Users - Preview release
- Preview release only in some regions
Sets the specified custom for as the default view for up to 100 specified users. Success or failure for each user is reported in the response body.

Note: This method is currently available as a preview release in some regions. We will update this page when the method is generally available.
Unhide a Recommendation for a View Unhides a view from being recommended by the server by removing it from the list of views that are dimissed for a user. If the unhidden view meets the criteria for being recommended, then it will be displayed on the server Home or Recommendation pages.
Update Custom View Changes the owner or name of an existing custom view.
Update Workbook Modifies an existing workbook, allowing you to change the owner or project that the workbook belongs to and whether the workbook shows views in tabs. Updated workbooks can optionally be marked to appear in the recently viewed list.
You can manage Data Freshness Policy(Link opens in a new window) for a workbook, and enable View Acceleration(Link opens in a new window) for views in a workbook.
Update Workbook Connection Updates the server address, port, username, or password for the specified workbook connection.
Update Workbook Now Refreshes the specified workbook.

API Method Details

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

Add (or Update) Quality Warning Trigger

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

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

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

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

URI

Add or update a quality warning trigger

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

Add or update a quality warning trigger for multiple assets

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

Parameter Values

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

The type of content the quality warning trigger is being applied to. Use one of the following values:

  • datasource
  • flow

These values are not case sensitive.

content-luid The unique ID of the asset. This is the same as the content ID.

Request Body

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

Attribute Values

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

content

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

  • EXTRACT_REFRESH
  • FLOW_RUN

These values are not case sensitive.

status

(Optional) Status of the trigger. Values can be "true" or "false". If set to "true", either the extract data source is monitored for refresh failures or the flow is monitored for flow run failures. If a failure occurs, an alert is applied (or replaces an existing one) to either the extract data source or flow. The alert remains there until the next successful refresh or flow run. For more information about monitoring quality warnings, see the monitoring quality warning section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

message (Optional) A custom message to accompany the trigger.
severity (Optional) Enables high visibility for the trigger. Values can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

Permissions

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

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

Response Code

200

Response Body

Example response

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

Version

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

Errors

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

Add analytics extension connection to site

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

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

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

License: No additional license required.

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

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

view details

Add Ask Data Lens Permissions - Retired in API 3.22

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

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

For more information, see Permissions.

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400009 Invalid capability The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Delete, Move, Read, and Write.
403 403004 No permissions to set permissions. A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404002 User not found The user specified in the request body doesn't correspond to an existing user.
404 404006 Lens not found The specified lens doesn't correspond to an existing data source.
404 404012 Group not found The group specified in the request body doesn't correspond to an existing group.
404 404013 Capability not found A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Data Quality Warning

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

This method adds a single data quality warning to an asset. (An automatically-generated monitoring warning does not count towards this limit.) Adding a data quality warning to the asset that already has one causes an error.

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

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type The type of asset that the data quality warning is being attached to. To specify the type, use:
  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtual connection
  • virtual connection table

These values are not case sensitive.

content-luid The unique ID of the asset (database, table, column, published data source, flow, virtual connection, or virtual connection table). This is the same as the content ID.

Request Body

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

Attribute Values

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

type

Type of data quality warning to apply to the asset. To specify the type, use one of the following values:

  • DEPRECATED
  • WARNING
  • STALE
  • SENSITIVE_DATA
  • MAINTENANCE

These values are case sensitive.

state

(Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default. For more information about data quality warnings, see "Set a Data Quality Warning" in the Server Help or Cloud Help.

message

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

severity (Optional) Enables high visibility for the data quality warning when set to "true". Value can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

Permissions

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

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

Response Code

201

Response Body

Example response:

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

Version

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

Errors

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

Add Data Source Permissions

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

For more information, see Permissions.

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

Permissions

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

Required scope for JWT authorization

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

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

tableau:permissions:update

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400009 Invalid capability The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write.
403 403004 No permissions to set permissions. A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source.
404 404000 Site not found The specified site doesn't correspond to an existing site.
404 404002 User not found The user specified in the request body doesn't correspond to an existing user.
404 404004 Data source not found The specified data source doesn't correspond to an existing data source.
404 404012 Group not found The group specified in the request body doesn't correspond to an existing group.
404 404013 Capability not found A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Data Source to Favorites

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden favorites access A non-administrator user called this method but doesn't have permission to add a data source to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404011 Data source not found The data source ID in the request body doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different data source in the specified user's favorites.

For more information, see Handling Errors.

Add Data Source to Server Schedule

Adds a task to refresh a data source to an existing server schedule on Tableau Server.
For Tableau Cloud, see Create 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 as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
schedule-id The ID of the schedule that you are associating with the data source.

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad Request The content of the request body is missing or incomplete, or contains malformed XML.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404004 Resource not found The data source ID in the request body is unknown.
405 405000 Invalid request method Request type was not PUT.
500 500000 Internal Server Error The schedule ID in the URI is unknown.

For more information, see Handling Errors.

Example

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

Content of add-to-schedule.xml:

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

Example response:

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

Add Database Permissions

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

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

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

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

JWT Access Scope: Not available.      

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Request Attributes

database The LUID of the database asset you want to add permissions to.
user id The LUID of the user to add permissions for.
capability name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a database are:

  • Read (view)
  • Write (edit)
  • ChangePermissions (set permissions)
  • ChangeHierarchy (move)

These values are case sensitive.

capability mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

group id The LUID of the group to add permissions for.

Response Code

200

Response Body

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

Errors

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

Add Default Database Permissions

Adds default permission capabilities to a user or group for table resources in that database. These default permissions function as a permissions template for the database's table assets.

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

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

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

user-luid The LUID of the user to add default permissions for.
group-luid The LUID of the group to add permissions for.
capability-name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a databases are the following:

  • Read (view)
  • Write (edit)
  • ChangePermissions (set permissions)
  • ChangeHierarchy (move)

These values are case sensitive.

capability-mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

Permissions

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

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

Response Code

200

Response Body

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

Version

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

Errors

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

Add Default Permissions

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

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

URI

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

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

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

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

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

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

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

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

Parameter Values

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

Request Body

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

Attribute Values

user-luid The LUID of the user to add default permissions for.
group-luid The LUID of the group to add permissions for.
capability-name

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

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

For more information, see Permissions.

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

Permissions

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

Required scope for JWT authorization

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

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

tableau:permissions:update

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400009 Invalid capability The capability in the URI is invalid for a data source.

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

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

400 400042 Malformed permissions qualifier The request body includes a <workbook> or <datasource> element.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to add permissions on the project.
404 404000 Site not found The site LUID in the URI doesn't correspond to an existing site.
404 404002 User not found A user LUID in the request body as the grantee doesn't correspond to an existing user.
404 404005 Project not found The project LUID in the URI doesn't correspond to an existing project.
404 404009 Project ID mismatch A project LUID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.)
404 404012 Group not found A group LUID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Flow Permissions

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

For more information, see Permissions.

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400009 Invalid capability The capability in the URI is invalid for a flow. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the flow.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the request body doesn't correspond to an existing user.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Flow Task to Server Schedule

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

flow-id

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

parameter-id

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

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

For more information, see Run flows with parameters.

overrideValue

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

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

For more information, see Run flows with parameters.

Permissions

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

Response Code

200

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400148 Invalid parameter override value The run-time value provided for the flow parameter is invalid.
400 400149 Missing run-time parameter value. The run-time value for a required flow parameters was not provided.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403098 Update Forbidden A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404043 Flow parameter not found The flow parameter information was not provided.
404 404002 User not found A user ID in the request body doesn't correspond to an existing user.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

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

Content of add-to-schedule.xml:

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

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

Example response:

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

Add Flow to Favorites

Adds the specified flow to the user's favorites.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden favorites access A non-administrator user called this method but doesn't have permission to add a data source to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different data source in the specified user's favorites.

For more information, see Handling Errors.

Add Group to Group Set

Adds group to a group set.

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

License: No additional license required.

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

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

URI

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

Parameter Values

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

Request Body

None

Response Code

201

Response Body

None

Errors

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

For more information, see Handling Errors.

Add Metric to Favorites - Retired in API 3.22

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

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

Adds the specified metric to the user's favorites.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden favorites access A non-administrator user called this method but doesn't have permission to add a metric to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404028 Metric not found The metric ID in the URI doesn't correspond to an existing metric.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different metric in the specified user's favorites.

For more information, see Handling Errors.

Add Project Permissions

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

For more information, see Permissions.

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

Permissions

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

Required scope for JWT authorization

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

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

tableau:permissions:update

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400009 Invalid capability

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

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

403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to add permissions on the project.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the request body as the grantee doesn't correspond to an existing user.
404 404005 Project not found The project ID in the URI doesn't correspond to an existing project.
404 404009 Project ID mismatch A project ID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.)
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Project to Favorites

Adds the specified project to a user's favorites.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

        

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Access to favorites denied A non-administrator user called this method but doesn't have permission to add a project to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

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

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

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

Example response:

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

Add Table Permissions

Add permissions to a table asset.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

table-luid The LUID for the table asset you want to add permissions to.
user-luid The LUID of the user to add permissions for.
capability-name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a database are:

  • Read (view)
  • Write (edit)
  • ChangePermissions (set permissions)
  • ChangeHierarchy (move)

These values are case sensitive.

capability-mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

group-id The LUID of the group to add permissions for.

Permissions

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

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

Response Code

200

Response Body

Example response:

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

Version

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

Errors

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

Add Tags to Column

Add one or more tags to a column.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

tag-value1

Keyword text you want to add to the asset.

tag-value2

Keyword text you want to add to the asset.

Permissions

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

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

Response Code

200

Response Body

Example response

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

Version

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

Errors

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

Add Tags to Data Source

Adds one or more tags to the specified data source.

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400075 Error adding tags There was a problem adding tags to the specified data source.
403 403004 Adding tags forbidden

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

404 404000 Site not found

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

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

For more information, see Handling Errors.

Example

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

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

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

Example response:

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

Add Tags to Database

Add one or more tags to a database.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

tag-value1

Keyword text you want to add to the asset.

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

Permissions

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

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

Response Code

200

Response Body

Example response

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

Version

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

Errors

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

Add Tags to Table

Add one or more tags to a table.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

tag-value1

Keyword text you want to add to the asset.

tag-value2

Keyword text you want to add to the asset.

Permissions

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

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

Response Code

200

Response Body

Example response

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

Version

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

Errors

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

Add Tags to View

Adds one or more tags to the specified view.

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400076 Error adding tags There was a problem adding tags to the specified view.
403 403004 Adding tags forbidden

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

404 404000 Site not found

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

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

For more information, see Handling Errors.

Example

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

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

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

Example response:

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

Add Tags to Workbook

Adds one or more tags to the specified workbook.

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400049 Error adding tags There was a problem adding tags to the specified workbook.
403 403004 Adding tags forbidden

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

404 404000 Site not found

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

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

For more information, see Handling Errors.

Example

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

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

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

Example response:

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

Add User to Data-Driven Alert

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

URI

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

Parameter Values

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

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

License: No additional license required.>

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

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

Request Body

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

Response Code

200

Response Body

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

Errors

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

For more information, see Handling Errors.

Example

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

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

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

Example response:


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

Add User to Group

Adds a user to the specified group.

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

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

URI

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

Parameter Values

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

Request Body

Add a single user to a group

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

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

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

Attribute Values

user-id

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

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

Permissions

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

Required scope for JWT authorization

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

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

tableau:groups:update

Response Code

200

Response Body

Add a single user to a group

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

Bulk add users to group (beginning in API 3.21)

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

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404012 Group not found The group name in the request body doesn't correspond to an existing group.
405 405000 Invalid request method Request type was not POST.
409 409011 User conflict The specified user is already a member of the group.

For more information, see Handling Errors.

Example

Add a single user to a group

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

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

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

Example response:

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

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

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

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

Example response:

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

Add User to Identity Pool

Add a user to a specified identity pool.

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

user-name

The name of the user to add.

site-role

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

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

Permissions

This method can only be called by Tableau Server administrators.

Response Code

200

Response Body

Example response:

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
429 429001 User conflict The specified user is already a member of the identity pool.
429 429002 Can't add user There was a problem and the user couldn't be added to the identity pool.

For more information, see Handling Errors.

Example

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

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

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

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

Example response:

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

Add User to Site

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

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

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

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

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

user-name

The name of the user. If the server uses local authentication, this can be any name. If you are using Active Directory authentication, or if you are using Tableau Cloud, there are specific requirements for the name.

For Tableau Server:
If Tableau Server uses Active Directory authentication, this must be the name of an existing user in Active Directory. If the user name is not unique across domains, you must include the domain as part of the user name (for example, example\Adam or adam@example.com).

Note: Active Directory specifies a user name using two attributes: sAMAccountName and userPrincipalName (UPN) prefix. For most Active Directory users, these attributes are the same. By default, if you are adding a user from Active Directory, the name that you provide in the user-name is matched against the Active Directory sAMAccountName attribute, which becomes the name that the user signs in to Tableau Server with.

Two exceptions are when the name that you provide: is longer than 20 characters; and includes an @ character. In these cases, Tableau imports the user using the Active Directory UPN. For more information, see User Naming Attributes(Link opens in a new window) on the MSDN site.

For Tableau Cloud:
The user-name is the email address that the user will use to sign in to Tableau Cloud. When you add a user to the site, Tableau Cloud sends an email invitation. The user can click the link in the invitation to sign in and update their full name and password.

site-role

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

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

auth-setting

(Optional) The authentication type for the user.

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

You can assign the following values for this attribute:

  • SAML - The user signs in using the identity provider (IdP) configured for the site. For Tableau Cloud configuration, see Enable SAML Authentication on a Site(Link opens in a new window). For Tableau Server, see Configure Site-Specific SAML(Link opens in a new window).
  • OpenID - Tableau Cloud only the user signs in using Google, Salesforce, or their OpenID provider credentials. In Tableau Cloud authentication settings, OpenID corresponds to Google, Salesforce, or OIDC configuration.
  • TableauIDWithMFA - Tableau Cloud only: The user signs in using a combination of TableauID credentials and a registered verification method. For more information, see About multi-factor authentication and Tableau Cloud(Link opens in a new window).
  • ServerDefault - The user signs in using the default authentication method that's set for the server. For Tableau Cloud, if Tableau hasn't updated your site to require Tableau with MFA yet, you can continue to use this authentication type on a temporary basis. The ServerDefault value corresponds to TableauID in authentication settings. For Tableau Server, the SAML(Link opens in a new window) Server help page describes default authentication options.

Permissions

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

Required scope for JWT authorization

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

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

tableau:users:create

Response Code

201

Response Body

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

Response Headers

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400003 Bad request The user authentication setting ServerDefault is not supported for you site. Try again using TableauIDWithMFA instead.
400 400013 Invalid site role

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

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

For more information, see Handling Errors.

Example

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

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

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

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

Example response:

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

Add View Permissions

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

For more information, see Permissions.

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

Permissions

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

Required scope for JWT authorization

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

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

tableau:permissions:update

Response Code

200

Response Body

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

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400009 Invalid capability The capability in the URI is invalid for a view.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the view.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view.
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or an invalid capability value (other than Allow or Deny).
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

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

Example of add-view-permissions.xml:

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

Example response:

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

Add View to Favorites

Adds the specified view to a user's favorites.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400005 Invalid label The favorite label is empty or consists of only white space characters.
403 403004 Forbidden Favorites access A non-administrator user called this method but doesn't have permission to add a view to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404011 View not found The view ID in the request body doesn't correspond to an existing view.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different view of the same workbook in the specified user's favorites.

For more information, see Handling Errors.

Example

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

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

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

Example response:

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

Add Workbook Permissions

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

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

For more information, see Permissions.

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

Permissions

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

Required scope for JWT authorization

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

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

tableau:permissions:update

Response Code

200

Response Body

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

Version

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

Errors

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

For more information, see Handling Errors.

Add Workbook to Favorites

Adds the specified workbook to a user's favorites.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400005 Invalid label

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

403 403004 Access to Favorites forbidden

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

404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404006 Workbook not found The workbook ID in the request body doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not PUT.
409 409007 Label conflict There is already a favorite with the same label for a different workbook in the specified user's favorites.

For more information, see Handling Errors.

Add Workbook to Server Schedule

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

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

This method is not available for Tableau Cloud.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

Permissions

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

Response Code

200

Response Body

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

Version

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

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

For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad Request The content of the request body is missing or incomplete, or contains malformed XML.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403032 Update Forbidden A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI is unknown.
404 404006 Resource not found The workbook ID in the request body is unknown.
405 405000 Invalid request method Request type was not PUT.
500 500000 Internal Server Error The schedule ID in the URI is unknown.

For more information, see Handling Errors.

Example

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

Content of add-to-schedule.xml:

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

Example response:

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

Allow dashboard extension on site - Retired in API 3.21


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

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


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

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

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

License: No additional license required.

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

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

view details

Append to File Upload

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

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

For more information, see Publishing Resources.

URI

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

Parameter Values

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

Request Body

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

Permissions

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

Required scope for JWT authorization

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

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

tableau:file_uploads:create

Response Code

200

Response Body

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

Version

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

Errors

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

For more information, see Handling Errors.

Batch Add or Update Data Quality Certifications

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

content

The type of content or asset the data quality warning is attached to. To specify type, use one of the following values:

  • database
  • table
  • datasource
  • virtualconnection
  • virtualconnectiontable
database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
datasource-id The unique ID of the data source content.
virtualconnection-id The unique ID of the virtual connection asset.
virtualconnectiontable-id The unique ID of the virtual connection table asset.
type

Use the following value to apply a data quality certification: CERTIFIED.

message A custom message to accompany the data quality certification.
state (Optional) Controls whether the data quality certification displays. Value can be "true" or "false". If the state is not specified, the data quality certification is set to "true" and is visible by default. For more information about data quality certifications, see "Set a Data Quality Certification" in the Server Help or Cloud Help.
severity (Optional) Enables high visibility for when the data quality certification is set to "true". Value can be "true" or "false". If the severity is not specified, the data quality certification is set to "false." This setting is available only through the REST API.

Permissions

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

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

Response Code

201

Response Body

Example response

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

Version

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

Errors

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

Batch Add or Update Data Quality Warnings

Add or update multiple data quality warnings on assets.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

content

The type of content or asset the data quality warning is attached to. To specify type, use one of the following values:

  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable
database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.
datasource-id The unique ID of the data source content.
flow-id The unique ID of the flow content.
virtualconnection-id The unique ID of the virtual connection.
virtualconnectiontable-id The unique ID of the virtual connection table.
type

The type of data quality warning to apply to the content or asset. To specify type, use one of the following values:

  • DEPRECATED
  • WARNING
  • STALE
  • SENSITIVE_DATA
  • MAINTENANCE
message (Optional) A custom message to accompany the data quality warning.
state (Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default. For more information about data quality warnings, see "Set a Data Quality Warning" in the Server Help or Cloud Help.
severity (Optional) Enables high visibility for when the data quality warning is set to "true". Value can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help.

Permissions

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

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

Response Code

200

Response Body

Example response

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

Version

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

Errors

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

Batch Add Tags

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

tag-value1

Keyword text you want to add to item.

tag-value2

Keyword text you want to add to item.

database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.
datasource-id The unique ID of the data source content.
workbook-id The unique ID of the workbook content.
flow-id The unique ID of the flow content.

Permissions

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

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

Response Code

200

Response Body

Example response

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

Version

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

Errors

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

Batch create subscriptions

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

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

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

License: No additional license required.

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

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

view details

Batch Delete Data Quality Warnings

Delete multiple data quality warnings from assets.

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

content

The type of content or asset the data quality warning is attached to. To specify type, use one of the following values:

  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable
database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.
datasource-id The unique ID of the data source content.
flow-id The unique ID of the flow content.
virtualconnection-id The unique ID of the virtual connection.
virtualconnectiontable-id The unique ID of the virtual connection table.

Permissions

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

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

Response Code

204

Response Body

None

Version

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

Errors

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

Batch Delete Tags

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

tag-value1

Keyword text you want to add to item.

tag-value2

Keyword text you want to add to item.

database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.
datasource-id The unique ID of the data source content.
workbook-id The unique ID of the workbook content.
flow-id The unique ID of the flow content.

Permissions

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

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

Response Code

204

Response Body

Example response

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

Version

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

Errors

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

Batch get subscriber counts

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

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

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

License: No additional license required.

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

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

view details

Batch get subscriptions

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

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

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

License: No additional license required.

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

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

view details

Batch list metric definitions

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

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

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

License: No additional license required.

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

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

view details

Batch list metrics

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

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

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

License: No additional license required.

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

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

view details

Block dashboard extension on server - Retired in API 3.21


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

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


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

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

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

License: No additional license required.

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

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

view details

Cancel Flow Run

Cancels a flow run that is in progress.

URI

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

Parameter Values

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

Request Body

None

Response Code

200

Response Body

None

Version

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

Errors

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

For more information, see Handling Errors.

Cancel Job

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

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

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

URI

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

Parameter Values

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

Request Body

None

Permissions

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

Response Code

200

Response Body

None

Version

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

Errors

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

For more information, see Handling Errors.

Example

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

Configure Identity Store

Configure a new local identity store to provision users.

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

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

License: No additional license required.

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

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

view details

Create a Webhook

Creates a new webhook for a site.

URI

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

Parameter Values

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

Request Body

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

Attribute Values

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

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

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

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

Permissions

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

Response Code

200

Response Body

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

Response Headers

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

Create an Extract for a Data Source

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

URI

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

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

Parameter Values

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

Request Body

None

Permissions

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

Response Code

200

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
    <extractCreationJob>
	  <datasource id="datasource-id" name="datasource-name" />
  </extractCreationJob>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

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

Response body:

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

Create ask data lens - Retired in API 3.22


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

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


Create an ask data lens.

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

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

License: No additional license required.

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

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

view details

Create Authentication Configuration

Create an instance of OpenID Connect (OIDC) authentication.

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

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

License: No additional license required.

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

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

view details

Create Cloud Extract Refresh Task

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

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

License: No additional license required.

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

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

URI

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

URI Parameter Values

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

Request Body

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

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

Request Attributes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cURL Request Example

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

Response Code

200

Response Body

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

Errors

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

For more information, see Handling Errors.

Create Cloud Flow Task

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

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

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: Requires Tableau 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.     Access Scopes Overview: Cloud(Link opens in a new window) 

URI

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

URI Parameter Values

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

Request Body

Copy
<tsRequest>
  <task>
    <flowRun>
      <flow id="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"/>
    </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>

Copy
{
  "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:
  • Hourly
  • Daily
  • Weekly
  • Monthly
frequencyDetails start (Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.
frequencyDetails end

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

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

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

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

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

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

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

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

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

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

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

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

cURL Request Example

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

Response Code

200

Response Body

Copy
<tsResponse>
  <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"/>
              </parameter>
            </parameters>
        </flow>
        <flowRunSpec flowId="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541">
        <flowOutputSteps>
          <flowOutputStep id="485c8b5f-5647-466c-b549-e38410b7c7c8" 
            name="Output"/>
        </flowOutputSteps>
        <flowParameterSpecs/>
      </flowRunSpec>
    </flowRun>
  </task>
</tsResponse>
Copy
{
  "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, see Handling Errors.

Create Connected App

Create a connected app.

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

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

URI

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

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

Parameter Values

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

Request Body

Tableau Cloud

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

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

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

Attribute Values

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

name Name of the connected app.
enabled (Optional) Controls whether the connected app is enabled or not. Value can be "true" or "false". If the state is not specified, the connected app is set to "false" and not enabled by default.
project_id

(Optional, embedding workflows only) The IDs of the projects that the connected app's access level is scoped to. To get a project's project ID, see Query Projects. You can specify one project, multiple projects, all projects on a site.

  • Single project:

    • For Tableau Cloud, to scope the connected app's access to one project, the recommended workflow is to specify the projectIds and projectId attributes and projectId value.

    • For Tableau Server (or Tableau Cloud using REST API 3.21 (or earlier)), specify the projectId parameter and its value.

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

  • All projects:

    • For Tableau Cloud, to scope the connected app's access to all projects on a site, omit the projectIds attribute from the request.

    • For Tableau Server (or Tableau Cloud using REST API 3.21 (or earlier)), to scope the connected app's access to all projects on a site, omit the projectId attribute from the request.

    Note: Specifying "all projects" in an update request for a connected app is handled differently. For more information, see update project(Link opens in a new window).

Note: For Tableau Cloud, the stand-alone projectId attribute will be retired in a future release so we recommend using projectIds attribute instead.

domainSafelist

(Optional, embedding workflows only) A list of domains the connected app is allowed to be hosted. Specify one or more URLs, separated by spaces, using a format described in Domain allowlist rules(Link opens in a new window) in the Tableau Server Help or Domain allowlist rules(Link opens in a new window) in the Tableau Cloud Help.

For example: https://tableau.com https://myco.com:552 marketing.example.com

unrestrictedEmbedding (Optional, embedding workflows only) Controls whether the connected app can be hosted on all domains. If "true" value is specified, the connected app can be hosted on all domains. If "false" value is specified, the connected app can only be hosted on the domains specified in the <domainSafelist> attribute.

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

201

Response Body

Example response:

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

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

Version

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

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

Errors

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

Create Connected App Secret

Generate a secret for a connected app.

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

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

URI

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

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

Parameter Values

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

Request Body

None

Permissions

Tableau Server admins or Tableau Cloud site admins only.

Response Code

201

Response Body

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

Example response:

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

Version

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

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

Errors

HTTP status error Code Condition Details
400 400143 Generic connected app error The connected app could not be deleted for some other reason than those specified in this table.
400 400144 Secret limit exceeded

The connected app has already reached its two secret maximum.

403 403000 Admin permissions required A non-admin user called this method and doesn't have adequate permissions to perform the action.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404041 Connected app not found The requested connected app could not be found.
404 404042 Secret not found The requested secret for the connected app could not be found.

Create Data Driven Alert

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

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

License: No additional license required.

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

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

URI

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

URI Parameter Values

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

Request Body

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

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

Request Attributes

dataAlertCreateAlert alertCondition

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

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

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

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

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

  • desktop
  • phone
  • tablet
dataAlertCreateAlert worksheetName

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

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

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

dataAlertCreateAlert viewId

OR

dataAlertCreateAlert customViewId

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

cURL Request Example

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

Response Code

200

Response Body

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

Errors

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

For more information, see Handling Errors.

Create Extracts for Embedded Data Sources in a Workbook

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

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

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

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

URI

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

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

Path Parameter Values

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

Request Body

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

Request Parameter Values

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

Permissions

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

Response Code

200

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
    <extractCreationJob>
      <workbook id="workbook-id" name="workbook-name" />
	</extractCreationJob>
  </job>
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
404 404000 Site not found The specified site doesn't correspond to an existing site.
405 405000 Invalid request method Request type was not POST.
409 409070 Invalid request method The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

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

Content of create-extracts-for-workbook.xml

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

Response body:

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

Create Group

Creates a group on Tableau Server or Tableau Cloud site.

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

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

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

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

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

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

URI

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

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

Parameter Values

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

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

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

This attribute is available for Tableau Server only.

Request Body

Creating a local group

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

        

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

Importing a group from Active Directory (Tableau Server only)

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

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

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

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

Attribute Values

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

The name of the Active Directory group to import.

This attribute is available for Tableau Server only.

active-directory-domain-name

The domain of the Active Directory group to import.

This attribute is available for Tableau Server only.

minimum-site-role

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

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

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

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

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

license-mode

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

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

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

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

on-demand-access

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

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

Permissions

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

Required scope for JWT authorization

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

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

tableau:groups:create

Response Code

201, for creating a local group and for importing immediately

202, for importing using a background process

Response Headers

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

Response Body

Creating a local group:

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

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

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

Importing as a background process:

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="GroupImport"
    progress="0" createdAt="time-job-created" />
</tsResponse>
        

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400013 Invalid site role

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

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

For more information, see Handling Errors.

Example: Local Group

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

Content of create-local-group.xml:

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

Response header:

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

Response body:

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

Example: Active Directory Group

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

Content of create-ad-group.xml:

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

Response header:

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

Response body:

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

Create Group Set

Creates a group set with a specified name.

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

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

License: No additional license required.

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

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

URI

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

URI Parameter Values

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

Request Body

XML

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

JSON

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

Request Attributes

name

(Required) Name of the new group set.

cURL Request Example

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

Response Code

201, for creating a group set.

Response Body

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400013 Invalid site role

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

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

For more information, see Handling Errors.

Create Identity Pool

Create an identity pool.

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

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

License: No additional license required.

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

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

view details

Create Label Category

Creates a data label category.

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

label-category-name

The label category name.
Required. Must be 1-128 characters long in Tableau Cloud. Must be 1-24 characters long in Tableau Server.

label-category-description

The label category description.
Required. Must be 1-500 characters in length.

Permissions

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

Response Code

200

Version

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

Response Body

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

Errors

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

Create metric

Creates a metric.

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

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

License: No additional license required.

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

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

view details

Create metric definition

Creates a metric definition.

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

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

License: No additional license required.

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

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

view details

Create OpenID Connect Configuration

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

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

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

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

License: No additional license required.

Permissions: Tableau Cloud site admins only.

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

URI

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

URI Parameter Values

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

Request Body

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

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

Request Attributes

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

cURL Request Example

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

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

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

Response Code

200

Response Body

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

Notes:

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

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

Errors

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

For more information, see Handling Errors.

Create or Update labelValue

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

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

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

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

URI

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

Parameter Values

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

Request Body

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

Attribute Values

label-value-name

The label value name.

Required. If you specify an existing label value name, this method will update the label value. If you specify a label value name that's different than existing label value names, this method will create the label value.

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

label-value-category

The label value category.

Required. If you're updating an existing label value, this must match the existing category for that label value.

label-value-description

The label value description.

Required, but does not need to be different than the existing description. Must be 1-500 characters in length.

Permissions

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

Response Code

200

Version

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

Response Body

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

Errors

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

Create Project

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

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

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

License: No additional license required.

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

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

URI

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

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

Parameter Values

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

Request Body

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

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

Attribute Values

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

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

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

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

project contentPermissions

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

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

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

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

cURL Example

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

Response Code

201

Response Body

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

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

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400008 Bad request The request cannot set content permissions to LockedToProjectWithoutNested for a REST API version lower than 3.8.
403 403008 Insufficient storage on site The samples could not be published because there is not enough storage space remaining on the server to accommodate the samples.
404 404000 Site not found

The site ID in the URI doesn't correspond to an existing site.

405 405000 Invalid request method Request type was not POST.
409 409006 Project name conflict The project name in the request already belongs to the specified site. For the purpose of uniqueness checks, project names are case-insensitive.

For more information, see Handling Errors.

Create Server Schedule

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

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

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

URI

POST /api/api-version/schedules

Parameter Values

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

Request Body

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

Attribute Values

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

This represents the granularity of the schedule.

  • Hourly. Jobs can be scheduled to run at intervals specified in run one or more times per day at intervals specified in minutes or hours. Valid intervals are 15 and 30 minutes and 2, 4, 6, 8, and 12 hours.

  • Daily. Jobs can be scheduled to run once per day.
  • Weekly. Jobs can be scheduled to run one or more times per week.
  • Monthly. Jobs can be scheduled to run once per month on a specific day.

The value you provide for schedule-frequency determines whether you must include an end-time value, and what is required in the contents of the <intervals> element.

start-time The time of day on which scheduled jobs should run (or if the frequency is hourly, on which they should start being run), in the format HH:MM:SS (for example, 18:30:00). This value is required for all schedule frequencies. The entered time will be applied based on the time zone of your server.
end-time If the schedule frequency is Hourly, the time of day on which scheduled jobs should stop being run, in the format HH:MM:SS (for example, 23:30:00). Hourly jobs will occur at the specified intervals between the start time and the end time. For other schedule frequencies, this value is not required; if the attribute is included, it is ignored. The entered time will be applied based on the time zone of your server.
interval-expression A value that specifies the interval between jobs associated with the schedule. The value you specify here depends on the value specified in schedule-frequency.

Hourly

The interval expression is only one of the following:

  • hours="interval" where interval is 1, 2, 4, 6, 8, or 12, representing how many hours between jobs.
  • minutes="interval" where interval is 15 or 30, representing how many minutes between jobs.

You can specify an interval in hours or minutes, but not both.

Daily

If the schedule frequency is Daily, no interval is specified. Any information specified in the <intervals> element is ignored.

Weekly

The interval expression is weekDay="weekday", where weekday is Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

You can specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week.

Monthly

The interval expression is monthDay="day", where day is either the day of the month (1, 2, etc.) or LastDay.

Note: If you want to specify multiple days in the month, you can do this using the web interface. You cannot create or update such a monthly schedule using REST API.

Permissions

This method can only be called by server administrators.

Response Code

201

Response Body

<tsResponse>
  <schedule id="schedule-id"
    name="schedule-name"
	state="Active-or-Suspended"
    priority="schedule-priority"
	createdAt="datetime-created"
	updatedAt="datetime-updated"
	type="Extract-or-Subscription-or-Flow"
	frequency="schedule-frequency"
	nextRunAt="datetime-next-run"
	executionOrder="Parallel-or-Serial">
	  <frequencyDetails frequency-expression >
	    <intervals>
	      <interval interval-expression />
	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsResponse>
        

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
400 400064 Error creating schedule An unspecified error occurred while trying to create the schedule.
400 409004 Bad request The content of the request body is missing or incomplete. For hourly, daily, or monthly schedules, this often means that the content of the <intervals> element does not match the expected format. The <detail> element of the error provides detail about the expected format.
405 405000 Invalid request method Request type was not POST.
409 409021 Schedule name conflict The schedule name in the request already belongs to an existing schedule.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/schedules/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-schedule.xml


Content of create-schedule.xml for an hourly schedule

<tsRequest>
  <schedule name="hourly-schedule-1"
    priority="50"
	type="Extract"
	frequency="Hourly"
	executionOrder="Parallel">
	  <frequencyDetails start="18:30:00" end="23:00:00">
		<intervals>
		  <interval hours="2" />
		</intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse >
  <schedule
    id="4d652179-36bf-47e4-a9dc-e069227c72d0"
    name="hourly-schedule-1"
    state="Active"
    priority="50"
    createdAt="2016-05-07T01:51:19Z"
    updatedAt="2016-05-07T01:51:19Z"
    type="Extract"
    frequency="Hourly"
    nextRunAt="2016-05-07T03:30:00Z"
    executionOrder="Parallel">
      <frequencyDetails start="18:30:00" end="23:00:00">
        <intervals>
           <interval hours="2" />
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
        


Content of create-schedule.xml for a daily schedule

For a daily schedule, frequencyDetails is set to Daily. The start attribute is required. No intervals element is required. Daily schedules on any recurrence must have the same start and end minute. The hour can be different. However, if the daily schedule is set to only happen once a day, then it needs only a start time and not an end time.

<tsRequest>
  <schedule
    name="daily-schedule-1"
    priority="50"
    type="Subscription"
    frequency="Daily"
    executionOrder="Parallel">
      <frequencyDetails start="02:15:00" />
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule
	id="4d652179-36bf-47e4-a9dc-e069227c72d0"
	name="daily-schedule-1"
	state="Active"
	priority="50"
	createdAt="2016-05-07T01:43:33Z"
	updatedAt="2016-05-07T01:43:33Z"
	type="Subscription"
	frequency="Daily"
	nextRunAt="2016-05-07T09:15:00Z"
	executionOrder="Parallel">
	  <frequencyDetails start="02:15:00" />
  </schedule>
</tsResponse>
        


Content of create-schedule.xml for a weekly schedule

For a weekly schedule, frequencyDetails is set to Weekly. A start attribute is required. The intervals element is required, and must include between 1 and 7 interval subelements that contain a weekDay attribute. Valid values for the weekDay attribute are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

<tsRequest>
  <schedule name="weekly-schedule-1"
	priority="50"
	type="Subscription"
	frequency="Weekly"
	executionOrder="Serial">
  	  <frequencyDetails start="18:30:00">
	    <intervals>
	      <interval weekDay="Sunday" />
	      <interval weekDay="Wednesday" />
 	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0"
    name="weekly-schedule-1"
    state="Active"
    priority="50"
    createdAt="2016-05-07T02:01:30Z"
    updatedAt="2016-05-07T02:01:30Z"
    type="Subscription"
    frequency="Weekly"
    nextRunAt="2016-05-09T01:30:00Z"
    executionOrder="Serial">
      <frequencyDetails start="18:30:00">
        <intervals>
          <interval weekDay="Sunday" />
          <interval weekDay="Wednesday" />
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
        


Content of create-schedule.xml for a monthly schedule

For a monthly schedule, frequencyDetails is set to Monthly. A start attribute is required. The intervals element is required, and must include 1 interval subelement that contains a monthDay attribute. Valid values for the monthDay attribute are integers between 1 and 31 and the string LastDay.

<tsRequest>
  <schedule name="monthly-schedule-1"
	priority="50"
	type="Subscription"
	frequency="Monthly"
	executionOrder="Parallel">
	  <frequencyDetails start="06:00:00">
	    <intervals>
	      <interval monthDay="15" />
	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule
	id="4d652179-36bf-47e4-a9dc-e069227c72d0"
	name="monthly-schedule-1"
	state="Active"
	priority="50"
	createdAt="2016-05-07T02:08:25Z"
	updatedAt="2016-05-07T02:08:25Z"
	type="Subscription"
	frequency="Monthly"
	nextRunAt="2016-06-03T13:00:00Z"
	executionOrder="Parallel">
	  <frequencyDetails start="06:00:00">
	    <intervals>
	      <interval monthDay="15" />
	    </intervals>
  	  </frequencyDetails>
  </schedule>
</tsResponse>
        

Create Site

Creates a site on Tableau Server. To make changes to an existing site, call Update Site. This method is not available for Tableau Cloud.

For more information, see Work with Sites(Link opens in a new window) and Add or Edit Sites(Link opens in a new window) in the Tableau Server documentation.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

POST /api/api-version/sites

Request Body

<tsRequest>
  <site
	name="site-name"
	contentUrl="content-url"
	adminMode="admin-mode"
	storageQuota="limit-in-megabytes"
	disableSubscriptions="disable-subscriptions"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	commentingEnabled="commenting-enabled-flag"
	revisionHistoryEnabled="enable-revision-history-flag"
	revisionLimit="num-revision-limit"
	subscribeOthersEnabled="subscribe-others-enabled-flag"
	extractEncryptionMode="extractEncryptionMode"
	requestAccessEnabled="request-access-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	dataAlertsEnabled="data-alerts-enabled-flag"
	commentingMentionsEnabled="commenting-mentions-enabled-flag"
	catalogObfuscationEnabled="catalog-obfuscation-enabled-flag"
	flowAutoSaveEnabled="flow-auto-save-enabled-flag"
	webExtractionEnabled="web-extraction-enabled-flag"
	runNowEnabled="run-now-enabled-flag"
	metricsContentTypeEnabled="metrics-content-type-enabled-flag"
	notifySiteAdminsOnThrottle="notify-site-admins-on-throttle-flag"
	authoringEnabled="authoring-enabled-flag"
	customSubscriptionEmailEnabled="custom-subscription-email-enabled-flag"
	customSubscriptionEmail="custom-subscription-email"
	customSubscriptionFooterEnabled="custom-subscription-footer-enabled-flag"
	customSubscriptionFooter="custom-subscription-footer"
	askDataMode="ask-data-mode"
	namedSharingEnabled="named-sharing-enabled-flag"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	userVisibilityMode="user-visibility-mode"
	useDefaultTimeZone="default-time-zone-flag"
 	timeZone="time-zone"
    autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
    autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window"
	explainDataEnabled="explainDataEnabled" />
</tsRequest>
        

Attribute Values

site-name The name of the site.
content-url The subdomain name of the site's URL. This value can contain only characters that are upper or lower case alphabetic characters, numbers, hyphens (-), or underscores (_). If you provide unsupported special characters, Tableau creates the site content URL by omitting those characters from the string. For example, if you provide the site URL as "test.site", Tableau converts it to "testsite" and returns this new URL in the response.
admin-mode

(Optional) Specify ContentAndUsers to allow site administrators to use the server interface and tabcmd commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify ContentOnly to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.)

Note: You cannot set adminMode to ContentOnly and also set userQuota. The default value is ContentAndUsers.

storage-quota (Optional) The maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again.
disable-subscriptions

(Optional) Specify true to prevent users from being able to subscribe to workbooks on the specified site. The default is false.

editing-flows-enabled-flag

(Optional) Specify true to enable and false to disable editing flows for a site. For more information on flows, see Enable and Configure Tableau Prep Conductor(Link opens in a new window).

The default is set to true which means editing flows is enabled by default. For more information, see Implication of disabling Tableau Prep Conductor.

scheduling-flows-enabled-flag

(Optional) Specify true to enable and false to disable scheduling flows for a site. For more information on flows, see Enable and Configure Tableau Prep Conductor(Link opens in a new window).

The default is set to true which means scheduling flows is enabled by default. For more information, see Implication of disabling Tableau Prep Conductor.

flows-enabled-flag

The flowsEnabled attribute is deprecated as of API version 3.10.

allow-subscription-attachments-flag

(Optional) If true, and subscription to attachments is enabled on the server, then users can create subscriptions that send an email with images of a workbook or view in a PDF attachment. The default value is true. If subscription to attachments is disabled in the server settings, then making this value true will have no effect. Default is true.

guest-access-enabled-flag

(Optional) Specify true to enable and false to disable the ability for guests, users without specific site access permission, to access the site. Default is false.

cache-warmup-enabled-flag

This attribute is removed in API 3.19 and later (Tableau Cloud September 2021). For current methods to improve Tableau performance see, View Acceleration(Link opens in a new window).

(Optional) Set this value to true to enable cache warm up to improve workbook load time. Set the value to false to disable cache warmup. Default is true.

commenting-enabled-flag

(Optional) Specify true to enable and false to disable the ability for user comments on views in the site. Default is true.

revision-history-enabled (Optional) true if the site maintains revisions for changes to workbooks and data sources; otherwise, false. The default is false.
num-revision-limit (Optional) An integer between 2 and 10000 to indicate a limited number of revisions for content.

Setting this value to -1 removes any value that was set previously, and effectively removes any limit to the number of revisions that are maintained.

subscribe-others-enabled-flag

(Optional) Specify true to enable and false to disable the ability for view owners to subscribe other users to a view. Default is true.

extractEncryptionMode

(Optional) Specify enforced, enabled, or disabled. Default is disabled. For more information, see Extract and Encryption Methods.

requestAccessEnabled (Optional) Specify true to allow users send access request emails to content or project owners. Specify false if you do not want users to be able to request access. The default is false.
runNowEnabled

(Optional) Specify true to allow users to run flows, extract refreshes, and schedules manually. Specify false if you do not want users to be able to run flows, extract refreshes, and subscriptions manually. The default is true. If this attribute is set to false, the following methods will fail and will return an error message.

Run Flow Now

Run Flow Task(Link opens in a new window)

Update Data Source Now(Link opens in a new window)

Run Extract Refresh Task(Link opens in a new window)

Licensing attributes

For user-based license types, the maximum possible number of users is set by the licenses activated on that server. For core-based licensing, there is no limit to the number of users; if you specify a maximum value, only licensed users are counted, and server administrators are excluded.

The REST API enables administrators to set licensing limits below the purchased maximum with two types of license-related attributes:
- User Quota - The total maximum number of licenses currently configured for a site.
- Tiered Capacities - If set, the configured maximum license count for each license type (role).

Online administrators can get these attributes. An on premise server administrator can both get and set them but if license maximums are set using one attribute kind then the value(s) of the other kind must be null. Setting values for both kinds of attributes will result in an error.

For more information, see Licensing Overview(Link opens in a new window).

User quota

all-license-limit-total

(Optional) The maximum total number of users with Creator, Explorer, or Viewer licenses currently allowed on a site.

On premise server administrators can set userQuota with the following rules: The number can't exceed the number of licenses activated for the site; and if tiered capacity attributes are set, then userQuota will equal the sum of the tiered capacity values, and attempting to set userQuota will cause an error.

An administrator can revert the license limit to number of activated licenses on the site, or shift control of license limits to tiered capacities values, by omitting userQuota from a Create Site or Update Site request, or making its value -1.

Tiered capacity attributes

creator-license-limit
explorer-license-limit
viewer-license-limit

(Optional) The maximum number of licenses for users with the Creator, Explorer, or Viewer role, respectively, allowed on a site.

On premise server administrators can set tiered capacity attributes with the following rules: the number can't exceed the number of licenses of a given type that are activated for the site; a value must be supplied for every tiered capacity license type every time any one or more of them is set.

A value of -1 removes the administrator applied limit for a license type, and reverts the limit to the number of activated licenses configured for the role. Setting the value of a tiered capacity to -1 will not automatically increase the limit if more licenses are purchased and activated for the role in the future.

To use role-specific license limits, the userQuota must be set to null by omitting the attribute from Create Site or Update Site request, or setting its value to -1. Attempting to set values for both tiered capacities and userQuota will result in an error.

data-alerts-enabled-flag

(Optional, boolean) If true, data alerts are enabled on the site. Default value is true.

commenting-mentions-enabled-flag

(Optional, boolean) If true, mentions for commenting are enabled. Default value is true.

catalog-obfuscation-enabled-flag

(Optional, boolean) If true, catalog obfuscation is enabled on the site. Default value is true.

flow-auto-save-enabled-flag

(Optional, boolean) If true, flow auto save is enabled on the site. Default value is true.

web-extraction-enabled-flag

(Optional, boolean) If true, web extraction is enabled on the site. Default value is true.

run-now-enabled-flag

(Optional, boolean) If true, run now for schedules is enabled which allows non-administrators to run schedules manually. Default value is true.

metrics-content-type-enabled-flag

(Optional, boolean) If true, the metrics content type is enabled on the server. Default value is true.

notify-site-admins-on-throttle-flag

(Optional, boolean) If true, site admins will be notified if their background jobs are being throttled. Default value is false.

authoring-enabled-flag

(Optional, boolean) If true, web authoring is enabled. Default value is true.

custom-subscription-email-enabled-flag

(Optional, boolean) If true, sending custom subscription email is enabled. If set to false after being set true, the current custom subscription email is voided. Default value is false.

custom-subscription-email

A valid custom email that will be sent if customSubscriptionEmailEnabled is set to true. Default value is false.

custom-subscription-footer-enabled-flag

(Optional, boolean) If true, a custom footer will be included on subscription and data alert emails. If set to false after being set true, the current custom subscription footer is voided. Default value is false.

custom-subscription-footer

A custom subscription footer that will be added to subscription and data alerts if customSubscriptionFooterEnabled is set to true. Default value is false.

ask-data-mode

The mode of the ask data feature on the site. Can be set to one of two values:
  • DisabledByDefault - Enables creation of Ask Data lenses for all published data sources. Data sources do not have lenses created automatically.
  • DisabledAlways - Disables Ask Data lenses and related content throughout the site. Preserves information about lenses and data source indexes, which are restored if Ask Data is re-enabled.
Default value is DisabledByDefault. For more information, see Disable or Enable Ask Data for a Site(Link opens in a new window).

named-sharing-enabled-flag

(Optional, boolean) If true, named sharing is enabled. Default value is true.

cataloging-enabled-flag

(Optional, boolean) If true, data catalog is enabled for the site. Default value is true.

derived-permissions-enabled-flag

(Optional, boolean) If true, derived permissions are enabled for the site. Default value is false.

user-visibility-mode

(Optional, string) When the value is FULL users can see the user of other site users. If the value is LIMITED User information on the site is not visible to other users. Default value is FULL. For more information, see User Visibility(Link opens in a new window).
use-default-time-zone Optional, boolean) Set this to true, if you want the time-zone attribute use the Server time Zone at run time. This attribute is set to official IANA name.  If this is set to false, the time-zone value must be specified.
time-zone (Optional, string) Use this attribute to specify a time zone other than the Server time zone at run time. Only canonical names in the official IANA database are supported. You can find the list of the canonical time zone names on wikipedia.
autoSuspendRefreshEnabled (Optional) Tableau can automatically suspend extract refresh tasks for inactive workbooks to save resources. Specify true to enable or false to disable. Default is true.
autoSuspendRefreshInactivityWindow (Optional) An integer between 7 and 100 to indicate the number of days to wait before automatically suspending extract refresh tasks for inactive workbooks. The default is 30.
explainDataEnabled

(Optional, boolean) Set this attribute to false to disable Explain Data capabilities for a site. By default, this attribute is set to true. For more information about this site setting, see one of the following topics:

dqwSubscriptionsEnabled

(Optional, boolean) Set this attribute to false to exclude data quality warnings (DQWs) from subscription emails. By default, this attribute is set to true. For more information about this site setting, see one of the following topics:

Permissions

This method can only be called by server administrators.

Required scope for JWT authorization

Introduced in Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:sites:create

Response Code

201

Response Body

<tsResponse>
  <site id="site-id"
 	name="site-name"
	contentUrl="content-url"
 	adminMode="admin-mode"
	disableSubscriptions="disable-subscriptions-flag"
	state="active-or-suspended"
	revisionHistoryEnabled="history-enabled-flag"
	revisionLimit="max-num-revisions"
	allowSubscriptionAttachments="allow-subcription-attachments-flag"
	subscribeOthersEnabled="enable-subscription-of-others-flag"
	guestAccessEnabled="guest-access-enabled-flag"
	cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
	commentingEnabled="commenting-enabled-flag"
    editingFlowsEnabled="editing-flows-enabled-flag"
    schedulingFlowsEnabled="scheduling-flows-enabled-flag"
	extractEncryptionMode="encryption-mode"
	catalogingEnabled="cataloging-enabled-flag"
	derivedPermissionsEnabled="derived-permissions-enabled-flag"
	requestAccessEnabled="request-access-enabled-flag"
	webExtractionEnabled="create-extracts-on-the-web-flag"
	runNowEnabled="run-now-enabled-flag"
	userQuota="all-license-limit-total"
	tierCreatorCapacity="creator-license-limit"
	tierExplorerCapacity="explorer-license-limit"
	tierViewerCapacity="viewer-license-limit"
	askDataMode="ask-data-mode"
	useDefaultTimeZone="default-time-zone-flag"
	timeZone="time-zone"
    autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
    autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window"
	explainDataEnabled="explain-data-enabled"
	dqwSubscriptionsEnabled="dqw-subscriptions-enabled" />
  </site>
</tsResponse>
        

Response Body Details:

  • userQuota, storageQuota, and tiered capacity (tierCreatorCapacity, tierExplorerCapacity, tierViewerCapacity) attributes are only present in the response body if those quotas have been set for the site being queried.

Response Headers

Location: /api/3.22/sites/new-site-id

Version

Version 1.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing, incomplete, or contains malformed XML.
400 400000 Invalid storage quota The storage quota value was not a positive number.
400 400000 Invalid user quota The user quota value was not a positive number.
400 400013 Invalid administrator mode The user provided an administrator mode that is not ContentOnly or ContentAndUsers.

Note: An empty string or all whitespace is invalid.

405 405000 Invalid request method Request type was not POST.
409 409001 Site name conflict The site name in the request already belongs to an existing site.
409 409002 Site URL conflict The content URI in the request already belongs to an existing site.
409 409004 User quota and tiered capacity conflict The request cannot set both tiered capacity attributes and userQuota. One or the other must be null.
409 409004 License limit exceeded The request cannot set tiered capacity attributes or userQuota