Workbooks and Views Methods

Using the workbooks and views methods of the Tableau Server REST API you can do the operations listed in the following categories:

Workbooks (configurations of data sources and views in a site)

Get a filtered, sorted list of all or selected fields of workbooks of a site.
Get a list of workbooks a user has read access to or that they own.
Get or update the details of a specific workbook.
Update (refresh) the extract of a workbook.
List the data sources of a workbook or update the details of a datasource.
Publish a workbook to a specific site as a single part or in multiple parts.
Download or delete a specific workbook.
Download a specific revision of a workbook.
Download images of the sheets of a workbook as a .pdf or .pptx file.
Download the crosstab data of a specific view to an .xlsx file.
Download an encrypted keychain for a workbook that is migrating to another site.
Upload an encrypted keychain for a workbook migrated to another site.

Views (sheets of a workbook in a site)

Get a filtered, sorted list of all or selected fields of views in a site.
Get a list of views for a workbook and the usage statistics for each view.
Get the data, a full or thumbnail .png image, or a .pdf of a selected view.
Get a thumbnail of the default (first) view of a workbook.

Custom Views (sheets of a workbook in a site)

Get a list of custom views on a site, get the details of a custom view, or download an image of a custom view.
Delete a custom view or update the name or owner of a custom view.
Get a list of users that have a specified custom view configured as their default view.
Configure a custom view as the default view for specified users.

Tags (keywords added to workbooks, views, data sources, and flows)

Add or delete tags of a Workbook or Site.

View Recommendations (Recommended Views that are displayed on the server Home and Recommendations pages)

Get a list of the currently recommended views on a site.
Hide or unhide views from being recommendable to a user by adding them to or removing them from a list of views that are dismissed for the user.

This functionality relates to the UI elements and concepts described at: Workbooks and Sheets(Link opens in a new window).

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.26`. 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.26/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.26`. 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.26/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>

Delete Custom View

Deletes the specified custom view.

Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1). Version Overview

License: No additional license required.

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

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

URI

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

URI Parameter Values

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

Request Body

None.

Required scope for JWT authorization

Introduced in Tableau Cloud December 2022 (API 3.18) .

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

tableau:views:update

cURL Request Example

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

Response Code

201

Response Body

None.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Delete Tag from View

Deletes a tag from the specified view.

URI

DELETE /api/api-version/sites/site-id/views/view-id/tags/tag-name

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
view-id	The ID of the view to remove the tag from.
tag-name	The name of the tag to remove from the view.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or workbook owners can delete a tag from a workbook only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400078	Error deleting tag	There was a problem deleting the tag from the specified view.
403	403004	Deleting tags forbidden	A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.
404	404000	Site not found	The site ID or URL namespace in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
404	404007	Tag not found	The tag in the URI doesn't exist for the specified workbook.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Delete Tag from Workbook

Deletes a tag from the specified workbook.

URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/tags/tag-name

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to remove the tag from.
tag-name	The name of the tag to remove from the workbook.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or workbook owners can delete a tag from a workbook only if they are project leaders or if they originally added the tag.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400051	Error deleting tag	There was a problem deleting the tag from the specified workbook.
403	403004	Deleting tags forbidden	A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.
404	404000	Site not found	The site ID or URL namespace in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
404	404007	Tag not found	The tag in the URI doesn't exist for the specified workbook.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Delete Workbook

Deletes a workbook. When a workbook is deleted, all of its assets are also deleted, including associated views, data connections, and so on.

URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id

Parameter Values

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

Request Body

None

Permissions

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

Response Code

204

Response Body

None

Version

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

Errors

HTTP status	`error` Code	Condition	Details
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Download View Crosstab Excel

Downloads an Excel (.xlsx) file containing crosstab data from a view that the user has permission to access in a workbook. If a crosstab is exported from a dashboard, data from only the first view in the dashboard will appear in the .xlsx file. Downloads of data from story dashboards are not supported at this time.

If you make multiple requests for an .xlsx, subsequent calls return a cached version of the file. This means that the returned .xlsx might not include the latest changes to the workbook. To decrease the amount of time that a workbook is cached, use the maxAge parameter.

Note the data exported is at a summary level only. Detail level data is only available as a download option in the user interface.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

URI

GET /api/api-version/sites/site-id/views/view-id/crosstab/excel

GET /api/api-version/sites/site-id/views/view-id/crosstab/excel?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/views/view-id/crosstab/excel?vf_<fieldname>=filter-value

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
view-id	The ID of the view to use as the source of the crosstab to be downloaded as an `.xlsx` file.
max-age-minutes	(Optional) The maximum number of minutes an `.xlsx` file will be cached on the server before being refreshed. To prevent multiple `.xlsx` requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
filter-value	The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter `/excel?vf_year=2017` would only display data from the year 2017. To learn more, see View filter queries.

Request Body

None

Permissions

To export a crosstab to an .xlsx of a view, users who are not server administrators or site administrators need Read and ExportData permissions for the workbook containing the view and for the view itself.

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .xlsx file. The response header content will have Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400101	Unknown error	There was a problem downloading or querying this file.
400	400130	Unknown error	The view ID in the URI doesn't correspond to a view available on the specified site.
401	4001XX	Unauthorized	The authentication token for the request is missing, invalid, or expired.
403	4031XX	Unauthorized	A user attempted to download a .xlsx file without Read and/or ExportData permissions for the workbook or view, and is not an administrator.
404	404xxx	Site or view not found	The site or view specified in the request could not be found.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/crosstab/excel?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response is a file that contains the crosstab, whose data is no older than 60 minutes, saved as an .xlsx file.

Download Workbook

Downloads a workbook in .twb or .twbx format.

Security note: Content in .twb or .twbx files downloaded using this method is stored in plain text. All data, including filter values that may give semantic clues to the data, will be readable by anyone who opens the files.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/content

GET /api/api-version/sites/site-id/workbooks/workbook-id/content?includeExtract=extract-value

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to download.
extract-value	(Optional) The extract-value is a Boolean value (`False` or `True`). When the workbook specified for download has an extract, if you add the parameter `?includeExtract=False`, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can download a workbook only if they have ExportXml permission for the workbook (either explicitly or implicitly).

Required scope for JWT authorization

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

tableau:workbooks:download

Response Code

200

Response Body

One of the following, depending on the format of the workbook:

The workbook's content in .twb format (Content-Type: application/xml)
The workbook's content in .twbx format (Content-Type: application/octet-stream)

In both cases, the response will have the following content disposition header:

Content-Disposition: name="tableau_workbook"; filename="workbook-filename"

Version

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

Errors

HTTP status	`error` Code	Condition	Details
403	403019	Read forbidden	A non-administrator user attempted to download a workbook, but the caller doesn't have ExportXml permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > c:\files\my-workbook.twbx

The response is a file that contains the workbook.

Download Workbook Encrypted Keychain

Gets an encrypted version of the embedded credentials from the workbook. These credentials can only be migrated to the linked destination Tableau Cloud or Tableau Server.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

Version: Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

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

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

POST /api/api-version/sites/site-luid/workbooks/workbook-luid/retrieveKeychain

URI Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-luid	The LUID for the site.
workbook-luid	The LUID of the workbook to download the encrypted keychain from.

Request Body

<tsRequest>
  <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace>
  <destinationSiteLuid>d56023b5-8f8b-4241-aa74-8974ced85827</destinationSiteLuid>
  <destinationServerUrl>http://localhost</destinationServerUrl>
</tsRequest>

{
  "destinationSiteUrlNamespace": "site1",
  "destinationSiteLuid": "d56023b5-8f8b-4241-aa74-8974ced85827",
  "destinationServerUrl": "http://localhost"
}

Request Attributes

`destinationSiteUrlNamespace`	(Required) The site name on Tableau Cloud.
`destinationSiteLuid`	(Required) The site ID on Tableau Cloud.
`destinationServerUrl`	(Required) The destination Tableau Cloud URL.

cURL Request Example

curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/retrieveKeychain"  --header "Content-Type: application/xml"  --header "X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86"  --data "<tsRequest>   <destinationSiteUrlNamespace>site1</destinationSiteUrlNamespace>    <destinationSiteLuid>9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d</destinationSiteLuid>   <destinationServerUrl>http://example.com</destinationServerUrl>  </tsRequest>"

Response Code

200

Response Body

<tsResponse>
   <associatedUserLuidList/>
   <encryptedKeychainList>
     <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyKgNw5FnJud0etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/py5okFzVW4wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oCS5wRNtJ6lGz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1L2q9VyhVr8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKhsBZyFrVY7Wtf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ13hV0jXW7nXUhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain>
   </encryptedKeychainList>
</tsResponse>

{
  "associatedUserLuidList": [],
  "encryptedKeychainList": {
    "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyKgNw5FnJud0etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/py5okFzVW4wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oCS5wRNtJ6lGz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1L2q9VyhVr8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKhsBZyFrVY7Wtf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ13hV0jXW7nXUhfIW7o5iUtbYWrpCvVwubZLf4U5Y="
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not POST.

For more information, see Handling Errors.

Download Workbook PDF

Downloads a .pdf containing images of the sheets that the user has permission to view in a workbook.

Download Images/PDF permissions must be enabled for the workbook (true by default). If Show sheets in tabs is not selected for the workbook, only the default tab will appear in the .pdf file. If you make multiple requests for a PDF, subsequent calls return a cached version of the file. This means that the returned PDF might not include the latest changes to the workbook. To decrease the amount of time that a workbook is cached, use the maxAge parameter.

Version: Available in API 3.4 and later.

License: No additional license required.

Permissions: To download a .pdf of a workbook, Tableau Server users who are not server administrators or site administrators need Read and ExportImage permissions for the workbook. The user needs Read and ExportImage permissions for a view in a workbook in order for that view to appear in the .pdf.

Access Scope: tableau:workbooks:download

For more information, see Versions(Link opens in a new window), Permissions(Link opens in a new window), and access scopes for Cloud(Link opens in a new window), Server-Windows,(Link opens in a new window) or Server-Linux(Link opens in a new window).

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?type=page-type&orientation=orientation

GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?maxAge=max-age-minutes

Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later:

GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?vf_fieldname>=filter-value

Available in API 3.26 (Tableau Cloud June 2025) and later, but not available in Tableau Server:

GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?vizHeight=viz-height&vizWidth=viz-width

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to use as the source of the .pdf file to be downloaded.
max-age-minutes	(Optional) The maximum number of minutes a workbook PDF will be cached before being refreshed. To prevent multiple PDF requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
orientation	(Optional) The orientation of the pages in the .pdf file produced. The value can be `Portrait` or `Landscape`. If this parameter is not present the page orientation will default to `Portrait`.
page-type	(Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be: `A3`, `A4`, `A5`, `B5`, `Executive`, `Folio`, `Ledger`, `Legal`, `Letter`, `Note`, `Quarto`, or `Tabloid`. If this parameter is not present the page type will default to `Legal`.
fieldname=filter-value	Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later: (Optional) An expression that applies a granular filter to the request. Returns will be based on the value (filtervalue) of the dimension or measure (fieldname) of your view data you specify. For more information, see View filter queries.
viz-height	(Optional) The height of the rendered pdf image in pixels that, along with the value of `vizWidth`, determines its resolution and aspect ratio.
viz-width	(Optional) The width of the rendered pdf image in pixels that, along with the value of `vizHeight`, determines its resolution and aspect ratio.

Request Body

None

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .pdf file. The response header content will have Content-Type:application/pdf.

Errors

HTTP status	`error` Code	Condition	Details
400	400101	Unknown error	There was a problem downloading or querying this workbook.
403	403004	Unauthorized	A non-administrator user attempted to download a pdf, but they don't have Read and/or ExportImage permissions for the workbook or user does not have Read permissions for the views of the workbook.
403	403105	Unauthorized	The PDF export feature is disabled on the server or the server is not configured to allow PDF exports using the REST API.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

cURL Request Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/pdf?maxAge=60"  -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"  -o "response.pdf"

The response is a file that contains the workbook, whose data is no older than 60 minutes, is saved as a pdf.

Download Workbook PowerPoint

Downloads a PowerPoint (.pptx) file containing slides with images of the sheets that the user has permission to view in a workbook. Download Images/PDF permissions must be enabled for the workbook (true by default). If Show sheets in tabs is not selected for the workbook, only the default tab will appear in the .pptx file.

If you make multiple requests for a .pptx, subsequent calls return a cached version of the file. This means that the returned .pptx might not include the latest changes to the workbook. To decrease the amount of time that a workbook is cached, use the maxAge parameter.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/powerpoint

GET /api/api-version/sites/site-id/workbooks/workbook-id/powerpoint?maxAge=max-age-minutes

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to use as the source of the `.pptx` file to be downloaded.
max-age-minutes	(Optional) The maximum number of minutes a workbook `.pptx` will be cached before being refreshed. To prevent multiple `.pptx` requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.

Request Body

None

Permissions

To download a .pptx of a workbook, Tableau Server users who are not server administrators or site administrators need Read and ExportImage permissions for the workbook. The user needs Read and ExportImage permissions for a view in a workbook in order for that view to appear in the .pptx.

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .pptx file. The response header content will have Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation.

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400101	Unknown error	There was a problem downloading or querying this workbook.
401	4001XX	Unknown error	There was a problem downloading or querying this workbook.
403	4031XX	Unauthorized	A non-administrator user attempted to download a .pptx file, but they don't have Read and/or ExportImage permissions for the workbook or user does not have Read permissions for the views of the workbook.
403	403105	Unauthorized	The PowerPoint export feature is disabled on the server or the server is not configured to allow PowerPoint exports using the REST API.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/powerpoint?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -o "response.pptx"

The response is a file that contains the workbook, whose data is no older than 60 minutes, saved as a .pptx.

Download Workbook Revision

Downloads a specific version of a workbook in .twb or .twbx format.

Note: This method is available only if version history is enabled for the specified site. For more information, see

Maintain a History of Revisions in the Tableau Server Help.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content?includeExtract=extract-value

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to download.
revision-number	The revision number of the workbook to download. To determine what versions are available, call Get Workbook Revisions. Note that the current revision of a workbook cannot be accessed by this call; use Download Workbook instead.
extract-value	(Optional) The extract-value is a Boolean value (`False` or `True`). When the workbook specified for download has an extract, if you add the parameter `?includeExtract=False`, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Users who are site administrators can download workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can download workbook revisions if they have all of the following:

A site role of ExplorerCanPublish.
Read (view), Write (save), and Download (save as) permissions for the specified workbook.
Save (write) permissions for the project that contains the workbook.

Required scope for JWT authorization

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

tableau:workbooks:download

Response Code

200

Response Body

One of the following, depending on the format of the workbook:

The workbook's content in .twb format (Content-Type: application/xml)
The workbook's content in .twbx format (Content-Type: application/octet-stream)

In both cases, the response will have the following content disposition header:

Content-Disposition: name="tableau_workbook"; filename="workbook-filename"

Version

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

Errors

HTTP status	`error` Code	Condition	Details
403	403053	Version history not enabled	version history is not enabled for the specified site.
403	403019	Read forbidden	A non-administrator user attempted to download a workbook, but the caller doesn't have required permissions.
404	404024	Workbook revision not found	The revision number in the URI doesn't correspond to an existing data source revision.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Get Custom View

Gets the details of a specified custom view.

Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1). Version Overview

License: No additional license required.

Permissions: Tableau administrators can get the details of a custom view. Other users can get the details of any custom view that they have Read permissions for. Permissions Overview

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

URI

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

URI Parameter Values

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

Request Body

None.

Required scope for JWT authorization

Introduced in Tableau Cloud December 2022 (API 3.18) .

tableau:content:read

cURL Request Example

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

Response Code

200

Response Body

<tsResponse >
  <pagination pageNumber="1" pageSize="100" totalAvailable="1673"/>
  <customView
    id="37d015c6-bc28-4c88-989c-72c0a171f7aa"
    name="New name 2"
    createdAt="2016-02-03T23:35:09Z"
    updatedAt="2022-09-28T23:56:01Z"
    lastAccessedAt="2022-09-28T23:57:12Z"
    shared="false">
      <view id="8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f" name="circle"/>
      <workbook id="2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5" name="marks and viz types 2"/>
      <owner id="cdfe8548-84c8-418e-9b33-2c0728b2398a" name="workgroupuser"/>
  </customView>
</tsResponse>

{
  "pagination": {
	"pageNumber": "1",
	"pageSize": "100",
	"totalAvailable": "1673"
  },
  "customView": {
	"id": "37d015c6-bc28-4c88-989c-72c0a171f7aa",
	"name": "New name 2",
	"createdAt": "2016-02-03T23:35:09Z",
	"updatedAt": "2022-09-28T23:56:01Z",
	"lastAccessedAt": "2022-09-28T23:57:12Z",
	"shared": "false",
	"view": {
	  "id": "8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f",
	  "name": "circle"
	},
  	"workbook": {
	  "id": "2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5",
	  "name": "marks and viz types 2"
	},
	"owner": {
	  "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
	  "name": "workgroupuser"
    }
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Get Custom View Data

Returns a specified custom view rendered as data in comma separated value (CSV) format.

Version: Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later.

License: No additional license required.

Permissions: Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) and Export data permissions for the underlying view (either explicitly or implicitly).

Access Scope: tableau:views:download

CSV data is provided in the response body, rather than as a download. If the request is for a dashboard, only data for the dashboard's first view is returned.

If you make multiple requests for a custom view's data, subsequent calls return a cached version of the data. This means that the returned data might not include the latest changes to the custom view. To decrease the amount of time that data of a custom view is cached, use the maxAge parameter. Default age of data is 60 minutes.

For Tableau Cloud, concurrent requests to endpoints that start long-running jobs, including this one, are limited to 20 at a time. A 429 HTML reponse means that a request exceeded the limit and should be retried at a later time. (introduced September 2021).

Note the data exported is at a summary level only. Detail level data is only available as a download option in the user interface.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

URI

GET /api/api-version/sites/site-id/customviews/custom-view_luid/data

GET /api/api-version/sites/site-id/customviews/custom-view_luid/data?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/customviews/custom-view_luid/data?vf_fieldname>=filter-value

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the view.
custom-view-luid	The ID of the view to render as data.
max-age-minutes	(Optional) The maximum number of minutes view data will be cached before being refreshed. To prevent multiple view data requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
fieldname=filter-value	(Optional) An expression that applies a granular filter to the request. Returns will be based on the value (filtervalue) of the dimension or measure (fieldname) of your view data you specify. For more information, see View filter queries.

Request Body

None

cURL Request

curl "http://MY-SERVER/api/3.26/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/customviews/2474164d-8d37-4a4c-abc7-c2070fd25fd5/data?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

The response body contains view data in CSV format no more than 60 minutes old.

Month of Date,Year of Date,Above Median?,Avg. Median
January,1893,below median,-1.0
January,1864,below median,-0.9
January,1861,below median,-0.9
December,1862,below median,-0.9
March,1917,below median,-0.8
December,1892,below median,-0.8
February,1862,below median,-0.8
February,1911,below median,-0.8
February,1917,below median,-0.8
May,1861,below median,-0.8
November,1862,below median,-0.8
March,1898,below median,-0.8
December,1860,below median,-0.8
January,1862,below median,-0.7
March,1850,below median,-0.7
February,1893,below median,-0.7
December,1870,below median,-0.7

Errors

HTTP status	`error` Code	Condition	Details
400	400080	Bad Request	The view ID in the URI doesn't correspond to a view available on the specified site.
401	401002	Unauthorized	The authentication token provided in the request header was invalid or has expired.
403	403032	Read forbidden	A non-administrator user attempted to get custok views, but the caller doesn't have Read or Expot imagepermission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.
429	429000	Concurrent request limit exceeded	For Tableau Cloud, the cumulative number of concurrent requests has exceeded the limit of 20. This limit applies to long-running jobs such as exports and downloads for view data, images, .pdf or .pptx files, datasources, and crosstabs, Retry this request at a later time. Introduced September 2021.

For more information, see Handling Errors.

Get Custom View Image

Downloads a .png format image file of a specified custom view.

Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1). Version Overview

License: No additional license required.

Permissions: Tableau administrators download the image of a custom view. Other users candownload the image of any custom view that they have Publish permissions for. Permissions Overview

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

URI

GET /api/api-version/sites/site-luid/customviews/custom-view-luid/image

GET /api/api-version/sites/site-id/customviews/view-id/image?resolution=image-resolution

GET /api/api-version/sites/site-id/customviews/view-id/image?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/customviews/view-id/image?vf_<fieldname>=filter-value

URI Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-luid	The LUID for the site.
custom-view-luid	The LUID for the custom view being updated.
image-resolution	(Optional) The resolution of the image. Image width and actual pixel density are determined by the display context of the image. Aspect ratio is always preserved. Set the value to `high` to ensure maximum pixel density.
max-age-minutes	(Optional) The maximum number of minutes a view image will be cached before being refreshed. To prevent multiple image requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
filter-value	The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter `/data?vf_year=2017` would only display data from the year 2017. To learn more, see View filter queries.

Request Body

None.

Required scope for JWT authorization

Introduced in Tableau Cloud December 2022 (API 3.18) .

tableau:views:download

cURL Request Example

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

Response Code

200

Response Body

None. Tableau returns a an image file as a download.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Get Custom View PDF

Returns a specified custom view rendered as a .pdf file.

Version: Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later.

License: No additional license required.

Permissions: Tableau Serverand site administrators can get custom views as PDFs. Other users can do this only if they have Read (view) and Export image permissions for the views (either explicitly or implicitly).

Access Scope: tableau:views:download

If you make multiple requests for a PDF, subsequent calls return a cached version of the file. This means that the returned PDF might not include the latest changes to the custom view. To decrease the amount of time that an PDF is cached, use the maxAge parameter.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

URI

GET /api/api-version/sites/site-luid/customviews/custom-view-luid/pdf

GET /api/api-version/sites/site-luid/customviews/custom-view-luid/pdf?vizHeight=viz-height&vizWidth=viz-width

GET /api/api-version/sites/site-luid/customviews/custom-view-luid/pdf?maxAge=max-age-minutes

GET /api/api-version/sites/site-luid/customviews/custom-view-luid/pdf?type=page-type&orientation=orientation

GET /api/api-version/sites/site-luidcustomviews/custom-view-luid/pdf?vf_fieldname=filter-value

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-luid	The ID of the site that contains the view.
custom-view-luid	The ID of the view to render as a .pdf file.
viz-height	(Optional) The height of the rendered pdf image in pixels that, along with the value of `vizWidth`, determines its resolution and aspect ratio.
viz-width	(Optional) The width of the rendered pdf image in pixels that, along with the value of `vizHeight`, determines its resolution and aspect ratio.
max-age-minutes	(Optional) The maximum number of minutes a view PDF will be cached before being refreshed. To prevent multiple PDF requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
orientation	(Optional) The orientation of the pages in the .pdf file produced. The value can be `Portrait` or `Landscape`. If this parameter is not present the page orientation will default to `Portrait`.
page-type	(Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be: `A3`, `A4`, `A5`, `B5`, `Executive`, `Folio`, `Ledger`, `Legal`, `Letter`, `Note`, `Quarto`, or `Tabloid`. If this parameter is not present the page type will default to `Legal`.
fieldname=filter-value	(Optional) An expression that applies a granular filter to the request. Returns will be based on the value (filtervalue) of the dimension or measure (fieldname) of your view data you specify. For more information, see View filter queries.

Request Body

None

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .pdf file. The response header content will have Content-Type:application/pdf.

cURL Example

curl "http://MY-SERVER/api/3.26/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84dcustomviews/2474164d-8d37-4a4c-abc7-c2070fd25fd5/pdf/maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response is a file that contains the view, whose data is no older than 60 minutes, saved as a pdf.

Errors

HTTP status	`error` Code	Condition	Details
400	400080	Bad Request	The view ID in the URI doesn't correspond to a view available on the specified site.
401	401002	Unauthorized	The authentication token provided in the request header was invalid or has expired.
403	403032	Read forbidden	A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Get View

Gets the details of a specific view.

Version: Available in API 3.0 and later.

License: No additional license required.

Permissions: For users who are not server administrators or site administrators, the method returns only the views that the user owns or has Read permissions for (either explicitly or implicitly).

Access Scope: tableau:content:read

Access scope introduced in API 3.16 (Tableau Cloud June 2022 / Tableau Server 2022.3)

URI

GET /api/api-version/sites/site-id/views/view-id?includeUsageStatistics=get-usage-information

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the group.
view-id	The ID of the view whose details are requested.
(Optional) get-usage-information	true to return usage statistics. The default is false.

Request Body

None

Response Code

200

Response Body

<tsResponse>
	<view id="view-id"
	  name="view-name"
	  contentUrl="path-to-view"
	  createdAt="created-date"
	  updatedAt="updated-date"
	  viewUrlName="view-url-name">
	    <workbook id="workbook-id"/>
		<owner id="owner-id"/>
		<project id="project-id"/>
		<tags/>
	</view>
</tsResponse>

{
  "view": {
    "id": "view-id",
    "name": "view-name",
    "contentUrl": "path-to-view",
    "createdAt": "created-date",
    "updatedAt": "updated-date",
    "viewUrlName": "view-url-name",
    "workbook": {
      "id": "workbook-id"
    },
      "owner": {
      	  "id": "owner-id"
    },
      "project": {
      	  "id": "project-id"
    },
      "tags": []
  }
}

Errors

404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Resource not found	The view ID in the URI doesn't correspond to an existing view.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

cURL Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6ds" -X GET -H "X-Tableau-Auth:RDEj_zqgQtGGcCiD3BXnSA|abXWv8thv5ocrXLNU7axCicQu3UdfgeX"

Example response:

<tsResponse>
  <view id="57dc5674-23aa-4a83-b3d4-8653cf3c735f"
	name="Sheet 1"
	contentUrl="workbook/sheets/Sheet1"
	createdAt="2019-05-07T17:59:42Z"
	updatedAt="2019-05-07T17:59:48Z"
	viewUrlName="view-name">
	  <workbook id="0cee459c-9640-4d10-a33d-c6ee98b72beb"/>
	  <owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
	  <project id="0ef6e0e6-b775-4d0c-8a1c-1b82e6343526"/>
	  <tags/>
  </view>
</tsResponse>

Get View by Path

Gets the details of all views in a site with a specified name.

Version: Available in API 3.6 and later.

License: No additional license required.

Access Scope: tableau:content:read

Access scope introduced in API 3.16 (Tableau Cloud June 2022 / Tableau Server 2022.3)

URI

GET /api/api-version/sites/site-id/views?filter=viewUrlName:eq:view-name

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the group.
view-name	The name of the view as it appears in the URL to the view. For `https://MY_SERVER/#/MY_SITE/views/workbook-name/Sheet1?:iid=1`, the name would be `Sheet1`.

Request Body

None

Response Code

200

Response Body

<tsResponse>
	<view id="view-id"
	  name="view-name"
	  contentUrl="path-to-view"
	  createdAt="created-date"
	  updatedAt="updated-date"
	  viewUrlName="view-name"  >
		<workbook id="workbook-id" />
		<owner id="owner-id" />
		<project id="product-id" />
		<tags/>
	</view>
	<!-- potential additional views with the same name -->
</tsResponse>

{
  "view": {
    "id": "view-id",
    "name": "view-name",
    "contentUrl": "path-to-view",
    "createdAt": "created-date",
    "updatedAt": "updated-date",
    "viewUrlName": "view-name",
    "workbook": {
      "id": "workbook-id"
    },
    "owner": {
      "id": "owner-id"
    },
    "project": {
      "id": "product-id"
    },
    "tags": []
  }
 }

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

Errors

404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Resource not found	The view ID in the URI doesn't correspond to an existing view.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

cURL Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views?filter=viewUrlName:eq:Sheet1" -X GET -H "X-Tableau-Auth:RDEj_zqgQtGGcCiD3BXnSA|abXWv8thv5ocrXLNU7axCicQu3UdfgeX"

Example response:

<tsResponse>
  <view id="57dc5674-23aa-4a83-b3d4-8653cf3c735f"
	name="Sheet 1"
	contentUrl="workbook/sheets/Sheet1"
	createdAt="2019-05-07T17:59:42Z"
	updatedAt="2019-05-07T17:59:48Z">
	viewUrlName="Sheet1" >
 	  <workbook id="0cee459c-9640-4d10-a33d-c6ee98b72beb"/>
	  <owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
	  <project id="0ef6e0e6-b775-4d0c-8a1c-1b82e6343526"/>
	  <tags/>
  </view>
</tsResponse>

Get Recommendations for Views

Gets a list of views that are recommended for a user. Using machine learning, the server will match preferences between similar users and recommend content that is most popular and recently viewed. When a recommended view is selected and not marked as hidden, it appears on the server Home and Recommendations pages.

URI

GET /api/api-version/sites/site-id/recommendations/?type=view

Path Parameters

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The LUID of the site that contains the group.

Request Body

None

Permissions

This method can be called by any site user or administrator.

Response Code

200

Response Body

<tsRequest>
 <recommendations>
   <recommendation score="recommendation_score">
     <view id="view_id" />
     <similarUsersExplanation>
       <users>
         <user id="user_id_1" />
         <user id="user_id_2" />
       </users>
     </similarUsersExplanation>
   </recommendation>
   <recommendation score="recommendation_score">
     <view id="view_id" />
     <popularExplanation />
   </recommendation>
 </recommendations>
</tsRequest>

Version

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

Errors

HTTP status	`error` Code	Condition	Details
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/recommendations?type=view" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsRequest>
 <recommendations>
   <recommendation score="94.100233876">
     <view id="0f0d33ac-027d-42a7-94bf-4f0b13e07652" />
     <similarUsersExplanation>
       <users>
         <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
         <user id="f33n9d9c-8b8a-8f8e-7d7c-7b7a6f6d0p12" />
       </users>
     </similarUsersExplanation>
   </recommendation>
   <recommendation score="94.038491833">
     <view id="w33533ac-027d-42a7-94bf-4f0b13e0so32" />
     <popularExplanation />
   </recommendation>
 </recommendations>
</tsRequest>

Get Workbook Downgrade Info

Returns a list of the features that would be impacted, and the severity of the impact, when a workbook is exported as a downgraded version (for instance, exporting a v2019.3 workbook to a v10.5 version).

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/downGradeInfo?productVersion=downgrade-target-version

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook that downgrade info is being shown for.
workbook-id	The ID of the workbook being downgraded.
downgrade-target-version	The Tableau release version number the workbook is being downgraded to.

Request Body

None

Permissions

Tableau Server users who are site administrators can get downgrade information for workbooks on the site that they are administrators for. Users who are not server administrators or site administrators can get downgrade information for workbooks they have permissions to.

Response Code

200

Response Body

<tsResponse>
  <downgradeInfo>
	<downgradedFeature name="feature-downgraded-name" severity="level-of-severity"/>
	<!-- more downgraded feature info -->
  </downgradeInfo>
</tsResponse>

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400114	Unknown downgrade error	The workbook cannot be exported to a downgraded version due to an unknown error.
400	400115	Invalid downgrade version	The downgrade version specified is not a valid Tableau version number.
400	400116	Downgrade version not supported	The downgrade version specified refers to a Tableau version that is not supported.
403	40310	Access to downgrade info denied	The caller does not have permissions required to access download info for this workbook.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Get Workbook Revisions

Returns a list of revision information (history) for the specified workbook.

Note: This method is available only if version history is enabled for the specified site.

To get a specific version of the workbook from revision history, use the Download Workbook Revision method. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook to get revisions for.
workbook-id	The ID of the workbook to get revisions for.
page-size	(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number	(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get workbook revisions if they have all of the following:

A site role of ExplorerCanPublish.
Read (view), Write (save), and Download (save as) permissions for the specified workbook.
Save (write) permissions for the project that contains the workbook.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
       totalAvailable="total-available" />
  <revisions>
    <revision createdAt="date" revisionNumber="1" isDeleted="false">
      <user id="user-id" name="user-name"/>
    </revision>
    <revision createdAt="date" revisionNumber="2" isDeleted="false">
    </revision>
    <revision createdAt="date" revisionNumber="3" isCurrent="true">
        <user id="user-id" name="user-name"/>
    </revision>
  </revisions>
</tsResponse>

If the revision element includes the attribute isDeleted="true", the workbook has been deleted and cannot be downloaded using the Download Workbook Revision method.

If a user has been deleted from the site, no <user> element is included in the <revision> element.

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
403	403053	Version history not enabled	version history is not enabled for the specified site.
403	403056	A non-administrator user attempted to get workbook revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Hide a Recommendation for a View

Hides a view from being recommended by the server by adding it to a list of views that are dismissed for a user. If hidden, a view will not be displayed on the server Home or Recommendation pages.

URI

PUT /api/api-version/sites/site-id/recommendations/dismissals

Path Parameter Values

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

Request Body

<tsRequest>
	<recommendationDismissal>
		<view id="view_luid" />
	</recommendationDismissal>
</tsRequest>

Request Parameters

view-luid

The LUID of the view to be added to the list of views hidden from recommendation for a user.

Permissions

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

Response Code

200

Response Body

None

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The content ID in the URI doesn't correspond to an existing content of the requested type.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dismissals -X PUT \
-H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" \
-d "@hide-view.xml"

Content of hide-view.xml

<tsRequest>
  <recommendationDismissal>
    <view id="57dc5674-23aa-4a83-b3d4-8653cf3c735f" />
  </recommendationDismissal>
</tsRequest>

Example response:

No response body. Response code is 204.

List Custom Views

Gets a list of custom views on a site. The list includes details of each custom view.

Version: Available in API 3.18 (Tableau Cloud December 2022 and Tableau Server 2023.1) and later. Version Overview

License: No additional license required.

Permissions: Tableau administrators can get the list of the custom views on a site, including details of each custom view. For details of non-administrator users' permissions, see Permissions Details . Permissions Overview

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

URI

GET /api/api-version/sites/site-luid/customviews

GET /api/api-version/sites/site-luid/customviews?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/customviews?sort=sort-expression

GET /api/api-version/sites/site-id/customviews?fields=field-expression

GET /api/api-version/sites/site-id/customviews?fields=filter-expression

URI Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-luid	The LUID for the site.
page-size	(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number	(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression	(Optional) An expression that lets you specify the set of available fields to return. When a request has a valid field expression, describing the attributes of a Tableau resource like a workbook or data source, only the attributes specified in the expression will be present in the response. For example, a field expression that results in a response containing only the resources LUIDs of the resources being requested would look like: `?field=id` You can qualify the expression to return values based upon predefined keywords such as `_default_`, which returns only default values, and `_all_`, which returns default and non-default values. You can include multiple field expressions in a request, and mix field, sort, and filter expressions in the same request. The supported fields for custom views are its attributes: `id`, `name`, `createdAt`, `updatedAt`, and `shared`. For more information, see Using Fields in the REST API.
filter-expression	(Optional) An expression that lets you filter which Tableau resources are present in the response. A filter expression has a resource, an operator, and a value. For example, a filter that returns only resources created after a specified date would look like: `?filter=createdAt:gt:2016-08-26T18:00:33Z` (where `gt` is the greater-than operator) You can include multiple filter expressions in a request, and mix field, sort, and filter expressions in the same request. The supported filters for custom views use the `eq` (equals) operator, with the resources: `viewId`, `ownerId`, and `workbookId`. For more information, see Filtering and Sorting in the Tableau REST API.
sort-expression	(Optional) An expression that lets you sort the Tableau resources present in the response. A sort expression contains an attribute name and a direction (`asc` or `desc`). For example, a sort expression that sorts the requested resource by creation date with the latest date first would look like: `?sort=createdAt:desc` You can include multiple sort expressions in a request, and mix field, sort, and filter expressions in the same request. The supported filters for custom views use the `eq` (equals) operator, with the resources: `viewId`, `ownerId`, and `workbookId`. For more information, see Filtering and Sorting in the Tableau REST API.

Request Body

None.

Required scope for JWT authorization

Introduced in Tableau Server 2022.3 (API 3.17).

tableau:content:read

cURL Request Example

curl -L -X GET "https://qa-near/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews" -H "X-Tableau-Auth: njR9EGn0QSCpbDrUOh0IKg"wamRRyVFFUHTVwFL6OWEyOggxCwWYXuq"a946d998-2ead-4894-bb50-1054a91dcab3"

Response Code

200

Response Body

<tsResponse >
  <pagination pageNumber="1" pageSize="100" totalAvailable="1673"/>
  <customViews>
	<customView
	  id="37d015c6-bc28-4c88-989c-72c0a171f7aa"
	  name="New name 2"
	  createdAt="2016-02-03T23:35:09Z"
	  updatedAt="2022-09-28T23:56:01Z"
	  lastAccessedAt="2022-09-28T23:58:25Z"
	  shared="false">
	    <view id="8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f" name="circle"/>
	    <workbook id="2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5" name="marks and viz types 2"/>
	    <owner id="cdfe8548-84c8-418e-9b33-2c0728b2398a" name="workgroupuser"/>
	</customView>
	<!--    more custom views   -->
  </customViews>
</tsResponse>

{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "1673"
  },
  "customViews": {
	"customView": {
	  "id": "37d015c6-bc28-4c88-989c-72c0a171f7aa",
	  "name": "New name 2",
	  "createdAt": "2016-02-03T23:35:09Z",
	  "updatedAt": "2022-09-28T23:56:01Z",
	  "lastAccessedAt": "2022-09-28T23:58:25Z",
	  "shared": "false",
	  "view": {
	    "id": "8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f",
	    "name": "circle"
	  },
	  "workbook": {
	    "id": "2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5",
	    "name": "marks and viz types 2"
	  },
	  "owner": {
	    "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
	    "name": "workgroupuser"
	  }
	}
	// more customViews
  }
}

Permissions Details

For users who do not have administrator permissions:
The custom views present in the response to a request, and the details of those views that are displayed, depend on four things:

Does the user have both Write and WebAuthoring permissions for the custom view?
Is the user is the owner of the custom view
Is there filter applied in the request parameters.
Is site user visibility(Link opens in a new window) set to Limited?

The expected behavior in a response is as follows:

If the request has no filter parameters: Users will see only custom views that they own.
If the filter parameters include ownerId: Users will see only custom views that they own.
If the filter parameters include viewId and/or workbookId, and don't include ownerId:
- Users will see those custom views that they have Write and WebAuthoring permissions for.
- If site user visibility in not set to Limited, the Users will see those custom views that are "public", meaning the value of their shared attribute is true.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

List Users with Custom View as Default

Gets the list of users whose default view is the specified custom view.

Version: Available in API 3.21 (Tableau Cloud October 2023 / Server 2023.3) and later. Version Overview

License: No additional license required.

Permissions: Only Tableau administrators can list users whose default view is the specified custom view. Permissions Overview

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

URI

GET /api/api-version/sites/site-luid/customviews/custom-view-luid/default/users

URI Parameter Values

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

Request Body

None.

cURL Request Example

curl --location 'https://qa-near.tsi.lan/api/3.21/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/3321cb71-6606-4d78-8a0c-e69a7e7d2261/default/users' --header 'Accept: application/xml' --header 'X-Tableau-Auth: LfzV48kKRUOYMYbzamWRpA|bfkD8ruGmN8ZNGmdL03PHB0gMHGtCfOk|a946d998-2ead-4894-bb50-1054a91dcab3'

Response Code

200

Response Body

Copy

<tsResponse >
  <pagination pageNumber="1" 
    pageSize="100" 
    totalAvailable="1"/>
      <users>
        <user id="5c9a81df-7ec0-4752-a057-82cd2bb22c44"/>
      </users>
</tsResponse>

Copy

{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "1"
  },
  "users": {
    "user": [
      {
        "id": "5c9a81df-7ec0-4752-a057-82cd2bb22c44"
      }
    ]
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions.
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Publish Workbook

Publishes a workbook on the specified site. To make changes to a published workbook, call Update Workbook or Update Workbook Connection.

Version: Available in API 2.0 and later.

License: No additional license required.

Permissions: Users who are not server administrators or site administrators can publish a workbook only if the workbook belongs to a project that they have permissions to publish to.

Access Scope: tableau:workbooks:create

Access scope introduced in API 3.16 (Tableau Cloud June 2022 / Tableau Server 2022.3)

This method is used in two ways. You can call it to publish a workbook in a single request. To do that, you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make workbook publication asynchronous.

Alternatively, you can publish a workbook in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Workbook. In this case, Publish Workbook doesn't contain the file to publish.

Hiding views in a published workbook
To exclude certain sheets (also known as views) when you publish a workbook, configure them in the request as hidden. You cannot publish a workbook if all sheets are hidden.

Extracts with multiple table options
If an extract was stored using the multiple tables option, you can't append data to it.

Workbooks that rely on external local resources
When you publish a workbook from your local computer to the server, the publish process will fail if the workbook relies on resources (such as an Excel file or other data file) that are on your local computer but are not available on the server. (Unlike the publish process that is used in Tableau Desktop, the REST API publish process cannot automatically include extracts or other resources that the workbook uses.) If you are publishing a workbook that gets its data from a source on your computer, save the workbook as a packaged workbook (.twbx file) and publish the package so that workbook has all the resources it needs on the server.

For more information, see Publishing Resources.

URI

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

POST /api/api-version/sites/site-id/workbooks?overwrite=overwrite-flag

POST /api/api-version/sites/site-id/workbooks?skipConnectionCheck=skip-connection-check-flag

POST /api/api-version/sites/site-id/workbooks?uploadSessionId=upload-session-id&workbookType=workbook-file-type&overwrite=bool&asJob=asJob-value

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site to publish to.
overwrite-flag	(Optional) true to overwrite a workbook that has the same name, or false to fail if the specified workbook already exists. The default is false. If overwrite-flag is set to true but the workbook doesn't already exist, the operation succeeds.
asJob-value	(Optional, boolean) If `false`, the workbook publishing process runs as a synchronous process. If a workbook is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job. Default value is `false`.
skip-connection-check-flag	(Optional, boolean) If `true`, then the Tableau server will not check if a non-published connection of a workbook is reachable. Publishing will succeed but unchecked connection issues may result in a non-functioning workbook. If you encounter this issue, follow Keep Data Fresh guidelines(Link opens in a new window). Default value is `false`.
upload-session-id	If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
workbook-file-type	twb or twbx to indicate whether you have uploaded a workbook file (twb) or a packaged workbook file (twbx). This value is required if you are calling Publish Workbook in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request.

Request Body

The content type in the header of requests to publish a workbook must use the mixed multi-part content type with a boundary string definition, in the form of: Content-Type: multipart/mixed; boundary=boundary-string.

Publishing a file in the request body

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" description="workbook-description" thumbnailsUserId="user-luid">
    <connections>
    <connection serverAddress="server-address" serverPort="port-number">
    <connectionCredentials name="connection-username" password="connection-password"
          embed="embed-flag" />
    </connection>
    </connections>
    <project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_workbook"; filename="workbook-file-name"
Content-Type: application/octet-stream
content-of-workbook-file
--boundary-string--

Committing a file previously uploaded

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" description="workbook-description" thumbnailsUserId="user-luid" >
    <connections>
    <connection serverAddress="server-address" serverPort="port-number">
    <connectionCredentials name="connection-username" password="connection-password"
          embed="embed-flag" oAuth="oauth-flag" />
    </connection>
    </connections>
    <project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string--

Hiding a view when publishing a workbook

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" description="workbook-description" thumbnailsUserId="user-luid" >
    <connections>
      <connection serverAddress="server-address" serverPort="port-number">
        <connectionCredentials name="connection-username" password="connection-password"
           embed="embed-flag" oAuth="oauth-flag" />
	  </connection>
	</connections>
	<views>
      <view name="view-name" hidden="hide-view-flag" />
	</views>
	<project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string--

Attribute Values

boundary-string	A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value must be declared as a header that has this format: `Content-type: multipart/mixed; boundary=boundary-string`
workbook-name	The name to assign to the workbook when it is saved on the server.
workbook-description	(Optional) Starting in API 3.20, the description for the workbook.
show-tabs-flag	(Optional) Specify true to have the published workbook show views in tabs; otherwise, false. The default is false.
user-luid	(Optional) The LUID of the user to generate thumbnails as. You can get the user LUID by calling Get Users on Site.
server-address	(Optional) Specify the server address for a data source connection if that data source does not use OAuth.
port-number	(Optional) Specify the port number for a data source connection if that data source does not use OAuth.
connection-username	(Optional) If the workbook's data source connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection username. If the element is included but is not required (for example, if the data source uses OAuth), the server ignores the element and its attributes. Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to a data source that requires credentials, unless that data source uses OAuth.
connection-password	(Optional) If the workbook's data source connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection password. If the element is included but is not required (for example, if the data source uses OAuth), the server ignores the element and its attributes. Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to a data source that requires credentials, unless that data source uses OAuth.
embed-flag	(Optional) If the workbook's data source connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to true instructs the server to save the credentials for when the data source is used.
oauth-flag	(Optional) If the workbook's data source connection is configured to use OAuth, set this to `true` to specify that the value of the name attribute in the <connectionCredentials> element is an OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the workbook, and the server address and port number are not required. For more information, see OAuth Connections(Link opens in a new window) in the Tableau Server documentation.
hide-view-flag	Setting this flag to `true` will cause the named view to be hidden in the published workbook. The default value is `false`. You can specify any number of views to hide. If all views in a workbook are hidden the server will not perform a publish.
project-id	The ID of the project to assign the workbook to. If the project is not specified, the workbook will be published to the default project.
workbook-file-name	The file name (including extension) of the workbook file to upload. This attribute is used in the request body only if the request also includes the content of the workbook file; it is not used if you are committing a file uploaded using previous requests.
content-of-workbook-file	The content of the workbook file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.
encryptExtracts	(Optional) true to encrypt the extracts or false to not encrypt extracts. For more information, see Extract and Encryption Methods.

Response Code

201

Response Body

<tsResponse>
  <workbook
    id="workbook-id"
	  name="workbook-name"
	  contentUrl="site-content-url"
	  webpageUrl="server-address"
	  showTabs="show-tabs-flag"
	  size="num-size"
	  createdAt="workbook-publish-date-time"
	  updatedAt="workbook-update-date-time"
	  encryptExtracts="encryptExtracts" >
 	    <project id="project-id" name="project-name"/>
	    <owner id="workbook-owner-id"/>
	    <tags/>
	    <views>
	      <view
	        id="view-id"
	     	name="view-name"
	        contentUrl="view-content-url"
	        createdAt="view-publish-date-time"
	        updatedAt="view-update-date-time" >
	          <tags/>
	 	  </view>
	  <materializedViewsEnablementConfig materializedViewsEnabled="materialized-views-enabled-flag"/>
  </workbook>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

cURL Request Example

curl "http://MY_SERVER/api/3.4/sites/ff2a8360-3c2b-4b05-a793-7607c602e1fb/workbooks" -X POST -H "X-Tableau-Auth:7T_33sOfS8Ks_0cht4tYxw|8tsTYQyyOZXfOgxZEHWQ4jUTCQ08GhRr" -H "Content-Type: multipart/mixed;" -F "request_payload=@publish-workbook.xml" -F "tableau_workbook=@MY_WORKBOOK.twbx"

Content of publish-workbook.xml (publish the Test1 workbook, hide the Test Sheet 1 view):

<tsRequest>
	<workbook name="test1" showTabs="true" >
	<project id=""/>
	<views>
	<view name="Test Sheet 1" hidden="true" />
	</views>
	</workbook>
</tsRequest>

Example response:

<tsResponse>
	<workbook
		id="1e40f015-ac41-4377-8238-544f70d36150"
		name="test1" contentUrl="test1"
		webpageUrl="http://MY_SERVER/#/workbooks/3"
		showTabs="true"
		size="1"
		createdAt="2019-04-03T21:24:58Z"
		updatedAt="2019-04-03T21:25:02Z"
		encryptExtracts="false">
		  <project id="e6e94e18-349f-11e9-a794-13e5e0f21c22" name="Default"/>
		  <owner id="1473347e-b0c6-4f1f-bcac-7927ee1a690e"/>
	 	  <tags/>
		  <views>
			<view
			  id="0f0d33ac-027d-42a7-94bf-4f0b13e07652"
			  name="Sheet 1"
			  contentUrl="test1/sheets/Sheet1"
			  createdAt="2019-04-03T21:25:02Z"
		      updatedAt="2019-04-03T21:25:02Z">
			  <tags/>
			</view>
		 <materializedViewsEnablementConfig materializedViewsEnabled="false"/>
	</workbook>
</tsResponse>

Response Headers

Location: /api/3.26/sites/site-id/workbooks/workbook-id

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Malformed request body	The XML content in the MIME multipart request is not empty.
400	400000	Missing workbook	There is no attachment in the request and no uploadSessionID parameter.
400	400000	Unexpected attachments	The message had both an uploadSessionId parameter and an attachment, or the request body contained more than one attachment.
400	400008	Invalid embed value	The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false.
400	400008	Invalid overwrite value	The overwrite parameter must be true or false.
400	400011	Publishing error	The workbook could not be published for some other reason than those specified earlier.
400	400020	Invalid workbook file name	The name of the workbook doesn't end in `.twb` or `.twbx`.
400	400035	Missing or invalid file type	The request included an uploadSessionId parameter but no file type, or the file type was something other than `.twb` or `.twbx`.
403	403007	Insufficient publishing permission	A non-administrator user attempted to publish a workbook, but the caller doesn't have sufficient project permissions.
403	403007	Unlicensed publishing forbidden	A non-administrator user attempted to publish a workbook. This is disallowed for all projects (including the default project).
403	403007	Overwrite forbidden	A workbook with the specified name already exists and the overwrite parameter was not set to true.
403	403007	Problem connecting to data source	There was a problem connecting to a data source used by the workbook. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server.
403	403008	Insufficient storage quota	The workbook could not be published because there is not enough storage remaining on the server to accommodate its size.
403	403130	Publishing overwrite	A workbook with the same name already exists.
403	403131	Concurrent update	The workbook is already being published in another process.
403	403132	Failed connection check	One or more data sources used by the workbook could not be reached.
404	404005	Project not found	The project ID in the request body doesn't correspond to an existing project on the site.
404	404006	Workbook not found	The user specified overwrite as true but no workbook with the specified name exists on the site.
404	404015	File upload not found	The file upload session ID in the uploadSessionId parameter doesn't correspond to an existing file upload on the site.
405	405000	Invalid request method	Request type was not POST.

For more information, see Handling Errors.

Query Views for Site

Returns all the views for the specified site, optionally including usage statistics.

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

Version: Available in API 2.2 and later.

License: No additional license required.

Permissions: For users who are not server administrators or site administrators, the method returns only the views that the user owns or has Read permissions for (either explicitly or implicitly).

Access Scope: tableau:content:read

URI

GET /api/api-version/sites/site-id/views

GET /api/api-version/sites/site-id/views?includeUsageStatistics=get-usage-information

GET /api/api-version/sites/site-id/views?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/views?includeUsageStatistics=get-usage-information&pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/views?filter=filter-expression

GET /api/api-version/sites/site-id/views?sort=sort-expression

GET /api/api-version/sites/site-id/views?fields=field-expression

Parameter Values

api-version	The version of the API to use, such as `2.2`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the views.
get-usage-information	(Optional) true to return usage statistics. The default is false.
page-size	(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number	(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression	(Optional) Fields and operators that you can use to filter results. For more information, see Filter expressions.
sort-expression	(Optional) Field and direction to sort results. For more information, see Sorting.
field-expression	(Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as `_all_` or `_default_`, and you can specify individual fields for the workbooks or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

cURL Request

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

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2" />
  <views>
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" name="Economic Indicators"
         contentUrl="Finance/sheets/EconomicIndicators">
      <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" />
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
    </view>
    <view id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="Investing in the Dow"
          contentUrl="Finance/sheets/InvestingintheDow">
      <workbook id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" />
      <owner id="9f8e7d6c5-b4a3-f2e1-d0c9-b8a7f6e5d4c" />
    </view>
  </views>
</tsResponse>

{
  "pagination": {
    "pageNumber": "1",
    "pageSize": "100",
    "totalAvailable": "2"
  },
  "views": [
    {
      "id": "1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c",
      "name": "Economic Indicators",
      "contentUrl": "Finance/sheets/EconomicIndicators",
      "workbook": {
        "id": "1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
      },
      "owner": {
        "id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"
      }
    },
    {
      "id": "9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b",
      "name": "Investing in the Dow",
      "contentUrl": "Finance/sheets/InvestingintheDow",
      "workbook": {
        "id": "59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba"
      },
      "owner": {
        "id": "9f8e7d6c5-b4a3-f2e1-d0c9-b8a7f6e5d4c"
      }
    }
  ]
}

The <usage> element is included in the response only if the method has includeUsageStatistics=true in the URI.

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
400	400008	Invalid parameter value	The includeUsageStatistics was provided with a value other than true or false.
403	403004	Read forbidden	A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Query Views for Workbook

Returns all the views for the specified workbook, optionally including usage statistics.

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

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/views

GET /api/api-version/sites/site-id/workbooks/workbook-id/views?includeUsageStatistics=get-usage-information

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to get the views for.
(Optional) get-usage-information	true to return usage statistics. The default is false.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <views>
    <view id="view-id" name="view-name"
        contentUrl="content-url" >
      <usage totalViewCount="total-count" />
    </view>
     ... additional views ...
  </views>
</tsResponse>

The <usage> element is included in the response only if the method has includeUsageStatistics=true in the URI.

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400008	Invalid parameter value	The includeUsageStatistics was provided with a value other than true or false.
403	403004	Read forbidden	A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

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

Example response:

<tsResponse version-and-namespace-settings>
  <views>
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" name="Tale of 100 Start-ups"
          contentUrl="Finance/sheets/Taleof100Start-ups"/>
    <view id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" name="Economic Indicators"
          contentUrl="Finance/sheets/EconomicIndicators"/>
    <view id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" name="Investing in the Dow"
          contentUrl="Finance/sheets/InvestingintheDow"/>
  </views>
</tsResponse>

Query View Data

Returns a specified view rendered as data in comma separated value (CSV) format.

Version: Available in API 2.8 and later.

License: No additional license required.

Permissions:Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Access Scope: tableau:views:download

CSV data is provided in the response body, rather than as a download. If the request is for a dashboard, only data for the dashboard's first view is returned.

If you make multiple requests for a view's data, subsequent calls return a cached version of the data. This means that the returned data might not include the latest changes to the view. To decrease the amount of time that an data is cached, use the maxAge parameter. Default age of data is 60 minutes.

Note the data exported is at a summary level only. Detail level data is only available as a download option in the user interface.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

URI

GET /api/api-version/sites/site-id/views/view-id/data

GET /api/api-version/sites/site-id/views/view-id/data?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/views/view-id/data?vf_<fieldname>=filter-value

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the view.
view-id	The ID of the view to render as data.
max-age-minutes	(Optional) The maximum number of minutes view data will be cached before being refreshed. To prevent multiple view data requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
filter-value	The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter `/data?vf_year=2017` would only display data from the year 2017. To learn more, see View filter queries.

Request Body

None

cURL Request

curl "http://MY-SERVER/api/3.26/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/views/2474164d-8d37-4a4c-abc7-c2070fd25fd5/data?maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

The response body contains view data in CSV format no more than 60 minutes old.

Month of Date,Year of Date,Above Median?,Avg. Median
January,1893,below median,-1.0
January,1864,below median,-0.9
January,1861,below median,-0.9
December,1862,below median,-0.9
March,1917,below median,-0.8
December,1892,below median,-0.8
February,1862,below median,-0.8
February,1911,below median,-0.8
February,1917,below median,-0.8
May,1861,below median,-0.8
November,1862,below median,-0.8
March,1898,below median,-0.8
December,1860,below median,-0.8
January,1862,below median,-0.7
March,1850,below median,-0.7
February,1893,below median,-0.7
December,1870,below median,-0.7

Errors

HTTP status	`error` Code	Condition	Details
400	400080	Bad Request	The view ID in the URI doesn't correspond to a view available on the specified site.
401	401002	Unauthorized	The authentication token provided in the request header was invalid or has expired.
403	403032	Read forbidden	A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.
429	429000	Concurrent request limit exceeded	For Tableau Cloud, the cumulative number of concurrent requests has exceeded the limit of 20. This limit applies to long-running jobs such as exports and downloads for view data, images, .pdf or .pptx files, datasources, and crosstabs, Retry this request at a later time. Introduced September 2021.

For more information, see Handling Errors.

Query View Image

Returns an image of the specified view.

Version: Available in API 2.5 and later.

License: No additional license required.

Permissions: Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Access Scope: tableau:views:download

Access scope introduced in API 3.16 (Tableau Cloud June 2022 / Tableau Server 2022.3)

If you make multiple requests for an image, subsequent calls return a cached version of the image. This means that the returned image might not include the latest changes to the view. To decrease the amount of time that an image is cached, use the maxAge parameter.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

Note: If you want to disable this endpoint, use TSM to set the sheet_image.enabled setting to false. For more information, see tsm configuration set options in the Tableau Server help.

URI

GET /api/api-version/sites/site-id/views/view-id/image

GET /api/api-version/sites/site-id/views/view-id/image?resolution=image-resolution

GET /api/api-version/sites/site-id/views/view-id/image?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/views/view-id/image?vf_<fieldname>=filter-value

Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later:

GET /api/api-version/sites/site-id/views/view-id/image?resolution=image-resolution

GET /api/api-version/sites/site-id/views/view-id/image?vizHeight=viz-height&vizWidth=viz-width

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the view.
view-id	The ID of the view to return an image for.
viz-height	Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later: (Optional) The height of the rendered pdf image in pixels that, along with the value of `vizWidth` determine its resolution and aspect ratio.
viz-width	Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later: (Optional) The width of the rendered pdf image in pixels that, along with the value of `vizHeight` determine its resolution and aspect ratio.
image-resolution	(Optional) The resolution of the image. Image width and actual pixel density are determined by the display context of the image. Aspect ratio is always preserved. Set the value to `high` to ensure maximum pixel density.
max-age-minutes	(Optional) The maximum number of minutes a view image will be cached before being refreshed. To prevent multiple image requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
filter-value	The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter `/data?vf_year=2017` would only display data from the year 2017. To learn more, see View filter queries.

Request Body

None

Response Code

200

Response Body

The view's image in PNG format (MIME media type image/png).

cURL Request Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/image?resolution=high&maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Read forbidden	A non-administrator user attempted to query a view preview image, but the caller doesn't have Read permission.
403	403068	Forbidden	The endpoint has been disabled on the server. To enable the endpoint, a server administrator must use tsm to configure the `sheet_image.enabled` setting. For more information, see tsm configuration set Options in the Tableau Server help.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
404	404011	View not found	The view ID in the URI doesn't correspond to an existing view in the specified workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Query View PDF

Returns a specified view rendered as a .pdf file.

Version: Available in API 2.8 and later.

License: No additional license required.

Permissions: Tableau Server users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Access Scope: tableau:views:download

Access scope introduced in API 3.16 (Tableau Cloud June 2022 / Tableau Server 2022.3)

If you make multiple requests for a PDF, subsequent calls return a cached version of the file. This means that the returned PDF might not include the latest changes to the view. To decrease the amount of time that an PDF is cached, use the maxAge parameter.

This method includes the ability to filter a view using fields in the underlying workbook data. To learn more about filtering query views, see Filtering and Sorting in the REST API.

URI

GET /api/api-version/sites/site-id/views/view-id/pdf

GET /api/api-version/sites/site-id/views/view-id/pdf?vizHeight=viz-height&vizWidth=viz-width

GET /api/api-version/sites/site-id/views/view-id/pdf?maxAge=max-age-minutes

GET /api/api-version/sites/site-id/views/view-id/pdf?type=page-type&orientation=orientation

GET /api/api-version/sites/site-id/views/view-id/pdf?vf_<fieldname>=filter-value

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the view.
view-id	The ID of the view to render as a .pdf file.
filter-value	The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter `/data?vf_year=2017` would only display data from the year 2017. To learn more, see View filter queries.
viz-height	(Optional) The height of the rendered pdf image in pixels that, along with the value of `vizWidth`, determines its resolution and aspect ratio.
viz-width	(Optional) The width of the rendered pdf image in pixels that, along with the value of `vizHeight`, determines its resolution and aspect ratio.
max-age-minutes	(Optional) The maximum number of minutes a view PDF will be cached before being refreshed. To prevent multiple PDF requests from overloading the server, the shortest interval you can set is one minute. There is no maximum value, but the server job enacting the caching action may expire before a long cache period is reached.
orientation	(Optional) The orientation of the pages in the .pdf file produced. The value can be `Portrait` or `Landscape`. If this parameter is not present the page orientation will default to `Portrait`.
page-type	(Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be: `A3`, `A4`, `A5`, `B5`, `Executive`, `Folio`, `Ledger`, `Legal`, `Letter`, `Note`, `Quarto`, or `Tabloid`. If this parameter is not present the page type will default to `Legal`.

Request Body

None

Response Code

200

Response Body

This method has no response body. The response is in the form of a downloaded .pdf file. The response header content will have Content-Type:application/pdf.

cURL Example

curl "http://MY-SERVER/api/3.26/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/views/2474164d-8d37-4a4c-abc7-c2070fd25fd5/pdf/maxAge=60" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response is a file that contains the view, whose data is no older than 60 minutes, saved as a pdf.

Errors

HTTP status	`error` Code	Condition	Details
400	400080	Bad Request	The view ID in the URI doesn't correspond to a view available on the specified site.
401	401002	Unauthorized	The authentication token provided in the request header was invalid or has expired.
403	403032	Read forbidden	A non-administrator user attempted to query workbook views, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Query View Preview Image

Returns the thumbnail image for the specified view.

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

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/views/view-id/previewImage

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the view.
workbook-id	The ID of the workbook that contains the view to return a thumbnail image for.
view-id	The ID of the view to return a thumbnail image for.

Request Body

None

Permissions

Users who are not server administrators or site administrators can query workbook views only if they have Read (view) permission for the views (either explicitly or implicitly).

Required scope for JWT authorization

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

tableau:views:download

Response Code

200

Response Body

The view's preview image in PNG format (MIME media type image/png).

Version

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

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Read forbidden	A non-administrator user attempted to query a view preview image, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
404	404011	View not found	The view ID in the URI doesn't correspond to an existing view in the specified workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Get Workbook

Returns information about the specified workbook, including information about views and tags.

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

Version: Available in API 2.0 and later. Data acceleration and data freshness policy setting update are added in API 3.22 (Tableau Cloud February 2024 / Server 2024.2). Version Overview

License: No additional license required.

Permissions: You can get workbok details if you are a user with implicit or explicit Read permissions for the workbook, or are a Tableau Administrator. Permissions Overview

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

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id

GET /api/api-version/sites/site-id/workbooks/content-url?key=contentUrl

URI Parameter Values

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

site-id The ID of the site that contains the workbook.

content-url

The permanent name of the site to sign in to. The content URL appears in the URL path of Tableau content in your browser address bar after the Tableau Server URL.

mySite is the content URL in the following example:

http://<server or cloud URL>/#/site/mySite/explore

Request Body

None

Response Code

200

cURL Request Example

curl -L -X GET "http://qa-near/api/3.17/sites/a946d998-2ead-4894-bb50-1054a91dcab3/workbooks/simple-highlight?key=contentUrl" -H "X-Tableau-Auth:HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3"

Response Body

Copy

<tsResponse>
  <workbook id="0828bd63-dea5-454f-8f54-30f9a92760ff" 
    name="WB_Election_live" 
    description="" contentUrl="WB_Election_live" 
    webpageUrl="http://MyServer/#/workbooks/4" 
    showTabs="false" size="1" createdAt="2024-01-25T23:42:57Z" 
    updatedAt="2024-01-25T23:42:57Z" 
    encryptExtracts="false" 
    defaultViewId="10f6d099-fe90-41a1-a77b-1512b818d23c">
      <project id="7eb51f54-bbca-11ee-9262-638afb01250c" name="Default"/>
      <location id="7eb51f54-bbca-11ee-9262-638afb01250c" type="Project" name="Default"/>
      <owner id="09d032b6-d17d-444c-afbe-d71c22f7ee31" name="test"/>
      <tags/>
      <views>
        <view id="fcc36499-fd2d-42af-8e2c-29d1c7893edd" 
            name="Votes" 
            contentUrl="WB_Election_live/sheets/Votes" 
            createdAt="2024-01-25T23:42:57Z" 
            updatedAt="2024-01-25T23:42:57Z" 
            viewUrlName="Votes">
            <tags/>
            <dataAccelerationConfig accelerationEnabled="true" 
                accelerationStatus="Pending"/>
          </view>
        </views>
        <dataFreshnessPolicy option="FreshAt">
            <freshAtSchedule time="08:15:00" frequency="Week" timezone="America/Los_Angeles">
                <intervals>
                    <interval weekDay="MONDAY"/>
                </intervals>
            </freshAtSchedule>
        </dataFreshnessPolicy>
  </workbook>
</tsResponse>

Copy

{
  "workbook": {
    "id": "0828bd63-dea5-454f-8f54-30f9a92760ff",
    "name": "WB_Election_live",
    "description": "",
    "contentUrl": "WB_Election_live",
    "webpageUrl": "http://MyServer/#/workbooks/4",
    "showTabs": "false",
    "size": "1",
    "createdAt": "2024-01-25T23:42:57Z",
    "updatedAt": "2024-01-25T23:42:57Z",
    "encryptExtracts": "false",
    "defaultViewId": "10f6d099-fe90-41a1-a77b-1512b818d23c",
    "project": {
      "id": "7eb51f54-bbca-11ee-9262-638afb01250c",
      "name": "Default"
    },
    "location": {
      "id": "7eb51f54-bbca-11ee-9262-638afb01250c",
      "type": "Project",
      "name": "Default"
    },
    "owner": {
      "id": "09d032b6-d17d-444c-afbe-d71c22f7ee31",
      "name": "test"
    },
    "tags": [],
    "views": {
      "view": {
        "id": "fcc36499-fd2d-42af-8e2c-29d1c7893edd",
        "name": "Votes",
        "contentUrl": "WB_Election_live/sheets/Votes",
        "createdAt": "2024-01-25T23:42:57Z",
        "updatedAt": "2024-01-25T23:42:57Z",
        "viewUrlName": "Votes",
        "tags": [],
        "dataAccelerationConfig": {
          "accelerationEnabled": "true",
          "accelerationStatus": "Pending"
        }
      }
    },
    "dataFreshnessPolicy": {
      "option": "FreshAt",
      "freshAtSchedule": {
        "time": "08:15:00",
        "frequency": "Week",
        "timezone": "America/Los_Angeles",
        "intervals": {
          "interval": {
            "weekDay": "MONDAY"
          }
        }
      }
    }
  }
}

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Errors

HTTP status	`error` Code	Condition	Details
403	403018	Read forbidden	A non-administrator user attempted to query the workbook, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook LUID or contentUrl in the URI doesn't correspond to an existing workbook, or the querystring `?key=contentUrl` is not capitalized correctly.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Query Workbooks for Site

Returns the workbooks on a site.

If the user is not an administrator, the method returns just the workbooks that the user has permissions to view.

URI

GET /api/api-version/sites/site-id/workbooks

GET /api/api-version/sites/site-id/workbooks?filter=filter-expression

GET /api/api-version/sites/site-id/workbooks?sort=sort-expression

GET /api/api-version/sites/site-id/workbooks?pageSize=page-size&pageNumber=page-number

GET /api/api-version/sites/site-id/workbooks?fields=field-expression

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbooks.
filter-expression	(Optional) An expression that lets you specify a subset of workbooks to return. You can filter on predefined fields such as `name`, `tags`, and `createdAt`. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression	(Optional) An expression that lets you specify the order in which workbook information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
page-size	(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number	(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
field-expression	(Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as `_all_` or `_default_`, and you can specify individual fields for the workbooks or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

Users who are not server administrators or site administrators can get workbooks that they have Read (view) permissions for (either explicitly or implicitly).

Required scope for JWT authorization

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

tableau:content:read

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="page-number"
     pageSize="page-size"
     totalAvailable="total-available" />
  <workbooks>
    <workbook id="workbook-id"
		name="name"
		description ="workbook-description"
		webpageurl="workbook-webpageurl"
		contentUrl="content-url"
        showTabs="show-tabs-flag"
        size="size-in-megabytes"
        createdAt="datetime-created"
	    updatedAt="datetime-updated"
	    defaultViewId="default-view-id" >
	      <project id="project-id" name="project-name" />
	      <owner id="user-id" />
	      <tags>
	        <tag label="tag"/>
	        ... additional tags ...
	     </tags>
	<dataAccelerationConfig accelerationEnabled="accelerationEnabled" lastUpdatedAt="update-date-time" accelerationStatus="accelerationStatus" />
   </workbook>
   ... additional workbooks ...
  </workbooks>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Attribute Values

accelerationEnabled

true if data acceleration is enabled, otherwise false. For more information, see Data Acceleration. (Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)

accelerationStatus

The status can be:

accelerated: The acceleration job succeeded.
failed: The acceleration job failed.
inProgress: The acceleration job is running.
notUseful: The acceleration job completed but none of the queries in the workbook were supported for acceleration.
waiting: The workbook is enabled for acceleration but no background job has been submitted yet to accelerate it.

(Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
403	403014	Page size exceeds upper limit	The page size parameter exceeds the system-wide upper limit of 1000.
403	403018	Read forbidden	A non-administrator user attempted to query workbooks for the site, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example: Get workbooks without filter

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="27"/>
  <workbooks>
    <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
		name="Finance"
        description="The finance workbook."
		contentUrl="Finance" showTabs="true"
		webpageUrl="http://MY_SERVER/#/worbooks/1" size="2"
		createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
		defaultViewId="abcd1234-fa4a-4e3f-85fe-db746f44bf4c" >
	      <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
	      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	      <tags/>
    </workbook>
    <workbook id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="World Indicators"
		description="The world indicators workbook."
		contentUrl="WorldIndicators" showTabs="true"
		webpageUrl="http://MY_SERVER/#/worbooks/2" size="1"
        createdAt="2014-02-19T10:19:23Z" updatedAt="2015-12-29T013:23:45Z"
		defaultViewId="edd01d90-fa4a-4e3f-85fe-db746f44bf4c" >
	      <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="default"/>
	      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	      <tags>
          <tag label="training" ></tags>
    </workbook>
  </workbooks>
  ...more workbooks ...
  </tsResponse>

Example: Get workbooks with date/time filter

The following example includes a filter to return the workbooks that were updated on 1 May 2016 at 6:00 AM or later and specifies that the results should be sorted by the workbook name.

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks?filter=updatedAt:gte:2016-05-01T06:00:00Z&sort=name:asc" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Query Workbooks for User

Returns the workbooks that the specified user owns in addition to those that the user has Read (view) permissions for.

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

URI

GET /api/api-version/sites/site-id/users/user-id/workbooks

GET /api/api-version/sites/site-id/users/user-id/workbooks?ownedBy=isOwner&pageSize=page-size&pageNumber=page-number

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the user.
user-id	The ID of the user to get workbooks for.
isOwner	(Optional) true to return only workbooks that the specified user owns, or false to return all workbooks that the specified user has at least read access to. The default is false.
page-size	(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number	(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

All users can call this method, but the results of the call depend on the user's permissions. Server and site administrators see all workbooks for the specified user. If the isOwner parameter is true, users who are not server or site administrators see the workbooks that they own on the site. If isOwner parameter is false, users who are not server administrators see the workbooks that they have Read (view) permissions for.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
         totalAvailable="total-available" />
  <workbooks>
    <workbook id="workbook-id"
	  name="name"
	  description ="workbook-description"
	  webpageurl="workbook-webpageurl"
	  contentUrl="content-url"
      showTabs="show-tabs-flag"
      size="size-in-megabytes"
      createdAt="datetime-created"
      updatedAt="datetime-updated"
      defaultViewId="default-view-id" >
	    <project id="project-id" name="project-name" />
	    <owner id="user-id" />
	    <tags>
	      <tag label="tag"/>
	        ... additional tags ...
	      </tags>
   </workbook>
   ... additional workbooks ...
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
403	403014	Page size exceeds upper limit	The page size parameter exceeds the system-wide upper limit of 1000.
403	403018	Read forbidden	A non-administrator user attempted to query workbooks for the user, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404002	User not found	The user ID in the URI doesn't correspond to an existing user.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/workbooks" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="2"/>
  <workbooks>
    <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d" name="Finance"
	  webpageUrl="https://MY_SERVER/#/worbooks/1"
      contentUrl="Finance" showTabs="true" size="2" description="The Finance workbook."
      createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
      defaultViewId="edd01d90-fa4a-4e3f-85fe-db746f44bf4c" >
	    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
	    <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	    <tags></tags>
    </workbook>
    <workbook id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="World Indicators"
	  webpageUrl="https://MY_SERVER/#/worbooks/2"
	  contentUrl="WorldIndicators" showTabs="true" size="1"  description="The World Indicators workbook."
	  createdAt="2014-02-19T10:19:23Z" updatedAt="2015-12-29T013:23:45Z"
	  defaultViewId="edd01d90-fa4a-4e3f-85fe-db746f44bf4c" >
        <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="default"/>
        <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
        <tags></tags>
    </workbook>
  </workbooks>
</tsResponse>

Query Workbook Connections

Returns a list of data connections for the specific workbook.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/connections

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to return connection information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a workbook only if they have Read (view) permission for the workbook (either explicitly or implicitly). queryTaggingEnabled is returned only for administrator users.

Response Code

200

Response Body

<tsResponse>
  <connections>
    <connection id="connection-id" type="connection-type"
      serverAddress="server-address" serverPort="port"
      userName="connection-user-name"
      queryTaggingEnabled="query-tagging-enabled"
      authenticationType="authentication-type"
      useOAuthManagedKeychain="using-OAuth-managed-keychain-or-not />
    < ... additional connections ... >
  </connections>
</tsResponse>

Version

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

Errors

HTTP status	`error` Code	Condition	Details
403	403021	Read forbidden	A user who is not a server administrator user attempted to query the workbook connections, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

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

Example response:

<tsResponse version-and-namespace-settings>
  <connections>
    <connection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" type="dataengine" />
    <connection id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b" type="dataengine" />
    <connection id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" type="dataengine" />
    <connection id="374371c0-ffe9-4e16-b48e-6b868e3026ca" type="dataengine" />
    <connection id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" type="dataengine" />
  </connections>
</tsResponse>

Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.

Query Workbook Preview Image

Returns the thumbnail image as a PNG file for the specified workbook. Usually the image that is returned is for the first sheet in the workbook.

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

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/previewImage

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to return the thumbnail image for.

Request Body

None

Permissions

Users who are not server administrators or site administrators can query a workbook preview image only if they have Read (view) permission for the workbook (either explicitly or implicitly) and also have Read (view) permission for the view that is used as the preview image. If the user doesn't have Read permissions to that view, the preview image for another view might be used. If the user doesn't have Read permissions to any views in the workbook, the user is not allowed to query a workbook query image.

Required scope for JWT authorization

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

tableau:workbooks:download

Response Code

200

Response Body

The workbook's preview image in PNG format (MIME media type image/png).

Version

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

Errors

HTTP status	`error` Code	Condition	Details
403	403004	Read forbidden	A non-administrator user attempted to query the workbook preview image, but the caller doesn't have Read permission for the workbook.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/previewImage" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" > workbook-preview.png

The response is a graphics file in PNG format.

Set Custom View as Default for Users

Sets the specified custom for as the default view for up to 100 specified users. Success or failure for each user is reported in the response body.

Version: Available in API 3.21 (Tableau Cloud October 2023 / Server 2023.3) and later. Version Overview

License: No additional license required.

Permissions: Only Tableau administrators can set a custom view as the default view for users. Permissions Overview

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

URI

POST /api/api-version/sites/site-luid/customviews/custom-view-luid/default/users

URI Parameter Values

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

Request Body

Copy

<tsRequest>
  <users >
    <user id="5c9a81df-7ec0-4752-a057-82cd2bb22c44"/>
  </users>
</tsRequest>

Copy

{
  "users": {
    "user": {
      "id": "5c9a81df-7ec0-4752-a057-82cd2bb22c44"
    }
  }
}

cURL Request Example

curl --location 'https://qa-near.tsi.lan/api/3.21/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/3321cb71-6606-4d78-8a0c-e69a7e7d2261/default/users' --header 'Accept: application/xml' --header 'X-Tableau-Auth: X4fzaa75SJqSiCjq6EI9ow|uTR4NKykLGob3VustCzOq1htrchwo0ga|a946d998-2ead-4894-bb50-1054a91dcab3' --header 'Content-Type: text/plain' --data '<tsRequest><users><user id="5c9a81df-7ec0-4752-a057-82cd2bb22c44" /></users></tsRequest>'

Response Code

200

Response Body

Copy

<tsResponse>
  <customViewAsUserDefaultResults>
    <customViewAsUserDefaultViewResult success="true">
      <user id="5c9a81df-7ec0-4752-a057-82cd2bb22c44"/>
    </customViewAsUserDefaultViewResult>
  </customViewAsUserDefaultResults>
</tsResponse>

Copy

{
  "customViewAsUserDefaultResults": {
    "customViewAsUserDefaultViewResult": {
      "success": "true",
      "user": {
        "id": "5c9a81df-7ec0-4752-a057-82cd2bb22c44"
      }
    }
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions.
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Unhide a Recommendation for a View

Unhides a view from being recommended by the server by removing it from the list of views that are dimissed for a user. If the unhidden view meets the criteria for being recommended, then it will be displayed on the server Home or Recommendation pages.

URI

DELETE /api/api-version/sites/site-id/recommendations/dismissals/?type=view&id=view-luid

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the group.
view-luid	The LUID of the view to be removed from the list of views hidden from recommendation for a user.

Request Body

None

Permissions

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

Response Code

204

Response Body

None

Version

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

Errors

HTTP status	`error` Code	Condition	Details
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404029	Content not found	The content ID in the URI doesn't correspond to an existing content of the requested type.
404	404035	Recommendation not found	A hidden recommendation for the given content ID was not found.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.26/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/dismissals/?type=view&id=1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

No response body. Response code is 204.

Update Custom View

Changes the owner or name of an existing custom view.

Version: Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1). Version Overview

License: No additional license required.

Permissions: Tableau administrators can update the owner and name of a custom view. Other users can update those attributes of any custom view that they own. Permissions Overview

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

URI

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

URI Parameter Values

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

Request Body

<tsRequest>
  <customView name="new-name" >
	  <owner id="cdfe8548-84c8-418e-9b33-2c0728b2398a" />
  </customView>
</tsRequest>

{
  "customView": {
    "name": "new-name",
	"owner": {
	  "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a"
	}
  }
}

Request Attributes

`customView name`	(Optional) string The new name of the custom view that replaces the existing one.
`owner id`	(Optional) LUID The LUID of the new owner of custom view that replaces the existing one.

Required scope for JWT authorization

Introduced in Tableau Server 2022.3 (API 3.17).

tableau:views:update

cURL Request Example

curl -L -X PUT "https://qa-near/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/customviews/37d015c6-bc28-4c88-989c-72c0a171f7aa" -H "X-Tableau-Auth: njR9EGn0QSCpbDrUOh0IKg"wamRRyVFFUHTVwFL6OWEyOggxCwWYXuq"a946d998-2ead-4894-bb50-1054a91dcab3" -H "Content-Type: application/xml" --data-raw "<tsRequest> <customView name='new-name'> <owner id='cdfe8548-84c8-418e-9b33-2c0728b2398a' /> </customView> </tsRequest>"

Response Code

200

Response Body

<tsResponse>
  <customView
    id="37d015c6-bc28-4c88-989c-72c0a171f7aa"
    name="new-name_2514e471-95ed-4d22-92c0-da648c23891b"
    createdAt="2016-02-03T23:35:09Z"
    updatedAt="2022-10-21T04:41:27Z"
    lastAccessedAt="2022-10-21T04:43:55Z"
    shared="false">
      <view id="8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f" name="circle"/>
      <workbook id="2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5" name="my workbook"/>
      <owner id="cdfe8548-84c8-418e-9b33-2c0728b2398a" name="workgroupuser"/>
  </customView>
</tsResponse>

{
  "customView": {
    "id": "37d015c6-bc28-4c88-989c-72c0a171f7aa",
    "name": "New name 3_2514e471-95ed-4d22-92c0-da648c23891b",
    "createdAt": "2016-02-03T23:35:09Z",
    "updatedAt": "2022-10-21T04:41:27Z",
    "lastAccessedAt": "2022-10-21T04:43:55Z",
    "shared": "false",
    "view": {
 	  "id": "8e33ff19-a7a4-4aa5-9dd8-a171e2b9c29f",
	  "name": "circle"
    },
    "workbook": {
      "id": "2fbe87c9-a7d8-45bf-b2b3-877a26ec9af5",
      "name": "marks and viz types 2"
    },
    "owner": {
      "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
      "name": "workgroupuser"
    }
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403162	Unauthorized Access	The user does not have adminstrator permissions or Read permissions for the custom view..
404	404008	Resource Not Found	A custom view with the requested LUID could not be found.
405	405000	Invalid Request Method	Request type was not GET.

For more information, see Handling Errors.

Update Workbook

Modifies an existing workbook, allowing you to change the owner or project that the workbook belongs to and whether the workbook shows views in tabs. Updated workbooks can optionally be marked to appear in the recently viewed list.

You can manage Data Freshness Policy(Link opens in a new window) for a workbook, and enable View Acceleration(Link opens in a new window) for views in a workbook.

Version: Available in API 2.0 (Tableau Cloud and later). Data acceleration and data freshness policy setting update are added in API 3.22 (Tableau Cloud February 2024 / Server 2024.2). Version Overview(Link opens in a new window)

License: No additional license required.

Permissions: Users who are Tableau administrators can change a workbook's owner. Users who are not server administrators can update a workbook only if they have Write permission for the workbook and for the project. Tableau server and site administrators can change the dataAccelerationConfig accelerationEnable setting for a workbook. Workbook owners can change the setting if the site is configured to enable acceleration by owners(Link opens in a new window). Both administrators and workbook owners can change dataFreshnessPolicy settings. Permissions Overview(Link opens in a new window)

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

URI

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

PUT /api/api-version/sites/site-id/workbooks/workbook-id?includeViewAccelerationStatus=include-view-acceleration-status-flag

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to update.
include-view-acceleration-status-flag	Query parameter is optional. Boolean: If `includeViewAccelerationStatus=true` then the list of views and the acceleration status of each view will be returned.

Request Body

Copy

<tsRequest> 
  <workbook 
    name="Finance"
    showTabs="false"
    recentlyViewed="false"
    encryptExtracts="false" 
    description="The finance workbook.">
      <project id="3d6e8174-8cdf-43ec-94dd-0a1fd3662e47" />
      <owner id="ca6b9ee-1d85-465b-abc2-f200ae2443b9" />
      <views>
          <view id="22e48174-8cdf-43ec-94dd-0a1fd366gh78"/>
        </views>
      <dataAccelerationConfig 
        accelerationEnabled="false" 
        accelerateNow="false" />
      <dataFreshnessPolicy option="FreshAt">
        <freshAtSchedule frequency="weekly" time="08:15:00" timezone="America/Los_Angeles">
          <intervals>
            <interval weekDay="Monday" />
          </intervals>
        </freshAtSchedule>  
      </dataFreshnessPolicy>
  </workbook> 
</tsRequest>

Copy

{
  "workbook": {
    "name": "Finance",
    "showTabs": "false",
    "recentlyViewed": "false",
    "encryptExtracts": "false",
    "description": "The finance workbook.",
    "project": {
      "id": "3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"
    },
    "owner": {
      "id": "ca6b9ee-1d85-465b-abc2-f200ae2443b9"
    },
    "views": {
      "view": {
        "id": "22e48174-8cdf-43ec-94dd-0a1fd366gh78"
      }
    },
    "dataAccelerationConfig": {
      "accelerationEnabled": "false",
      "accelerateNow": "false"
    },
    "dataFreshnessPolicy": {
      "option": "FreshAt",
      "freshAtSchedule": {
        "frequency": "weekly",
        "time": "08:15:00",
        "timezone": "America/Los_Angeles",
        "intervals": {
          "interval": {
            "weekDay": "Monday"
          }
        }
      }
    }
  }
}

Notes on Data Freshness Policy(Link opens in a new window) and View Acceleration(Link opens in a new window):

Data Freshness Policy and View Acceleration are independent features.
If a policy is set without view acceleration for a workbook, then only query caching(Link opens in a new window) for the workbook will be affected by the policy.
If a workbook has a data freshness policy configured, then updating the workbook to turn on view acceleration will not impact the policy unless the update explicitly changes that.
If a workbook has accelerated views enabled, but does not have a data freshness policy explicitly set for it, data will be refreshed on the site default cadence of every 12 hours.
On Tableau Cloud, view acceleration is limited to 12 refreshes per day, per view. If data freshness policy for a workbook is set to refresh data more frequently than every 2 hours, refreshes for a view after the 12th one will not trigger the computation that accelerates that view until the first refresh of the next day.
The preceding example shows the freshAt data freshness policy option. The freshEvery option is illustrated in the following Attribute Values section.

Attribute Values

workbook name (Optional) New name for the workbook being updated.

workbook showTabs (Optional) Specify true to have the updated workbook show views in tabs; otherwise, false. The default is false.

workbook recentlyViewed (Optional) Set this value to true to have the updated workbook show in the site's recently viewed list. The default is false. Once the flag is set to true, setting it to false will have no effect. When enough views or workbooks have populated the recently viewed list, the oldest item will fall off the list and its recently-viewed-flag will revert to false.

workbook encryptExtracts (Optional) true to encrypt the extracts or false to not encrypt extracts. For more information, see Extract and Encryption Methods.

workbook description (Optional) Starting in API 3.20, the new description for the updated workbook.

project id (Optional) The LUID of a project to assign the workbook to.

owner id (Optional) The LUID of a user to assign the workbook to as owner.

dataAccelerationConfig accelerationEnable (Optional) Boolean: If true, accelerate the specified view(s). Default is false.

dataAccelerationConfig accelerateNow

(Optional) Boolean: If true, make view acceleration available as soon as possible. Default is false. Note, the view object in the response (visible by using the ?includeViewAccelerationStatus=true query parameter) contains the accelerationStatus attribute, which can have the following values:

Off - Accelerate now is not enabled.
Pending - Accelerate now is enabled, but backgrounder processes are still running to make the acceleration available.
On Acceleration is enabled.

view id (Optional) LUID: The LUID of a view being accelerated. If no views are listed in the request then all views in the workbook will be accelerated.

dataFreshnessPolicy option

(Optional) Enum: The data freshness policy mode for scheduling refreshment of the workbook data specified in the request. A valid value is one of:

SiteDefault - Use the default scheduling policy: refresh the data every 12 hours).
AlwaysLive - Refresh as the data changes.
FreshAt - Define a detailed cadence for refreshing the data.
FreshEvery- Define an interval between data refreshes.

freshAtSchedule frequency

(Optional) Enum: The interval of workbook data refresh. A valid value is one of:

Day
Week
Month

freshAtSchedule time (Optional) Time in HH:MM:SS: The time of day that workbook data will be refreshed, in increment of 15 minutes. Minutes must end in 00, 15, 30, or 45. for instance time="10:30:00".

freshAtSchedule timeZone (Optional) Timezone string in IANA format: The timezone of the fresh at schedule time. For instance, timezone="America/Los_Angeles". If no timezone is provided, then the local timezone of the Tableau server is used."

freshAtSchedule intervals interval

A value that specifies the interval between refreshes of view acceleration data. The value you specify here depends on the value specified in freshAtSchedule frequency.

Day

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

Week

The interval expression is weekDay="weekday", where weekday is Sunday, Monday, Tuesday, Thursday, Friday, or specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week.

Month

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

freshEverySchedule frequency

(Optional) Enum: The time unit used for the cadence of view acceleration data refreshes. The count of the specified unit that occurs between refreshes is determined by freshEverySchedule value. A valid value is one of:

Minutes
Hours
Days
Weeks

freshEverySchedule value (Optional) Integer: The quantity of frequency units between view acceleration data refreshes. For instance, to specify a refresh every 4 hours, the dataFreshnessPolicy would look like:

XML JSON

Copy

<dataFreshnessPolicy option="FreshEvery">
  <freshEverySchedule 
  frequency="hours" 
  value="4" />
  </dataFreshnessPolicy>

Copy

"dataFreshnessPolicy": {
  "option": "FreshEvery",
  "freshEverySchedule": {
  "frequency": "hours",
  "value": 4"
  }
}

With the exception of dataFreshnessPolicy options, any combination of the elements inside the <workbook> element is valid. Only the attributes and child elements that are included result in updates to the data source. If no attributes or nested elements are included, no update is made.

The dataFreshnessPolicy option can only be one of listed options, and the elements of a specified option are required for that option to be updated.

If the <project> element is included, the id attribute must be included; other attributes of the <project> element are ignored.

If the <owner> element is included, the id attribute must be included; other attributes of the <owner> element are ignored.

cURL Example

curl --location --request PUT "https://myServer/api/3.22/sites/d76ee955-ccc7-4333-ab3b-25ad2f8b1aa8/workbooks/c75aaa17-727f-48f8-80d1-1e66c30497c5" \ --header "Content-Type: application/xml" \ --header "X-Tableau-Auth: vZg2soQ2TuiULoJgZ60h_A|JIfSgwAzBQ2QfSVS1PSsHvD9uynKLzWz|d76ee955-ccc7-4333-ab3b-25ad2f8b1aa8" \ --header "Cookie: AWSALBAPP-0=AAAAAAAAAADyQT+tw75WkCZpVc/icDu7+3QFC+j4W5jpddfTbd8p8kxx5cx5slxbi2jSYvaAa0RBfxXvQ3tTjfZGHnt3ORMP5y79bEWR/lBKRMbJpRVYfI4jV32tGCld6NPtpgwYogFxZBo=; AWSALBAPP-1=_remove_; AWSALBAPP-2=_remove_; AWSALBAPP-3=_remove_; hid=uw2a-hap01" \ --data "<tsRequest> <workbook > <dataAccelerationConfig accelerationEnabled='true' accelerateNow='true' /> <dataFreshnessPolicy option='FreshEvery'> <freshAtSchedule frequency='Week' time='08:15:00' timezone='America/Los_Angeles'> <intervals> <interval weekDay='Monday' /> </intervals> </freshAtSchedule> </dataFreshnessPolicy> </workbook> </tsRequest>"

Response Code

200

Response Body

Copy

<tsResponse>
  <workbook id="0828bd63-dea5-454f-8f54-30f9a92760ff" 
    name="WB_Election_live" 
    description="" contentUrl="WB_Election_live" 
    webpageUrl="http://MyServer/#/workbooks/4" 
    showTabs="false" size="1" createdAt="2024-01-25T23:42:57Z" 
    updatedAt="2024-01-25T23:42:57Z" 
    encryptExtracts="false" 
    defaultViewId="10f6d099-fe90-41a1-a77b-1512b818d23c">
      <project id="7eb51f54-bbca-11ee-9262-638afb01250c" name="Default"/>
      <location id="7eb51f54-bbca-11ee-9262-638afb01250c" type="Project" name="Default"/>
      <owner id="09d032b6-d17d-444c-afbe-d71c22f7ee31" name="test"/>
      <tags/>
      <views>
        <view id="fcc36499-fd2d-42af-8e2c-29d1c7893edd" 
            name="Votes" 
            contentUrl="WB_Election_live/sheets/Votes" 
            createdAt="2024-01-25T23:42:57Z" 
            updatedAt="2024-01-25T23:42:57Z" 
            viewUrlName="Votes">
            <tags/>
            <dataAccelerationConfig accelerationEnabled="true" 
                accelerationStatus="Pending"/>
          </view>
        </views>
      <dataFreshnessPolicy option="freshAt"/>
          <freshAtSchedule />
            <intervals>
              <interval weekDay="Monday"
            </intervals>
      </dataFreshnessPolicy>
  </workbook>
</tsResponse>

Copy

{
  "workbook": {
    "name": "Finance",
    "showTabs": "false",
    "recentlyViewed": "false",
    "encryptExtracts": "false",
    "description": "The finance workbook.",
    "project": {
      "id": "3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"
    },
    "owner": {
      "id": "ca6b9ee-1d85-465b-abc2-f200ae2443b9"
    },
    "views": {
      "view": {
        "id": "22e48174-8cdf-43ec-94dd-0a1fd366gh78"
      }
    },
    "dataAccelerationConfig": {
      "accelerationEnabled": "false",
      "accelerateNow": "false"
    },
    "dataFreshnessPolicy": {
      "option": "FreshAt",
      "freshAtSchedule": {
        "frequency": "weekly",
        "time": "08:15:00",
        "timezone": "America/Los_Angeles",
        "intervals": {
          "interval": {
            "day": "Monday"
          }
        }
      }
    }
  }
}

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

A response for the dataFreshnessPolicy segment with the FreshEvery option configured for weekly refreshes, would look like:

XML JSON

Copy

<dataFreshnessPolicy option="FreshEvery">
  <freshEverySchedule 
  frequency="Weeks" 
  value="1" />
  </dataFreshnessPolicy>

Copy

"dataFreshnessPolicy": {
  "option": "FreshEvery",
  "freshEverySchedule": {
  "frequency": "Weeks",
  "value": 1"
  }
}

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400036	Bad request	View acceleration is enabled, but the workbook loads too quickly to make use of it, or the view has never been accessed by a user.
403	403025	Project update forbidden	A non-administrator user tried to change the workbook project, but the caller doesn't have Write permission for the target project.
403	403027	Owner update forbidden	A non-administrator user tried to change the workbook owner.
403	403027	Update forbidden	A non-administrator user tried to change the workbook, but the caller doesn't have Write permission for the workbook.
403	403004	Update forbidden	A non-administrative user tried to update the workbook, but does not have permissions to publish the updated workbook to the project.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404002	Owner not found	The owner ID in the request body doesn't correspond to an existing user.
404	404005	Project not found	The project ID in the URI doesn't match the project ID provided in the request body.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Update Workbook Connection

Updates the server address, port, username, or password for the specified workbook connection.

If the workbook contains multiple connections to the same data source type, all the connections are updated. For example, if the workbook contains three connections to the same PostgreSQL database, and you attempt to update the user name of one of the connections, the user name is updated for all three connections.

Any combination of the attributes inside the <connection> element is valid. If no attributes are included, no update is made.

URI

PUT /api/api-version/sites/site-id/workbooks/workbook-id/connections/connection-id

Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the workbook.
workbook-id	The ID of the workbook to update.
connection-id	The ID of the connection to update.

Request Body

<tsRequest>
  <connection
    serverAddress="server-address" serverPort="port"
    userName="connection-username" password="connection-password"
    embedPassword="embed-password"
	queryTaggingEnabled="query-tagging-enabled" />
</tsRequest>

Attribute Values

server-address	The new server for the connection.
port	The new port for the connection.
connection-username	The new username for the connection.
connection-password	The new password for the connection.
embed-password	`True` to embed the password; otherwise, `False`.
query-tagging-enabled	Starting with API 3.23 (Tableau Cloud June 2024 / Server 2024.2), the `queryTaggingEnabled` attribute is deprecated, will no longer be supported, and may be retired in future releases. Instead, for Tableau Server, use TSM to enable query tagging for all content on a server by setting `native_api.UserInfoInGeneratedSQLEnabled`(Link opens in a new window) to `true`. For API 3.22 (Tableau Cloud February 2024 / Server 2024.1) or earlier: If `true`, query tagging is enabled. If `false`, query tagging is disabled. The default is `false`. For more information on query tagging, see Understand Workbook Impact on Your Database Using Query Tagging(Link opens in a new window).

Any combination of the attributes inside the <connection> element is valid. If no attributes are included, no update is made.

Permissions

Users who are not server administrators or site administrators can update permissions only for a workbook for which they have the Write capability (either explicitly or implicitly). Only users with administrator permissions can enable or disable query tagging.

Required scope for JWT authorization

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

tableau:workbooks:update

Response Code

200

Response Body

<tsResponse>
  <connection id="connection-id"
    serverAddress="server-address" serverPort="port"
	userName="connection-user-name"
	queryTaggingEnabled="query-tagging-enabled" />
</tsResponse>

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
403	403029	Update forbidden	A non-administrator user tried to update the workbook connection, but the caller doesn't have Write permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in the URI doesn't correspond to an existing workbook.
404	404020	Connection not found	The connection ID in the URI doesn't correspond to an existing connection.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Update Workbook Now

Refreshes the specified workbook.

This method refreshes the specified workbook, with no need to associate the workbook refresh with a scheduled task. This method is the equivalent of selecting a workbook using the Tableau Server UI, and then selecting Refresh Extracts from the menu (also known as a "manual refresh").

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

URI

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

Parameter Values

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

Request Body

<tsRequest></tsRequest>

Permissions

Tableau Server users who are not server administrators or site administrators can only refresh workbooks if they own the workbook, or if they are the project leader for the project.

Required scope for JWT authorization

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

tableau:tasks:run

Response Code

202

Response Body

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

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401000	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403032	Update Forbidden	A non-administrator user attempted to query workbook views, but the caller doesn't have sufficient permissions.
403	403004	Update forbidden	A non-administrative user tried to update the workbook, but does not have permissions to publish the updated workbook to the project.
404	404000	Site not found	The site ID in the URI is unknown.
404	404006	Resource not found	The workbook ID in the URI is unknown.
405	405000	Invalid request method	Request type was not POST.
409	409093	Operation already in Queue	The extract refresh job is already in the queue.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.26/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/workbooks/5de9cc53-b17d-45af-804d-49144b39f29f/refresh" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -H "Content-Type: application/xml" –d @empty-tsrequest.xml"

Content of empty-tsRequest.xml:

<tsRequest>
</tsRequest>

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-2.8.xsd">
  <job id="20cf4ddc-6d73-4733-89ec-8d336669bd56" mode="Asynchronous" type="RefreshExtract" createdAt="2017-12-06T22:58:52Z">
    <extractRefreshJob>
      <workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" name="Regional" />
    </extractRefreshJob>
  </job>
</tsResponse>

Upload Workbook Encrypted Keychain

Uploads the encrypted version of the embedded credentials. This method will only work if the credentials are encrypted with the latest public key used to link the source Tableau Server with the destination Tableau Cloud or Tableau Server site.

Before you use this method, you must create public and private keys for resources with embedded credentials. For more information, see Migrate Workbooks and Data Sources with Embedded Credentials.

Version: Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later. Version Overview(Link opens in a new window)

License: No additional license required.

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

JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)

URI

PUT /api/api-version/sites/site-luid/workbooks/workbook-luid/applyKeychain

URI Parameter Values

api-version	The version of the API to use, such as `3.26`. For more information, see REST API and Resource Versions.
site-luid	The LUID for the site.
workbook-luid	The LUID of the workbook to download the encrypted keychain from.

Request Body

<tsRequest>
    <associatedUserLuidMapping/>
    <encryptedKeychainList>
        <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain>
    </encryptedKeychainList>
</tsRequest>

{
"associatedUserLuidMapping": [],
"encryptedKeychainList": {
  "encryptedKeychain": "BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y="
  }
}

Request Attributes

`associatedUserLuidMapping`	(Required) The user IDs from the source site mapped to destination site user IDs.
`encryptedKeychainList`	(Required) List of encrypted keychains from the source Tableau Server.

cURL Request Example

curl --location 'https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/applykeychain' \
--header 'Content-Type: application/xml' \
--header 'X-Tableau-Auth: nbQAstTxTHuBlcMlXZ3QKg|LXn5aiYcffck999kgpOPrQft5JkvRsYg|7a2f773d-4a9f-496e-afc6-a60517cb1b86' \
--data '<tsRequest>
    <associatedUserLuidMapping/>
    <encryptedKeychainList>
        <encryptedKeychain>BADsJ5lBKho2Tdqqbo7txS8IyGlBu9LiRyb8etCHJLhBUurgIRHk3g5AeMQg6KHBw+6nwNIDEd65MKi76DLd5aIMhQC5aLCR4NE7R2gp7JbxLo+nOMGnfDQm5XekJVpLQGfY53GIX52ED2iTfOQ0yRNbnPV4djT0z23rosG0gpmqXV/GlBu9LiRyb8wx8RisnZdvv+SAlv222jVhksX1w5A6HB3Bs45BeWfpwrOnHwnNoWUGwHuu4iGlyE7m65RlATZN+fvDGOFN1zU2lXaSZyWqRKiWkD+oGlBu9LiRyb8Gz7RnesKvH6QEL9sT8cXA1ZOEA531xNAv9rjazEP5BssIdA1GcJ5J7zar5xxC68qm3cz3MkndyqWXZrf0vWPgwysUHEpWn60oDG/8/xG6c0Eigh4gwE+dA+NF1GlBu9LiRyb8+AzJ7vatf95LDwAuRT43G3Q+WApx9qBPXco15pKjwy00rHPgn4cRtu+unwh6d3gIh6AbK6X++U/vV/Ktpe31lSZmV8eHPeTNfdCrGOT9ozZhF5oKGlBu9LiRyb8tf1YcXawh3bvtZxg9d8a2mKNXDeaF+uJrpI43aFa4KrJKdfvDpq2k0aJhL1QNxWSFBYw0tPJX/rhKAeOHHY2K44Wh5JNWwL+x1uYap93IK303sJ1GlBu9LiRyb8UhfIW7o5iUtbYWrpCvVwubZLf4U5Y=</encryptedKeychain>
    </encryptedKeychainList>
</tsRequest>'

Response Code

200

Response Body

None.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403054	Unauthorized Access	A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Workbook not found	The workbook ID in URI doesn't correspond to an existing workbook.
405	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help