What's New in the REST API
This topic summarizes changes made to the REST API for Tableau Server and Tableau Cloud. All versions include updated documentation.
What's new in REST API 3.21 (Tableau Cloud October 2023/ Tableau Server 2023.3)
Retired in API 3.22 (Tableau Cloud February 2024 / Server 2024.2)
In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau AI and Tableau Pulse are reimagining the data experience(Link opens in a new window).
- New List Users with Custom View as Default(Link opens in a new window) and Set Custom View as Default for Users(Link opens in a new window) methods enable you to use the REST API to manage default custom view settings for users.
- As part of the personal access tokens (PATs) enhancements, list personal access tokens(Link opens in a new window) and revoke personal access token(Link opens in a new window) methods are available for Tableau Cloud site admins and users.
- The Update Embedding Settings for Site(Link opens in a new window) method enables Tableau Server users (previously Tableau Cloud users only) to control where Tableau content can be embedded when an external application uses a Tableau connected app with OAuth 2.0 trust for authentication.
- Enable on-demand access using the Create Group(Link opens in a new window) and Update Group(Link opens in a new window) methods to allow users who are not provisioned on a Tableau Cloud site licensed with Embedded Analytics usage-based model to interact with embedded Tableau content.
- Update Workbook(Link opens in a new window) method now enables you to modify the description of a workbook.
- Create Project(Link opens in a new window) and Update Project methods(Link opens in a new window) now enable you to specify a project's owner.
- The labelCategories methods allow an administrator to create, update, or delete data label categories, giving their users more control over the classification of assets. For more information, see Data Labels in the REST API and the labelCategories methods in Metadata Methods.
Added in REST API 3.20 (Tableau Cloud June 2023)
- The new Create Data Driven Alert method enables you to create and configure a data driven alert programmatically for Tableau Cloud sites.
- New methods for Tableau Cloud extract refresh and subscriptions tasks offer more customizable frequency configuration. See:
- The Update Embedding Settings for Site(Link opens in a new window) method now enables users to control where Tableau content can be embedded when an external application uses a Tableau connected app with OAuth 2.0 trust for authentication.
- The labelValues methods allow an administrator to customize existing label values or create entirely new ones, giving their users more control over the classification of assets. For more information, see Data Labels in the REST API and the labelValues methods in Metadata Methods.
Added in REST API 3.19 (Tableau Cloud March 2023/ Tableau Server 2023.1)
- As a Tableau Server administrator, you can use the Identity Pools Methods(Link opens in a new window) to provision and authenticate Tableau Server users.
- As a Tableau Cloud site administrator, you can enable the user attributes site setting for embedding workflows using the Update Site(Link opens in a new window) method.
- Methods for working with virtual connections—previously available only for Tableau Cloud—are now available for Tableau Server. Use the List Virtual Connections method(Link opens in a new window) to get a list of virtual connections and details for each, the List Virtual Connection Database Connections method(Link opens in a new window) to retrieve database connection information, and the Update Virtual Connection Database Connections method(Link opens in a new window) to update database connection information.
- Using the new content exploration method Get content suggestions(Link opens in a new window) you can now get suggestions for relevant content returned to display completion options as a user types.
- Ask data lens(Link opens in a new window) methods now support JWT access scopes(Link opens in a new window) so that permissions to use them can be granted to connected apps.
Added in REST API 3.18 (Tableau Cloud December 2022)
New methods are available for working with virtual connections. Use the List Virtual Connections method(Link opens in a new window) to get a list of virtual connections and details for each, the List Virtual Connection Database Connections method(Link opens in a new window) to retrieve database connection information, and the Update Virtual Connection Database Connections method(Link opens in a new window) to update database connection information.
- You can use the new Get usage statistics(Link opens in a new window) and Get batch usage stats(Link opens in a new window) content exploration methods to discover how users are accessing your content.
- Mobile Settings Methods(Link opens in a new window) enable you to view and control the Tableau mobile client security settings of mobile apps that access your site.
- Custom view methods now allow you to get a list of custom views on a site(Link opens in a new window), get the details of a custom view(Link opens in a new window), download an image of it(Link opens in a new window), delete it(Link opens in a new window), or update its name or owner(Link opens in a new window).
Added in REST API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3)
- As a Tableau Cloud site admin, you can register an external authorization server (EAS) to a site to establish a trust relationship between the EAS and your site using the OAuth 2.0 standard protocol. This trust relationship enables you to provide your users with a single sign-on (SSO) experience to Tableau content embedded in your custom applications or for REST API authorization. For more information, see Site-level external authorization server (EAS) methods.
- As a Tableau Server admin, you can programatically authorize access to the Tableau REST API on users' behalf using JSON web tokens (JWTs) and Tableau connected apps. For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
- Methods to manage data labels—originally released for Tableau Cloud only—are now available for Tableau Server. Label methods offer a new, unified interface for manipulating certification and data quality warnings through the REST API. For more information, see the Data Labels in the REST API topic and the label methods in Metadata Methods.
- The ability to move databases and tables—originally released for Tableau Cloud only—is now available for Tableau Server. You can move databases and tables to projects, enabling you to control permissions through them. For more information, see the Move Database and Move Table methods in the Tableau REST API Reference.
- Now you can set data quality warnings on columns. Relevant methods for data quality warnings and data labels were updated to include support for columns.
You can now get the details of a workbook using the Get Workbook method with the content URL of the workbook (the part that appears after
…/views/…in the URL path of the workbook in your browser address bar).
Added in REST API 3.16 (Tableau Cloud June 2022)
- As a Tableau Cloud site admin, you can programatically authorize access to the Tableau REST API on users' behalf using JSON web tokens (JWTs) and Tableau connected apps. For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help.
- Label methods offer a new, unified interface for manipulating certification and data quality warnings through the REST API. For more information, see the Data Labels in the REST API topic and the label methods in Metadata Methods.
- You can move databases and tables to projects, enabling you to control permissions through them. For more information, see the Move Database and Move Table methods in the Tableau REST API Reference.
- As a Tableau Cloud site admin, you can restrict embedding of Tableau views to only certain domains of your choice. For more information see the embedding setting methods in Site Methods
Added in REST API 3.15 for Tableau Server 2022.1 and Tableau Cloud
- As a Tableau Server admin or Tableau Cloud site admin, you can list and change user notification preferences for your site. For more information, see Notifications Methods.
- The Data-Driven Alerts methods and the Webhooks methods were moved to the Notifications Methods page.
- REST API methods are now available that enable multiple users to be imported to or deleted from a site from a .csv list of users. The .csv data can also include site role and authorization settings that will be assigned for each user upon import. For more information, see Import Users to Site from CSV(Link opens in a new window) and Delete Users from Site with CSV(Link opens in a new window).
- New methods related are now available to run and get information on linked tasks. Linked tasks are used to schedule flows to run one after the other. For more information, see Flow Methods.
- New attributes to support flow parameters have been added to various flow methods including methods that are used to run flows. You can use REST API to override flow parameter values at run time. For more information, see Flow Methods.
- Methods related to certification and data quality warnings have been expanded to include support for virtual connections and virtual connection tables. For more information, see Metadata Methods.
Added in REST API 3.14 for Tableau Server 2021.4 and Tableau Cloud
- As a Tableau Server admin or Tableau Cloud site admin, you can create, query, update, and delete Tableau connected apps configured for your site. For more information, see Connected App Methods.
- The publish data source(Link opens in a new window) method now supports multi table data created using the Hyper API, as long as there is a single fact table containing the foreign key for each of the other tables in the extract.
Added in REST API 3.13 for Tableau Server 2021.3 and Tableau Cloud
- Add, update, query, and delete data quality certifications for databases, tables, and data sources using the following methods: Add (or Update) Data Quality Certifications, Query Data Quality Certification by ID, Query Data Quality Certifications by Content, Delete Data Quality Certification by ID, and Delete Data Quality Certifications by Content.
- Query databases and tables from the connection information in the data source or workbook file's XML using Get Databases and Tables from the Connection.
- Enable data quality warnings (DQWs) in subscription emails for your site using the Create Site or Update Site method.
- If needed, you can disable Explain Data per site using the Create Site or Update Site method.
- Manage default permissions for lenses and data roles with the Add Default Permissions, Query Default Permissions, Delete Default Permission methods.
- Understand Workbook Impact on Your Database Using Query Tagging.
Added in REST API 3.12 for Tableau Server 2021.2 and Tableau Cloud
- You can modify (insert, update, upsert, replace, and delete) data in a published data source that is a live-to-Hyper connection. Use Update Data in Hyper Data Source or Update Data in Hyper Connection. For more information, see Update data in published live-to-Hyper data sources.
- With the appropriate permissions, you can batch add (or update), and delete multiple data quality warning (DQW) items to and from different content and external assets using the following methods: Batch Add Data Quality Warnings and Batch Delete Data Quality Warnings.
- Server and Site administrators can now directly find the Tableau resource responsible for a problematic data source query when they enable query tagging(Link opens in a new window) through update workbook connections and update data source connections. They can view enablement status through query workbook connections and query data source connections.
Added in REST API 3.11 for Tableau Server 2021.1 and Tableau Cloud
Add quality warning triggers to extract data sources and flows.
Quality warning triggers, applied to extract data sources and flows, monitor for and display alerts, along side other DQWs, when refreshes or flow runs fail. For more information, see the following methods: Add Quality Warning Triggers, Update Quality Warning Trigger, Query Quality Warning Trigger, Query Quality Warning Triggers, Delete Quality Warning Trigger, and Delete Quality Warning Triggers.
List the Active Directory domains in use on a Tableau Server and update a domain's name and nickname on a server using the List Server Active Directory Domains and Update Server Active Directory Domain methods.
If you have Tableau Server administrator permissions, you can now use a personal access token(Link opens in a new window) (PAT), instead of a user name and password to more securely impersonate users on a server. You can also revoke all server administrator PATs using the Revoke Administrator Personal Access Tokens method. Learn more.
Added in REST API 3.10 for Tableau Server 2020.4 and Tableau Cloud
- New REST endpoints have been added to manage metrics on your Tableau site. You can now list all metrics for a site, get the details of a specified metric, update the properties of a metric, and delete a metric through REST requests.
- Analytics Extensions methods(Link opens in a new window) are now available for Tableau Cloud.
flowsEnabledattribute for sites is deprecated and is replaced with
schedulingFlowsEnabledto provide more granular control over editing and scheduling flows. For more information, see Create Site.
- You can now get a list of flow runs for a site and details of a specific flow run. You can also cancel a specific flow run. For more information, see Get Flow Run, Get Flow Runs, and Cancel Flow Run.
Added in REST API 3.9 for Tableau Server 2020.3 and Tableau Cloud
With the appropriate permissions, you can do the following:
- Add and delete tags for databases, tables, and columns using the following methods: Add Tags to Database, Add Tags to Table, Add Tags to Column, Delete Tag from Database, Delete Tag from Table, and Delete Tag from Column.
- Batch update tags on Tableau content and external assets using the following methods: Batch Add Tags and Batch Delete Tags.
- You can set a data quality warning for sensitive data. For more information, see Add Data Quality Warning.
Added in REST API 3.8 for Tableau Server 2020.2 and Tableau Cloud
- You can enable high visibility for a data quality warning using the following methods: Add Data Quality Warning and Update Data Quality Warning.
- Administrators can now enable data acceleration for specific workbooks. The workbook loads faster because Tableau Server precomputes the workbook's data in a background process. For more information, see Data Acceleration.
- The details of the current server session can now be viewed by calling Get Current Server Session. The response includes identifiers and configuration information for the current site and user.
You can now call Download Workbook PowerPoint to download images of views
and dashboards in a workbook as slides in a PowerPoint deck (
- Settings for Analytics Extensions and Dashboard Extensions can now be configured using the REST API. These endpoints introduce a new form of RESTful API to the set of Tableau automation tools. To learn more, see REST API and Resource Versions.
- Organize a user's favorites. For more information, see Favorites Methods.
Added in REST API 3.7 for Tableau Server 2020.1 and Tableau Cloud
- Administrators can now use Get Site or Update Site to view the Tiered Capacities (maximum users of a site for each license type or role) configured for a site. For a site that has user-based licensing with no licensing limits set by its administrator, maximums for Creator, Explorer, and Viewer licensed users are determined by the activated licenses for each role on the site. On-premise server administrators can set the Tiered Capacity attributes to lower the user limits on any or all of the license types using Create Site or Update Site.
- You can now get the groups a site user belongs to with a REST API call.
- You can now manage view recommendations using the REST API. Use Get View Recommendations, to get a current list of recommended views. Use Hide a View Recommendation, to hide a view from the list of recommended views. Use Unhide a View Recommendation, to hide a view from the list of recommended views.
Added in REST API 3.6 for Tableau Server 2019.4
- With the appropriate permissions, you can query, set, and delete permissions on databases and tables using the following methods: Add Database Permissions, Query Database Permissions, Add Default Database Permissions, Query Default Database Permissions, Delete Database Permissions, Delete Default Database Permissions, Add Table Permissions, Query Table Permissions, Delete Table Permissions.
- You can now use a Personal Access Token (PAT), instead of plain text username and password, to sign in to Tableau Server or Online with the REST API. Signing in with a PAT returns the same form of credentials token as a password sign in, but PATs are more secure because they are revocable, they can be easily monitored, and they avoid revealing identifying information in scripts and tools. Administrators can make the impact of each process more visible by using separate PATs for each process. PATs allow you to change sign in credentials for a user without affecting their Tableau user credentials.
- Using Tableau Webhooks(Link opens in a new window), you can now build custom applications or workflows that react to events that happen in Tableau. For example, you could use webhooks to send an SMS or Slack notification any time a data source refresh fails. Use the REST API to create and manage your webhooks for a site. This initial release enables 13 workbook, data source and view events to fire notifications to destination URL of your choosing.
Added in REST API 3.5 for Tableau Server 2019.3
- You can now manage extract encryption at rest. To learn more, see Extract Encryption Methods.
- You can query or update metadata indexed by or surfaced through Tableau Catalog. To learn more, see Metadata Methods.
- With administrator permissions, you can now globally enable or disable attachments for subscriptions to workbooks and views in a site. You can read the enablement status in response bodies for Query Sites, Query Site, Create Site, and Update Sites requests. Enablement state can be set during Create Site and Update Site calls.
Users can now determine the file format (
Added in REST API 3.4 for Tableau Server 2019.2
- You can now use the maxAge parameter of the Query View Image method to set or get the limit for the age of a cached image of a view in your workbook. When that limit is passed accessing a view image will refresh the cache with a current image.
- You can now use the public parameter of the Get Data-Driven Alert method to set or get whether users who do not own an alert can discover and subscribe to it.
- You can now use the Download Workbook PDF method to download a PDF containing the views in the a workbook.
Added in REST API 3.3 for Tableau Server 2019.1
- When you publish a workbook that contains a user filter, you can now specify which user should be used to generate thumbnails by using the generateThumbnailsAsUser attribute. To learn more, see Publish Workbook.
- You can now manage flows. To learn more, see Flow Methods, Add Flow to Favorites, and Delete Flow from Favorites.
Added in REST API 3.2 for Tableau Server 2018.3
- When you call the Publish Workbook method with hidden sheets (also known as views) those sheets are no longer included in the published workbook.
- You can now manage permissions for views using the Add View Permissions, Query View Permissions, and Delete View Permission methods.
- You can now manage data-driven alerts using the Query Data-Driven Alerts, Query Data-Driven Alert Details, Update Data-Driven Alert, Delete Data-Driven Alert, Add User to Data-Driven Alert, and Delete User from Data-Driven Alert methods.
Added in REST API 3.1 for Tableau Server 2018.2
- You can now move projects within the project hierarchy. You can now move projects to the top of the project hierarchy when using the Update Project method by passing an empty string ("") to the parentProjectId attribute of the <project> element.
- You can now manage and cancel jobs. The following methods have been updated or added in the 2018.2 release to improve the management of jobs:
- You can now manage which projects are included on a user's list of favorites, and query a list of favorites that includes favorite projects using the following methods that have been updated or added in the 2018.2 release:
- You can now publish data sources asynchronously by adding the asJob parameter to the Publish Data Source request URI. To learn more, see Publishing workbooks and data sources asynchronously.
Added in REST API 3.0 for Tableau Server 2018.1
- You can now publish workbooks that use multiple data source connections. To learn more, see Publish Workbook.
- Starting with the 2018.1 release of Tableau Server and Tableau Cloud, available site roles have changed significantly to support the new user-based Creator, Explorer and Viewer licenses. To learn more, see Updated Site Roles in REST API 3.0.
- You can now publish workbooks asynchronously by adding the asJob parameter to the Publish Workbook request URI. To learn more, see Publishing workbooks asynchronously.
- Additional fields are now available when making queries using the REST API:
- To format views, you can use the sheetType field with the Query Views for Site method.
- To see workbook descriptions, you can use the description field with the Query Workbooks for Site and Query Views for Site methods.
To learn more, see Using fields in the REST API.
Added in REST API 2.8 for Tableau Server 10.5
- You can now filter results from the Query View Image, Query View Data and Query View PDF methods by specific workbook field values. To learn more, see Filter query views.
Create or update project hierarchies. A project can now contain other projects. For more information about nested projects, see the following methods:
Add workbooks and data sources to a schedule. You can now add workbook refreshes and data source extract refreshes to an existing schedule. To learn more, see Add Workbook to Server Schedule and Add Data Source to Server Schedule.
The Update User method now supports the ServerAdministrator site role. Users who are in the ServerAdministrator site role can now add or remove other users from that site role. To learn more, see Update User.
Added in REST API 2.7 for Tableau Server 10.4
Filtering and sorting can now be performed on the following additional methods:
The permissions required to move a data source from one project to another have been improved for non-server administrators.
Users who either own the data source or the current project, or are project leaders for the current project, can update a data source if they have write permissions for the new project. See Update Data Source
Improved pagination. Results returned from methods that support pagination, such as Query Data Sources or Query Projects, are now indexed and sorted internally, ensuring consistent results across method calls. See How Elements are Ordered.
- Certification notes and status. The Update Data Source method now supports setting certification status and adding a certification note. To learn more about data source certification, see Use Certified and Recommended Data Sources and Tables.
Added in REST API 2.6 for Tableau Server 10.3
New feature for querying a site for refresh tasks and running an extract refresh job. For more information, see the following methods:
New methods for tagging data sources and views.
New method that makes it easy to switch sites. You no longer need to provide a user name and password every time. See Switch Site.
Update to Query Sites. No longer just for server administrators. Now returns only the sites that the user making the call has access to.
Added in REST API 2.5 for Tableau Server 10.2
New method for getting views and workbooks that a user has marked as favorites. For more information, see Get Favorites for User.
New method for getting images for views. You can get images in standard resolution and high resolution. For more information, see Query View Image.
A new feature you can use to control the type and amount of data you want returned from some methods. You can qualify the return values based upon the type of resource (for example, workbooks or views), and fields (names, ids, and tags). You can include multiple fields in a request. You can combine this feature with filtering and sorting. For example, you can return the names of the all workbooks that were updated after a certain date. For more information, see Using Fields in the REST API.
Support for JSON in the REST API. You can set
application/xmlto control whether you want send requests or receive responses in XML or JSON. For more information, see Fundamentals of the Tableau Server REST API and REST API Example Requests.
Download workbooks or data sources without including the extracts. You can now download a data source or workbook without the large payload of the extract file by simply appending
?includeExtract=Falseto the URI. For more information, see the following methods:
New option to publish the Tableau provided sample workbooks when you create or update a project. For more information see the following methods:
Added in REST API 2.4 for Tableau Server 10.1
The Server Info method returns information about the version of Tableau Server and the version of the REST API compatible with the server.
Site administrators can now use the method to Query Workbooks for a User. Previously, only server administrators had permission to use this method.
Filtering and sorting can be performed on the following additional methods:
Added in REST API 2.3 for Tableau Server 10.0
A new feature that lets you add filter (
tags, and so on) to some methods. For example, instead of having to get all the users or workbooks for a site and then loop through them looking for a specific ones, you can add a filter to the method call to return just the users or workbooks you're interested in. You can also specify sort parameters to return the items in a defined order.
For more information, see Filtering and Sorting in the REST API.
New and updated methods for viewing, downloading, and removing versions (revisions) for workbooks and data sources:
Query Site. Now returns information about versioning settings for the site.
Update Site. Now lets you change versioning settings for the site.
New methods for creating and deleting schedules:
New methods for creating, viewing, and deleting subscriptions:
New methods for adding and removing data sources from a user's favorites:
New and updated methods for working with multiple connections in a data source. Starting with Tableau Server 10.0, data sources can have multiple connections. This version of the REST API includes the following changes:
Update Data Source Connection. This method has new syntax that lets you specify which connection in a data source you want to update.
Note: If the data source was created in Tableau 9.3 or earlier, the previous syntax for this method(Link opens in a new window) (without
/connections/connection-idin the URI) will work for updating that data source. However, we recommend that you use the syntax documented here for all data sources.
Query Data Source Connections. This new method returns information about all the connections in a data source.
Updates to the Update Site to let you upload a new logo image to a Tableau Cloud site.
Added in REST API 2.2 for Tableau Server 9.3
New methods for querying schedules and tasks:
The Query Views for Sites method.
A new append parameter for the Publish Data Source method that lets you add data to a data source that was published previously.
sizeattribute was added to the response for these methods:
updatedAtattributes were added to the response for these methods:
Added in REST API 2.1 for Tableau Server 9.2
New methods for setting default permissions. The REST API now has the following methods that let you set, view, and remove default permissions for a project. Default permissions let you specify a set of permissions that are applied to new content in a project.
Updated methods to support locking of project permissions. Permissions in a project can now be "locked" so that users cannot change permissions on individual workbooks or data sources in that project. The following methods have been updated in the REST API to enable you to lock or unlock permissions, or to view project default permissions.
Changes to the project capabilities that you can set or delete permissions for. Starting in Tableau Server 9.2, projects support only these capabilities: Read (view), Write (save), and ProjectLeader. (In Tableau Server 9.1 and earlier, you could set capabilities that could apply to all content in the project.)
Note: This is a change in the permissions model for Tableau Server itself, not just in the API. In Tableau Server 9.2, you cannot set permissions for any project capability except the ones listed here, even if you specify a previous version of the REST API in the URI.
This change affects the following methods:
To set capabilities that apply to content in the project, you can use the new methods for setting default permissions (see earlier items in this list).
Updated permissions for some methods to allow them to be called by site administrators in addition to server administrators. This also has the effect of making those methods available in Tableau Cloud. These are the affected methods:
A new Delete Group method.
Changes to required permissions for working with project permissions. In previous versions of the REST API, users who are not administrators can call Add Project Permissions or Delete Project Permission if they have ChangePermissions permissions. In REST API 2.1, users must instead have ProjectLeader permissions.
More rigorous checking to be sure that payloads are well formed. The REST API now requires the structure of payloads to conform strictly to the XML schema (see next point) and to the applicable RFC specifications. For example, the payloads for methods that allow multi-part publishing (Append to File Upload, Publish Data Source, and Publish Workbook) must meet the RFC 1341 standard(Link opens in a new window) for multi-part payloads.
The practical effect is that in some cases, payloads that were accepted in earlier versions of the REST API now cause an error and return a 500-level HTTP code. For example, in the Append to File Upload method, the first part of the payload is often blank, containing only
content-typeheaders. With the change in the REST API 2.1, this blank payload must include two blank lines, per the RFC specification. Earlier versions of the REST API allowed you to include only one blank line, even though this structure did not conform exactly to the RFC specification.
A new XML schema (version 2.1) for the REST API. For more information, see REST API XML Schema(Link opens in a new window).
Updated versions of the Python and Java samples. For more information, see REST API Samples(Link opens in a new window).
Added in in REST API 2.0.1 for Tableau Server 9.1
Updated namespace. The namespace and schema locations that are returned in the <tsResponse> blocks of REST API responses have been changed from