Workbooks and Views Methods

URI

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

Parameter Values

Request Body

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

Attribute Values

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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>

URI

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

Parameter Values

Request Body

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

Attribute Values

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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>

Version: Available in API 3.18 (Tableau Cloud December 2024) and later. Not available for Tableau Server. 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

Request Body

None.

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.

URI

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

Parameter Values

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

For more information, see Handling Errors.

URI

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

Parameter Values

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

For more information, see Handling Errors.

URI

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

Parameter Values

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

For more information, see Handling Errors.

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

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

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.

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

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

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

tableau: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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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.

URI

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

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

Parameter Values

Request Body

None

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.

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.

Version

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

Errors

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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, saved as a pdf.

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

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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.

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

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

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

tableau: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

For more information, see Handling Errors.

Version: Available in API 3.18 (Tableau Cloud December 2024) and later. Not available for Tableau Server. 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

Request Body

None.

cURL Request Example

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

Response Code

200

Response Body

<tsResponse >
  <pagination pageNumber="1" pageSize="100" totalAvailable="1673"/>
  <customView
    id="37d015c6-bc28-4c88-989c-72c0a171f7aa"
    name="New name 2"
    createdAt="2016-02-03T23:35:09Z"
    updatedAt="2022-09-28T23:56:01Z"
    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",
	"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"
    }
  }
}

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

License: No additional license required.

Permissions: 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

Request Body

None.

cURL Request Example

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

Response Code

200

Response Body

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

URI

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

Parameter Values

Request Body

None

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

Required scope for JWT authorization

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

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

tableau:content:read

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>
        

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

Version

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

Errors

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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>
          

URI

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

Parameter Values

Request Body

None

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

Required scope for JWT authorization

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

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

tableau:content:read

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="ownwer-ide"
		<project id="product-id"
		<tags/>
	</view>
	<!--      . . .more views with the same name. . .      -->
</tsResponse>
        

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

Version

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

Errors

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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>
          

URI

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

Path Parameters

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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>
          

URI

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

Parameter Values

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

For more information, see Handling Errors.

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

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

For more information, see Handling Errors.

URI

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

Path Parameter Values

Request Body

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

Request Parameters

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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.

Version: Available in API 3.18 (Tableau Cloud December 2024) and later. Not available for Tableau Server. 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

Request Body

None.

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"
	  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",
	  "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
  }
}

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

Request Body

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

Publishing a file in the request body

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" 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" 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" 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

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.

Required scope for JWT authorization

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

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

tableau:workbooks:create

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

Response Headers

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

Version

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

Errors

For more information, see Handling Errors.

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>

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

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

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

Required scope for JWT authorization

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

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

tableau:content:read

Response Code

200

Response Body

<tsResponse>
  <views>
    <view id="view-id"
        name="view-name"
        contentUrl="content-url" >
      <workbook id="workbook-id" />
      <owner id="owner-id" />
      <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 2.2 and later. For more information, see REST API and Resource Versions.

Errors

For more information, see Handling Errors.

Example

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

Example response:

<tsResponse version-and-namespace-settings>
  <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>
</tsResponse>

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

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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>

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

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

The response body contains data in CSV format.

Version

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

Errors

For more information, see Handling Errors.

Example

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

Example response:

The returned view data will be 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

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

Parameter Values

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

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

Version

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

Errors

For more information, see Handling Errors.

Example

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

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=page-orientation

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

Parameter Values

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

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.

Version

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

Errors

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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.

URI

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

Parameter Values

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

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

tableau: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

For more information, see Handling Errors.

Version: Available in API 2.0 and later. 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

Request Body

None

Response Code

200

cURL Request Example

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

Response Body

<tsResponse>
  <workbook id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
	name="Finance"
    description="The finance workbook."
    contentUrl="Finance"
	webpageUrl="https://MY_SERVER/workbooks/#/1"
	size="2"
	defaultViewId=064330ca-4222-4ca8-b01e-2525839a7f5f"
	createdAt="2011-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
    showTabs="true" size="3"
	encryptExtracts="true" >
	  <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
      <tags/>
      <views>
        <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c"
          contentUrl="Finance/sheets/Taleof100Start-ups"/>
		    <tags/>
		<view id="9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b"
		  contentUrl="Finance/sheets/EconomicIndicators"/>
		    <tags/>
        <view id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6"
          contentUrl="Finance/sheets/InvestingintheDow"/>
            <tags/>
        </views>
  </workbook>
</tsResponse>

{
  "workbook": {
  "id": "1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d",
  "name": "Finance",
  "description": "The finance workbook.",
  "contentUrl": "Finance",
  "webpageUrl": "https://MY_SERVER/workbooks/#/1",
  "size": "2",
  "defaultViewId": "064330ca-4222-4ca8-b01e-2525839a7f5f",
  "createdAt": "2011-03-30T22:32:35Z",
  "updatedAt": "2016-01-13T01:00:02Z",
  "showTabs": "true",
  "encryptExtracts": "true",
  "project": {
    "id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
	 "name": "Tableau Samples"
	},
  "owner": {
	"id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"
	},
  "tags": [],
	"views": [
	  {
	    "id": "1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c",
	    "contentUrl": "Finance/sheets/Taleof100Start-ups",
	    "tags": []
	  },
	  {
		"id": "9a8a7b6b-5c4c-3d2d-1e0e-9a8a7b6b5b4b",
		"contentUrl": "Finance/sheets/EconomicIndicators",
		"tags": []
	  }
	]
  }
}

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

Errors

For more information, see Handling Errors.

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

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

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

tableau: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

Version

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

Errors

For more information, see Handling Errors.

Example: Get workbooks without filter

curl "http://MY-SERVER/api/3.20/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.20/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"

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

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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>

URI

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

Parameter Values

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" />
    < ... additional connections ... >
  </connections>
</tsResponse>
        

Version

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

Errors

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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.

URI

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

Parameter Values

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

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

tableau: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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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.

URI

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

Parameter Values

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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.

Version: Available in API 3.18 (Tableau Cloud December 2024) and later. Not available for Tableau Server. 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

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

Required scope for JWT authorization

Introduced in Tableau Server 2022.3 (API 3.17).

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

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

<tsRequest>
  <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"
    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>
</tsRequest>

{
  "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",
    "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"
    }
  }
}

URI

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

Parameter Values

Request Body

<tsRequest>
  <workbook
	name="updated-workbook-name"
	showTabs="show-tabs-flag"
	  recentlyViewed"recently-viewed-flag"
	  encryptExtracts="encrypt-extracts-flag" >
	    <project id="new-project-id" />
        <owner id="new-owner-id" />
   <dataAccelerationConfig accelerationEnabled="true" accelerateNow="true"/>
 </workbook>
</tsRequest>       

Attribute Values

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.

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.

Permissions

Users who are server administrators or site 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. Only Tableau Server users who are server administrators or site administrators can set the change the dataAccelerationConfig accelerationEnable setting.

Required scope for JWT authorization

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

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

tableau:workbooks:update

Response Code

200

Response Body

<tsResponse>
  <workbook id="workbook-id" name="workbook-name"
      contentUrl="workbook-url"
      showTabs="show-tabs-flag"
      size="size-in-megabytes"
      createdAt="datetime-created"
      updatedAt="datetime-updated"
      encryptExtracts="encryptExtracts" >
    <project id="project-id" />
    <owner id="owner-id" />
    <dataAccelerationConfig accelerationEnabled="true"/ >
  </workbook>
</tsResponse>
        

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

Version

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

Errors

For more information, see Handling Errors.

Example

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

This command changes a workbook whose ID is 1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d from its original project to a new project (7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6). The new project ID is specified in the update-workbook.xml file.

Content of update-workbook.xml:

<tsRequest>
  <workbook showTabs="true" >
      <project id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" />
 </workbook>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <workbook name="Finance" id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
        contentUrl="Finance" showTabs="true" size="2"
        createdAt="2011-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z">
    <project id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6"/>
    <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
  </workbook>
</tsResponse>

URI

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

Parameter Values

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

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

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

tableau: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

For more information, see Handling Errors.

URI

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

Parameter Values

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

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

tableau: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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.20/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>