What's New in the REST API
This topic summarizes changes made to the REST API for Tableau Server and Tableau Online. All versions include updated documentation.
What's new in REST API 3.11 for Tableau Server 2021.1 and Tableau Online
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 Online
- 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 Online.
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 Online
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 Online
- 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 Online
- 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 Online, 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 Schedule and Add Data Source to 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 Online 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 Online. 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