---
schema_version: "1"
id: 0ab22c2591f716471991cb1f720a605fc1915fecf3a65d0bea24e2c17d7a8b29
title: Workbooks and Views Methods
collection: tableau
version: current
locale: en-us
portal_url: https://docs.salesforce.com/tableau/current/en-us/api/rest_api/REST/rest_api_ref_workbooks_and_views.md
canonical_url: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm
source_site: help.tableau.com
content_type: documentation
content_hash: 76fe9a66c9610aa07f0491d5b269071412e0289cb87d98b717f9578195e6fc66
description: "Using the workbooks and views methods of the Tableau Server REST API you can do the operations listed in the following categories:"
---
[Skip to main content](#main-content)

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

**Validate Tableau workbook files (TWB files)**

- Syntactically (using the [XSD](https://github.com/tableau/tableau-document-schemas)) and semantically validate TWB files.

Many workbook and view methods relate to UI elements and concepts described at: [Workbooks and Sheets](https://help.tableau.com/current/pro/desktop/en-us/environ_workbooksandsheets.htm).

## Use Postman

Our Postman collection of requests enables you to construct, send, and examine HTTP requests to the Tableau Server or Tableau Cloud API without writing initial code. Postman is a free online app used by many developers for prototyping API calls, investigating issues, and generating request code in a variety of languages.

[Postman: Workbooks and Views](https://www.postman.com/salesforce-developers/salesforce-developers/folder/9eavnhy/workbooks-and-views)

## 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">view-id</span></td><td>The ID of the views to add tags to.</td></tr></tbody></table>

#### Request Body

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

#### Attribute Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1"> <col></colgroup><tbody><tr><td><span class="api-placeholder">view-id</span></td><td>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 <span class="api-command-ref">&lt;tags&gt;</span> element is empty, no new tags are added to the view.</td></tr><tr><td><span class="api-placeholder">tag</span></td><td>The text of the tag.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:view_tags:update
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table">
                                <colgroup>
                                    <col class="api-error-table-col-1">
                                    <col class="api-error-table-col-2">
                                    <col class="api-error-table-col-3">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <th>HTTP status</th>
                                        <th><code>error</code> Code</th>
                                        <th>Condition</th>
                                        <th>Details</th>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400000</td>
                                        <td>Bad request</td>
                                        <td>The content of the request body is missing or incomplete, or contains malformed XML.</td>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400076</td>
                                        <td>Error adding tags</td>
                                        <td>There was a problem adding tags to the specified view.</td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403004</td>
                                        <td>Adding tags forbidden</td>
                                        <td>
                                            <p>
                                            A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if
                                            the <span class="api-command-ref">&lt;tags&gt;</span> element is empty.
                                        </p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404000</td>
                                        <td>Site not found</td>
                                        <td>
                                            <p>The site ID in the URI is not for an existing site.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404011</td>
                                        <td>View not found</td>
                                        <td>The view ID in URI doesn't correspond to an existing view.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404009</td>
                                        <td>Workbook ID mismatch</td>
                                        <td>The request body contains a view ID (which is optional) and it doesn't match the ID in the URI.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>405000</td>
                                        <td>Invalid request method</td>
                                        <td>Request type was not <span class="api-command-ref">PUT</span>.</td>
                                    </tr>
                                </tbody>
                            </table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to add tags to.</td></tr></tbody></table>

#### Request Body

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

#### Attribute Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1"> <col></colgroup><tbody><tr><td><span class="api-placeholder">workbook-id</span></td><td>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 <span class="api-command-ref">&lt;tags&gt;</span> element is empty, no new tags are added to the workbook.</td></tr><tr><td><span class="api-placeholder">tag</span></td><td>The text of the tag.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:workbook_tags:update
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table">
                                <colgroup>
                                    <col class="api-error-table-col-1">
                                    <col class="api-error-table-col-2">
                                    <col class="api-error-table-col-3">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <th>HTTP status</th>
                                        <th><code>error</code> Code</th>
                                        <th>Condition</th>
                                        <th>Details</th>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400000</td>
                                        <td>Bad request</td>
                                        <td>The content of the request body is missing or incomplete, or contains malformed XML.</td>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400049</td>
                                        <td>Error adding tags</td>
                                        <td>There was a problem adding tags to the specified workbook.</td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403004</td>
                                        <td>Adding tags forbidden</td>
                                        <td>
                                            <p>
                                        A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if
                                        the <span class="api-command-ref">&lt;tags&gt;</span> element is empty.
                                    </p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404000</td>
                                        <td>Site not found</td>
                                        <td>
                                            <p>The site ID in the URI is not for  an existing site.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404006</td>
                                        <td>Workbook not found</td>
                                        <td>The workbook ID in URI doesn't correspond to an existing workbook.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404009</td>
                                        <td>Workbook ID mismatch</td>
                                        <td>The request body contains a workbook ID (which is optional) and it doesn't match the ID in the URI.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>405000</td>
                                        <td>Invalid request method</td>
                                        <td>Request type was not <span class="api-command-ref">PUT</span>.</td>
                                    </tr>
                                </tbody>
                            </table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

`curl "http://MY-SERVER/api/3.29/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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:views:update

- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-luid</span></td><td>The LUID for the site.</td></tr><tr><td><span class="api-placeholder">custom-view-luid</span></td><td>The LUID for the custom view being updated.</td></tr></tbody></table>

#### 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](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm) 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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad Request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized Access</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403162</td><td>Unauthorized Access</td><td>The user does not have adminstrator permissions or <b>Read</b> permissions for the custom view..</td></tr><tr><td>404</td><td>404008</td><td>Resource Not Found</td><td>A custom view with the requested LUID could not be found.</td></tr><tr><td>405</td><td>405000</td><td>Invalid Request Method</td><td>Request type was not GET.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">view-id</span></td><td>The ID of the view to remove the tag from.</td></tr><tr><td><span class="api-placeholder">tag-name</span></td><td>The name of the tag to remove from the view.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:view_tags:delete
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### Response Code

204

#### Response Body

None

#### Version

Version 1.0 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400078</td><td>Error deleting tag</td><td>There was a problem deleting the tag from the specified view.</td></tr><tr><td>403</td><td>403004</td><td>Deleting tags forbidden</td><td>A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID or URL namespace in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>404</td><td>404007</td><td>Tag not found</td><td>The tag in the URI doesn't exist for the specified workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">DELETE</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to remove the tag from.</td></tr><tr><td><span class="api-placeholder">tag-name</span></td><td>The name of the tag to remove from the workbook.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:workbook_tags:delete
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### Response Code

204

#### Response Body

None

#### Version

Version 1.0 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400051</td><td>Error deleting tag</td><td>There was a problem deleting the tag from the specified workbook.</td></tr><tr><td>403</td><td>403004</td><td>Deleting tags forbidden</td><td>A non-administrator user called this method but doesn't have permission to delete a tag from the specified workbook.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID or URL namespace in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>404</td><td>404007</td><td>Tag not found</td><td>The tag in the URI doesn't exist for the specified workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">DELETE</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Delete View

Deletes a view from a workbook.

Use the [Get Workbook](#query_workbook) method or the [Query Views for Workbook](#query_views_for_workbook) method to find the view ID.

If you delete the only view in a workbook, the workbook is deleted.

#### URI

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

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the view.</td></tr><tr><td><span class="api-placeholder">view-id</span></td><td>The ID of the view to remove.</td></tr></tbody></table>

#### Request Body

None

#### Permissions

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:views:delete
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### Response Code

204

#### Response Body

None

#### Version

Introduced in Tableau Cloud December 2025 / Server 2025.3 (API 3.27). For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400212</td><td>Generic error</td><td>An unknown error occurred. Try again.</td></tr><tr><td>403</td><td>403004</td><td>Operation on resource unauthorized</td><td>Insufficient permissions to perform the operation. Confirm you have <span class="uicontrol">Read</span> and <span class="uicontrol">Delete</span> permissions for the view.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site. Confirm the site ID.</td></tr><tr><td>404</td><td>404011</td><td>View not found</td><td>The view ID in the URI doesn't correspond to an existing view. Confirm the view ID.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>The HTTP request method was wrong. Confirm you're using the HTTP <span class="api-command-ref">DELETE</span> method.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to remove.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:workbooks:delete
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### Response Code

204

#### Response Body

None

#### Version

Version 2.0 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">DELETE</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views).

#### 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">view-id</span></td><td>The ID of the view to use as the source of the crosstab to be downloaded as an <code>.xlsx</code> file.</td></tr><tr><td><span class="api-placeholder">max-age-minutes</span></td><td>(Optional) The maximum number of minutes an <code>.xlsx</code> file will be cached on the server before being refreshed. To prevent multiple <code>.xlsx</code> 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.</td></tr><tr><td><span class="api-placeholder">filter-value</span></td><td>The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter <code>/excel?vf_year=2017</code> would only display data from the year 2017. To learn more, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views">View filter queries</a>.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:views:download
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table">
                                <colgroup>
                                    <col class="api-error-table-col-1">
                                    <col class="api-error-table-col-2">
                                    <col class="api-error-table-col-3">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <th>HTTP status</th>
                                        <th><code>error</code> Code</th>
                                        <th>Condition</th>
                                        <th>Details</th>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400101</td>
                                        <td>Unknown error</td>
                                        <td>
                                            <p>There was a problem downloading or querying this file.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400130</td>
                                        <td>Unknown error</td>
                                        <td>
                                            <p>The view ID in the URI doesn't correspond to a view available on the specified site.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>401</td>
                                        <td>4001XX</td>
                                        <td>Unauthorized</td>
                                        <td>
                                            <p>The authentication token for the request is missing, invalid, or expired.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>4031XX</td>
                                        <td>Unauthorized</td>
                                        <td>
                                            <p>A user attempted to download a .xlsx file without <span class="api-command-ref">Read</span> and/or
								<span class="api-command-ref">ExportData</span> permissions for the workbook or view, and is not an administrator. </p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404xxx</td>
                                        <td>Site or view not found</td>
                                        <td>The site or view specified in the request could not be found.</td>
                                    </tr>
                                    <tr>
                                        <td>405</td>
                                        <td>405000</td>
                                        <td>Invalid request method</td>
                                        <td>Request type was not <span class="api-command-ref">GET</span>.</td>
                                    </tr>
                                </tbody>
                            </table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to download.</td></tr><tr><td><span class="api-placeholder">extract-value</span></td><td>(Optional) The <span class="api-placeholder">extract-value</span> is a Boolean value (<code>False</code> or <code>True</code>). When the workbook specified for download has an extract, if you add the parameter <code>?includeExtract=False</code>, 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.</td></tr></tbody></table>

#### 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
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>403</td><td>403019</td><td>Read forbidden</td><td>A non-administrator user attempted to download a workbook, but the caller doesn't have <span class="api-command-ref">ExportXml</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

`curl "http://MY-SERVER/api/3.29/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](https://help.tableau.com/current/server/en-us/cmt-migration_embedded_credentials.htm).

**Version:** Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later. _[Version Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**License:** No additional license required.

**Permissions:** This method can only be called by Tableau Cloud and Tableau Server admins.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope:** tableau:embedded\_credentials:download

- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-luid</span></td><td>The LUID for the site.</td></tr><tr><td><span class="api-placeholder">workbook-luid</span></td><td>The LUID of the workbook to download the encrypted keychain from.</td></tr></tbody></table>

#### 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

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><code>destinationSiteUrlNamespace</code>
                                        </td>
                                        <td>
                                            <p>
								(Required) The site name on Tableau Cloud.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><code>destinationSiteLuid</code>
                                        </td>
                                        <td>(Required) &nbsp;The site ID on Tableau Cloud.</td>
                                    </tr>
                                    <tr>
                                        <td><code>destinationServerUrl</code>
                                        </td>
                                        <td>
                                            <p>(Required) The destination Tableau Cloud URL.</p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

#### cURL Request Example

```
curl --location "https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/retrieveKeychain" -X POST --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="
  }
}
```

## 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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 / Tableau 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/ Tableau Server 2025.3) and later:

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

#### Parameter Values

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1-wide">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><span class="api-placeholder">api-version</span>
                                        </td>
                                        <td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">site-id</span>
                                        </td>
                                        <td>The ID of the site that contains the workbook.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">workbook-id</span>
                                        </td>
                                        <td>The ID of the workbook to use as the source of the .pdf file to be downloaded.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">max-age-minutes</span>
                                        </td>
                                        <td>(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.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">orientation</span>
                                        </td>
                                        <td>(Optional) The orientation of the pages in the .pdf file produced. The value can be
								<code>Portrait</code>
								or <code>Landscape</code>. If this parameter is not present the page orientation will default to <code>Portrait</code>.
							</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">page-type</span>
                                        </td>
                                        <td>
                                            <p>(Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be:
								<code>A3</code>,
								<code>A4</code>,
								<code>A5</code>,
								<code>B5</code>,
								<code>Executive</code>,
								<code>Folio</code>,
								<code>Ledger</code>,
								<code>Legal</code>,
								<code>Letter</code>,
								<code>Note</code>,
								<code>Quarto</code>,
								or <code>Tabloid</code>.</p>
                                            <p>If this parameter is not present the page type will default to <code>Legal</code>.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><i>fieldname</i>=<i>filter-value</i></td>
                                        <td>
                                            <p><span style="font-weight: normal;font-style: italic;"> Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later:</span>
                                            </p>
                                            <p>(Optional) An expression that applies a granular filter to the request. Returns will be based on the value (<i>filtervalue</i>) of the dimension or measure (<i>fieldname</i>) of your view data you specify. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views">View filter queries</a>.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">viz-height</span>
                                        </td>
                                        <td>(Optional) The height of the rendered pdf image in pixels that, along with the value of <code>vizWidth</code>, determines its resolution and aspect ratio.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">viz-width</span>
                                        </td>
                                        <td>(Optional) The width of the rendered pdf image in pixels that, along with the value of <code>vizHeight</code>, determines its resolution and aspect ratio.</td>
                                    </tr>
                                </tbody>
                            </table>

#### 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

<table class="api-error-table">
                                <colgroup>
                                    <col class="api-error-table-col-1">
                                    <col class="api-error-table-col-2">
                                    <col class="api-error-table-col-3">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <th>HTTP status</th>
                                        <th><code>error</code> Code</th>
                                        <th>Condition</th>
                                        <th>Details</th>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400101</td>
                                        <td>Unknown error</td>
                                        <td>
                                            <p>There was a problem downloading or querying this workbook.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403004</td>
                                        <td>Unauthorized</td>
                                        <td>
                                            <p>A non-administrator user attempted to download a pdf, but they don't have <span class="api-command-ref">Read</span> and/or <span class="api-command-ref">ExportImage</span> permissions for the workbook
								or user does not have <span class="api-command-ref">Read</span> permissions for the views of the workbook.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403105</td>
                                        <td>Unauthorized</td>
                                        <td>
                                            <p>The PDF export feature is disabled on the server or the server is not configured to allow PDF exports using the REST API.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404000</td>
                                        <td>Site not found</td>
                                        <td>The site ID  in the URI doesn't correspond to an existing site.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404006</td>
                                        <td>Workbook not found</td>
                                        <td>The workbook ID in the URI doesn't correspond to an existing workbook.</td>
                                    </tr>
                                    <tr>
                                        <td>405</td>
                                        <td>405000</td>
                                        <td>Invalid request method</td>
                                        <td>Request type was not <span class="api-command-ref">GET</span>.</td>
                                    </tr>
                                </tbody>
                            </table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### cURL Request Example

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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to use as the source of the <code>.pptx</code> file to be downloaded.</td></tr><tr><td><span class="api-placeholder">max-age-minutes</span></td><td>(Optional) The maximum number of minutes a workbook <code>.pptx</code> will be cached before being refreshed. To prevent multiple <code>.pptx</code> 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.</td></tr></tbody></table>

#### 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`.

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:workbooks:download
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

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

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

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

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

[Maintain a History of Revisions](https://help.tableau.com/current/server/en-us/help.htm#revision_history_maintain.htm) 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to download.</td></tr><tr><td><span class="api-placeholder">revision-number</span></td><td>The revision number of the workbook to download. To determine what versions are available, call <a href="#get_workbook_revisions">Get Workbook Revisions</a>. Note that the current revision of a workbook cannot be accessed by this call; use <a href="#download_workbook">Download Workbook</a> instead.</td></tr><tr><td><span class="api-placeholder">extract-value</span></td><td>(Optional) The <span class="api-placeholder">extract-value</span> is a Boolean value (<code>False</code> or <code>True</code>). When the workbook specified for download has an extract, if you add the parameter <code>?includeExtract=False</code>, 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.</td></tr></tbody></table>

#### 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
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>403</td><td>403053</td><td>Version history not enabled</td><td>version history is not enabled for the specified site.</td></tr><tr><td>403</td><td>403019</td><td>Read forbidden</td><td>A non-administrator user attempted to download a workbook, but the caller doesn't have required permissions.</td></tr><tr><td>404</td><td>404024</td><td>Workbook revision not found</td><td>The revision number in the URI doesn't correspond to an existing data source revision.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:content:read

- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-luid</span></td><td>The LUID for the site.</td></tr><tr><td><span class="api-placeholder">custom-view-luid</span></td><td>The LUID for the custom view being updated.</td></tr></tbody></table>

#### 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"
    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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad Request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized Access</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403162</td><td>Unauthorized Access</td><td>The user does not have adminstrator permissions or <b>Read</b> permissions for the custom view..</td></tr><tr><td>404</td><td>404008</td><td>Resource Not Found</td><td>A custom view with the requested LUID could not be found.</td></tr><tr><td>405</td><td>405000</td><td>Invalid Request Method</td><td>Request type was not GET.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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`

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

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 response 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views).

#### 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the view.</td></tr><tr><td><span class="api-placeholder">custom-view-luid</span></td><td>The ID of the view to render as data.</td></tr><tr><td><span class="api-placeholder">max-age-minutes</span></td><td>(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.</td></tr><tr><td><i>fieldname</i>=<i>filter-value</i></td><td>(Optional) An expression that applies a granular filter to the request. Returns will be based on the value (<i>filtervalue</i>) of the dimension or measure (<i>fieldname</i>) of your view data you specify. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views">View filter queries</a>.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request

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

<table class="api-error-table">
                                <colgroup>
                                    <col class="api-error-table-col-1">
                                    <col class="api-error-table-col-2">
                                    <col class="api-error-table-col-3">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <th>HTTP status</th>
                                        <th><code>error</code> Code</th>
                                        <th>Condition</th>
                                        <th>Details</th>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400080</td>
                                        <td>Bad Request</td>
                                        <td>The view ID in the URI doesn't correspond to a view available on the specified site.</td>
                                    </tr>
                                    <tr>
                                        <td>401</td>
                                        <td>401002</td>
                                        <td>Unauthorized</td>
                                        <td>The authentication token provided in the request header was invalid or has expired.</td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403032</td>
                                        <td>Read forbidden</td>
                                        <td>A non-administrator user attempted to get custok views, but the caller doesn't have <span class="api-command-ref">Read</span> or <span class="api-command-ref">Expot image</span>permission.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404000</td>
                                        <td>Site not found</td>
                                        <td>The site ID in the URI doesn't correspond to an existing site.</td>
                                    </tr>
                                    <tr>
                                        <td>405</td>
                                        <td>405000</td>
                                        <td>Invalid request method</td>
                                        <td>Request type was not <span class="api-command-ref">GET</span>.</td>
                                    </tr>
                                    <tr>
                                        <td>429</td>
                                        <td>429000</td>
                                        <td>Concurrent request limit exceeded</td>
                                        <td>
                                            <p>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.</p>
                                            <p>Introduced September 2021.</p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Get Custom View Image

Downloads an image file of the specified custom view.

**Version:** Available in API 3.18 (Tableau Cloud December 2022 / Server 2023.1). _[Version Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:views:download

- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

GET /api/api-version/sites/site-id/customviews/view-id/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_

Available in API 3.29 (Tableau Cloud June 2026 / Server 2026.2 and later:

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The LUID for the site.</td></tr><tr><td><span class="api-placeholder">view-id</span></td><td>The LUID for the custom view being updated.</td></tr><tr><td><span class="api-placeholder">image-resolution</span></td><td>(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 <code>high</code> to ensure maximum pixel density.</td></tr><tr><td><span class="api-placeholder">max-age-minutes</span></td><td>(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.</td></tr><tr><td><span class="api-placeholder">filter-value</span></td><td>The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter <code>/data?vf_year=2017</code> would only display data from the year 2017. To learn more, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views">View filter queries</a>.</td></tr><tr><td><span class="api-placeholder">image-format</span></td><td>(Optional) The format of the returned image. Valid values are <code>png</code> (default) or <code>svg</code>. Available in API 3.29 and later.</td></tr></tbody></table>

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

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad Request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized Access</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403162</td><td>Unauthorized Access</td><td>The user does not have adminstrator permissions or <b>Read</b> permissions for the custom view..</td></tr><tr><td>404</td><td>404008</td><td>Resource Not Found</td><td>A custom view with the requested LUID could not be found.</td></tr><tr><td>405</td><td>405000</td><td>Invalid Request Method</td><td>Request type was not GET.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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`

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views).

#### 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

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1-wide">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><span class="api-placeholder">api-version</span>
                                        </td>
                                        <td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">site-luid</span>
                                        </td>
                                        <td>The ID of the site that contains the view.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">custom-view-luid</span>
                                        </td>
                                        <td>The ID of the view to render as a .pdf file.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">viz-height</span>
                                        </td>
                                        <td>(Optional) The height of the rendered pdf image in pixels that, along with the value of <code>vizWidth</code>, determines its
							resolution and aspect ratio.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">viz-width</span>
                                        </td>
                                        <td>(Optional) The width of the rendered pdf image in pixels that, along with the value of <code>vizHeight</code>, determines its
				resolution and aspect ratio.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">max-age-minutes</span>
                                        </td>
                                        <td>(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.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">orientation</span>
                                        </td>
                                        <td>(Optional) The orientation of the pages in the .pdf file produced. The value can be
								<code>Portrait</code>
								or <code>Landscape</code>. If this parameter is not present the page orientation will default to <code>Portrait</code>.
							</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">page-type</span>
                                        </td>
                                        <td>
                                            <p>(Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be:
								<code>A3</code>,
								<code>A4</code>,
								<code>A5</code>,
								<code>B5</code>,
								<code>Executive</code>,
								<code>Folio</code>,
								<code>Ledger</code>,
								<code>Legal</code>,
								<code>Letter</code>,
								<code>Note</code>,
								<code>Quarto</code>,
								or <code>Tabloid</code>.</p>
                                            <p>If this parameter is not present the page type will default to <code>Legal</code>.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><i>fieldname</i>=<i>filter-value</i></td>
                                        <td>(Optional) An expression that applies a granular filter to the request. Returns will be based on the value (<i>filtervalue</i>) of the dimension or measure (<i>fieldname</i>) of your view data you specify. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views">View filter queries</a>.</td>
                                    </tr>
                                </tbody>
                            </table>

#### 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.29/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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400080</td><td>Bad Request</td><td>The view ID in the URI doesn't correspond to a view available on the specified site.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403032</td><td>Read forbidden</td><td>A non-administrator user attempted to query workbook views, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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`

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the group.</td></tr><tr><td><span class="api-placeholder">view-id</span></td><td>The ID of the view whose details are requested.</td></tr><tr><td>(Optional) <span class="api-placeholder">get-usage-information</span></td><td><span class="api-command-ref">true</span> to return usage statistics. The default is <span class="api-command-ref">false</span>.</td></tr></tbody></table>

#### 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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Resource not found</td><td>The view ID in the URI doesn't correspond to an existing view.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### cURL Example

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

**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`

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the group.</td></tr><tr><td><span class="api-placeholder">view-name</span></td><td>The name of the view as it appears in the URL to the view. For <code>https://MY_SERVER/#/MY_SITE/views/workbook-name/Sheet1?:iid=1</code>, the name would be <code>Sheet1</code>.</td></tr></tbody></table>

#### 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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Resource not found</td><td>The view ID in the URI doesn't correspond to an existing view.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### cURL Example

```
curl "http://MY-SERVER/api/3.29/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 - Deprecated in API 3.19

Gets a list of views that are recommended for a user.

> [!WARNING]
> 
> Starting in API version 3.19 (Tableau Server 2023.1 / Cloud March 2023), this method is deprecated, will no longer be supported, and may be retired in future releases.

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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The LUID of the site that contains the group.</td></tr></tbody></table>

#### Request Body

None

#### Permissions

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:recommendations:read
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook that downgrade info is being shown for.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook being downgraded.</td></tr><tr><td><span class="api-placeholder">downgrade-target-version</span></td><td>The Tableau release version number the workbook is being downgraded to.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:workbook_downgrade_info:read
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400114</td><td>Unknown downgrade error</td><td>The workbook cannot be exported to a downgraded version due to an unknown error.</td></tr><tr><td>400</td><td>400115</td><td>Invalid downgrade version</td><td>The downgrade version specified is not a valid Tableau version number.</td></tr><tr><td>400</td><td>400116</td><td>Downgrade version not supported</td><td>The downgrade version specified refers to a Tableau version that is not supported.</td></tr><tr><td>403</td><td>40310</td><td>Access to downgrade info denied</td><td>The caller does not have permissions required to access download info for this workbook.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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](#download_workbook_revision) method. For more information, see [Maintain a History of Revisions](https://help.tableau.com/current/server/en-us/help.htm#revision_history_maintain.htm) 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook to get revisions for.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to get revisions for.</td></tr><tr><td><span class="api-placeholder">page-size</span></td><td>(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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr><tr><td><span class="api-placeholder">page-number</span></td><td>(Optional) The offset for paging. The default is 1. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:content:read
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](#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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table">
                                <colgroup>
                                    <col class="api-error-table-col-1">
                                    <col class="api-error-table-col-2">
                                    <col class="api-error-table-col-3">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <th>HTTP status</th>
                                        <th><code>error</code> Code</th>
                                        <th>Condition</th>
                                        <th>Details</th>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400006</td>
                                        <td>Invalid page number</td>
                                        <td>
                                    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.
                                </td>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400007</td>
                                        <td>Invalid page size</td>
                                        <td>The page size parameter is not an integer, or is less than one.</td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403014</td>
                                        <td>Page size limit exceeded</td>
                                        <td>The specified page size is larger than the maximum page size.</td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403053</td>
                                        <td>Version history not enabled</td>
                                        <td>version history is not enabled for the specified site.</td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403056</td>
                                        <td>A non-administrator user attempted to get workbook revision information, but the caller doesn't have sufficient permissions.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404000</td>
                                        <td>Site not found</td>
                                        <td>The site ID in the URI doesn't correspond to an existing site.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404006</td>
                                        <td>Workbook not found</td>
                                        <td>The workbook ID in the URI doesn't correspond to an existing workbook.</td>
                                    </tr>
                                    <tr>
                                        <td>405</td>
                                        <td>405000</td>
                                        <td>Invalid request method</td>
                                        <td>Request type was not <span class="api-command-ref">GET</span>.</td>
                                    </tr>
                                </tbody>
                            </table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Hide a Recommendation for a View - Deprecated in API 3.19

Hides a view from being recommended by the server by adding it to a list of views that are dismissed for a user.

> [!WARNING]
> 
> Starting in API version 3.19 (Tableau Server 2023.1 / Cloud March 2023), this method is deprecated, will no longer be supported, and may be retired in future releases.

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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the group.</td></tr></tbody></table>

#### Request Body

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

#### Request Parameters

<table class="api-parameters-table"><colgroup><col style="width:27%;"> <col></colgroup><tbody><tr><td><span class="api-placeholder">view-luid</span></td><td>The LUID of the view to be added to the list of views hidden from recommendation for a user.</td></tr></tbody></table>

#### Permissions

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:recommendation_dismissals:update
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### Response Code

200

#### Response Body

None

#### Version

Version 1.0 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404029</td><td>Content not found</td><td>The content ID in the URI doesn't correspond to an existing content of the requested type.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">PUT</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

```
curl "http://MY-SERVER/api/3.29/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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**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](#list_custom_views_permissions)_ .  _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:content:read

- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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

<table class="api-parameters-table">
                            <colgroup>
                                <col class="api-parameters-table-col-1-wide">
                                <col>
                            </colgroup>
                            <tbody>
                                <tr>
                                    <td><span class="api-placeholder">api-version</span>
                                    </td>
                                    <td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.
						</td>
                                </tr>
                                <tr>
                                    <td><span class="api-placeholder">site-luid</span>
                                    </td>
                                    <td>The LUID for the site.</td>
                                </tr>
                                <tr>
                                    <td><span class="api-placeholder">page-size</span>
                                    </td>
                                    <td>(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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.
						</td>
                                </tr>
                                <tr>
                                    <td><span class="api-placeholder">page-number</span>
                                    </td>
                                    <td>(Optional) The offset for paging. The default is 1. For more information, see
							<a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.
						</td>
                                </tr>
                                <tr>
                                    <td><span class="api-placeholder">field-expression</span>
                                    </td>
                                    <td>
                                        <p>(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:</p>
                                        <p><code>?field=id</code>
                                        </p>
                                        <p>You can qualify the expression to return values based upon predefined keywords such as <code>_default_</code>,
								which returns only default values, and <code>_all_</code>, 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.</p>
                                        <p>The supported fields for custom views are its attributes:
							<code>id</code>, <code>name</code>, <code>createdAt</code>, <code>updatedAt</code>, and <code>shared</code>.</p>
                                        <p>For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_fields.htm">Using Fields in the REST API</a>.</p>
                                    </td>
                                </tr>
                                <tr>
                                    <td><span class="api-placeholder">filter-expression</span>
                                    </td>
                                    <td>
                                        <p>(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:</p>
                                        <p><code>?filter=createdAt:gt:2016-08-26T18:00:33Z</code> <i>(where <code>gt</code> is the greater-than operator)</i></p>
                                        <p>You can include multiple filter expressions in a request, and mix field, sort,
							and filter expressions in the same request.</p>
                                        <p>The supported filters for custom views use the <code>eq</code> (equals) operator, with the resources:
							<code>viewId</code>, <code>ownerId</code>, and <code>workbookId</code>.</p>
                                        <p>For more information, see
								<a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm">Filtering and Sorting in the Tableau REST API</a>.</p>
                                    </td>
                                </tr>
                                <tr>
                                    <td><span class="api-placeholder">sort-expression</span>
                                    </td>
                                    <td>
                                        <p>(Optional) An expression that lets you sort the Tableau resources present in the response. A sort expression contains
								an attribute name and a direction (<code>asc</code> or <code>desc</code>). For example, a sort expression that sorts
								the requested resource by creation date with the latest date first would look like:</p>
                                        <p><code>?sort=createdAt:desc</code>
                                        </p>
                                        <p>You can include multiple sort expressions in a request, and mix field, sort,
							and filter expressions in the same request.</p>
                                        <p>The supported filters for custom views use the <code>eq</code> (equals) operator, with the resources:
							<code>viewId</code>, <code>ownerId</code>, and <code>workbookId</code>.</p>
                                        <p>For more information, see
								<a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm">Filtering and Sorting in the Tableau REST API</a>.</p>
                                    </td>
                                </tr>
                            </tbody>
                        </table>

#### Request Body

None.

#### Required scope for JWT authorization

_Introduced in Tableau Server 2022.3 (API 3.17)._

Authorize use of this method by including this scope in the JSON Web Token (JWT). For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) see [Access Scopes for Connected Apps](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) in the Tableau Server Help.

`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](https://help.tableau.com/current/server/en-us/user_visibility.htm) 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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad Request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized Access</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403162</td><td>Unauthorized Access</td><td>The user does not have adminstrator permissions or <b>Read</b> permissions for the custom view..</td></tr><tr><td>405</td><td>405000</td><td>Invalid Request Method</td><td>Request type was not GET.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**License:** No additional license required.

**Permissions:** Only Tableau administrators can list users whose default view is the specified custom view.  _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:content:read

- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-luid</span></td><td>The LUID for the site.</td></tr><tr><td><span class="api-placeholder">custom-view-luid</span></td><td>The LUID for the custom view being updated.</td></tr></tbody></table>

#### 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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad Request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized Access</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403162</td><td>Unauthorized Access</td><td>The user does not have adminstrator permissions.</td></tr><tr><td>404</td><td>404008</td><td>Resource Not Found</td><td>A custom view with the requested LUID could not be found.</td></tr><tr><td>405</td><td>405000</td><td>Invalid Request Method</td><td>Request type was not GET.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Publish Workbook

Publishes a workbook on the specified site.

To make changes to a published workbook, call [Update Workbook](#update_workbook) or [Update Workbook Connection](#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`

For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_publishing.htm#initiate_file_upload), send portions of the file to the server using [Append to File Upload](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_publishing.htm#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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_publish.htm).

#### 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-extra-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site to publish to.</td></tr><tr><td><span class="api-placeholder">overwrite-flag</span></td><td>(Optional) <span class="api-command-ref">true</span> to overwrite a workbook that has the same name, or <span class="api-command-ref">false</span> to fail if the specified workbook already exists. The default is <span class="api-command-ref">false</span>. If <span class="api-placeholder">overwrite-flag</span> is set to <span class="api-command-ref">true</span> but the workbook doesn't already exist, the operation succeeds.</td></tr><tr><td><span class="api-placeholder">asJob-value</span></td><td>(Optional, boolean) If <code>false</code>, 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 <i>true</i>, 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 <a href="#query_job">Query Job</a>. Default value is <code>false</code>.</td></tr><tr><td><span class="api-placeholder">skip-connection-check-flag</span></td><td>(Optional, boolean) If <code>true</code>, 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 <a href="https://help.tableau.com/current/online/en-us/to_keep_data_fresh.htm" rel="noopener" target="_blank">Keep Data Fresh guidelines</a>. Default value is <code>false</code>.</td></tr><tr><td><span class="api-placeholder">upload-session-id</span></td><td>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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_publishing.htm#initiate_file_upload"><span class="api-command-ref">Initiate File Upload</span></a>. If this value is not included, the server assumes that the body of the request contains the file to be published.</td></tr><tr><td><span class="api-placeholder">workbook-file-type</span></td><td><span class="api-command-ref">twb</span> or <span class="api-command-ref">twbx</span> to indicate whether you have uploaded a workbook file (twb) or a packaged workbook file (twbx). This value is required if you are calling <span class="api-command-ref">Publish Workbook</span> in order to commit a file that was previously uploaded using <span class="api-command-ref">Append to File Upload</span>. The value is not used if you upload a file in the body of the request.</td></tr></tbody></table>

#### 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"
          oAuth="oauth-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

<table class="api-parameters-table">
                        <colgroup>
                            <col class="api-parameters-table-col-1-wide">
                            <col>
                        </colgroup>
                        <tbody>
                            <tr>
                                <td><span class="api-placeholder">boundary-string</span>
                                </td>
                                <td>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:
                                        <p><code>Content-type: multipart/mixed; boundary=<span class="api-placeholder">boundary-string</span></code></p></td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">workbook-name</span>
                                </td>
                                <td>The name to assign to the workbook when it is saved on the server.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">workbook-description</span>
                                </td>
                                <td>(Optional) Starting in API&nbsp;3.20, the description for the workbook.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">show-tabs-flag</span>
                                </td>
                                <td>(Optional) Specify <span class="api-command-ref">true</span> to have the published workbook show views in tabs; otherwise, <span class="api-command-ref">false</span>. The default is <span class="api-command-ref">false</span>.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">user-luid</span>
                                </td>
                                <td>(Optional) The LUID of the user to generate thumbnails as. You can get the user LUID by calling <a href="#get_users_on_site">Get Users on Site</a>.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">server-address</span>
                                </td>
                                <td>(Optional) Specify the server address for a data source connection if that data source does not use OAuth.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">port-number</span>
                                </td>
                                <td>(Optional) Specify the port number for a data source connection if that data source does not use OAuth.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">connection-username</span>
                                </td>
                                <td>(Optional) If the workbook's data source connections require credentials, the
								    <span class="api-command-ref">&lt;connectionCredentials&gt;</span> 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.<p>If your auth type allows secrets to be passed as generic username and password variables, use this attribute for the appropriate secret, such as client id. (Example auth types include 2-legged OAuth, like Service Principal OAuth with Databricks and Client Credentials OAuth with Snowflake.)</p><p><b>Note:</b> 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.</p></td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">connection-password</span>
                                </td>
                                <td>(Optional) If the workbook's data source connections require credentials, the
									<span class="api-command-ref">&lt;connectionCredentials&gt;</span> 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.<p>If your auth type allows secrets to be passed as generic username and password variables, use this attribute for the appropriate secret, such as client secret. (Example auth types include 2-legged OAuth, like Service Principal OAuth with Databricks and Client Credentials OAuth with Snowflake.)</p><p><b>Note:</b> 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.</p></td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">embed-flag</span>
                                </td>
                                <td>(Optional) If the workbook's data source connection requires credentials, the <span class="api-command-ref">&lt;connectionCredentials&gt;</span> element is included.
                                        Setting this attribute to <span class="api-command-ref">true</span> instructs the server to save the credentials for when the data source is used.
                                    </td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">oauth-flag</span>
                                </td>
                                <td>(Optional) If the workbook's data source connection is configured to use OAuth, set this to <code>true</code> to specify that the value of the <span class="api-command-ref">name</span> attribute
                                    in the <span class="api-command-ref">&lt;connectionCredentials&gt;</span> element is an
                                        OAuth username. In that case, no password is required and the value of the <span class="api-command-ref">embed</span> attribute specifies
                                        whether to embed the OAuth credential with the workbook, and the server address and port number are not required.<p>If your auth type allows secrets to be passed as generic username and password variables, set the <span class="api-command-ref">oAuth</span> attribute to <code>false</code>. (Example auth types include 2-legged OAuth, like Service Principal OAuth with Databricks and Client Credentials OAuth with Snowflake.)</p><p>For more information on OAuth, see the OAuth Connections section of the <a href="https://help.tableau.com/current/online/en-us/protected_auth.htm" target="_blank">Tableau Cloud</a> or <a href="https://help.tableau.com/current/server/en-us/protected_auth.htm" target="_blank">Tableau Server</a> Product Help.

                                    </p></td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">hide-view-flag</span>
                                </td>
                                <td>Setting this flag to <code>true</code> will cause the named view to be hidden in the published workbook. The default value is <code>false</code>.
							You can specify any number of views to hide. If all views in a workbook are hidden the server will not perform a publish.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">project-id</span>
                                </td>
                                <td>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.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">workbook-file-name</span>
                                </td>
                                <td>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.
                                    </td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">content-of-workbook-file</span>
                                </td>
                                <td>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&nbsp;MB.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">encryptExtracts</span>
                                </td>
                                <td>(Optional) <b>true</b> to encrypt the extracts or <b>false</b> to not encrypt extracts. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm" class="xref">Extract and Encryption Methods</a>.</td>
                            </tr>
                        </tbody>
                    </table>

#### 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.29/sites/site-id/workbooks/workbook-id

#### Errors

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

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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`

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-extra-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code>2.2</code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the views.</td></tr><tr><td><span class="api-placeholder">get-usage-information</span></td><td>(Optional) <span class="api-command-ref">true</span> to return usage statistics. The default is <span class="api-command-ref">false</span>.</td></tr><tr><td><span class="api-placeholder">page-size</span></td><td>(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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr><tr><td><span class="api-placeholder">page-number</span></td><td>(Optional) The offset for paging. The default is 1. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr><tr><td><span class="api-placeholder">filter-expression</span></td><td>(Optional) Fields and operators that you can use to filter results. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#filter_expressions" class="xref">Filter expressions</a>.</td></tr><tr><td><span class="api-placeholder">sort-expression</span></td><td>(Optional) Field and direction to sort results. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#sort_expressions" class="xref">Sorting</a>.</td></tr><tr><td><span class="api-placeholder">field-expression</span></td><td>(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 <code>_all_</code> or <code>_default_</code>, 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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_fields.htm">Using Fields in the REST API</a>.</td></tr></tbody></table>

**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.29/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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400006</td><td>Invalid page number</td><td>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.</td></tr><tr><td>400</td><td>400007</td><td>Invalid page size</td><td>The page size parameter is not an integer, or is less than one.</td></tr><tr><td>400</td><td>400008</td><td>Invalid parameter value</td><td>The <span class="api-command-ref">includeUsageStatistics</span> was provided with a value other than <span class="api-command-ref">true</span> or <span class="api-command-ref">false</span>.</td></tr><tr><td>403</td><td>403004</td><td>Read forbidden</td><td>A non-administrator user attempted to query workbook views, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>403</td><td>403014</td><td>Page size limit exceeded</td><td>The specified page size is larger than the maximum page size.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-extra-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to get the views for.</td></tr><tr><td>(Optional) <span class="api-placeholder">get-usage-information</span></td><td><span class="api-command-ref">true</span> to return usage statistics. The default is <span class="api-command-ref">false</span>.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:content:read
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400008</td><td>Invalid parameter value</td><td>The <span class="api-command-ref">includeUsageStatistics</span> was provided with a value other than <span class="api-command-ref">true</span> or <span class="api-command-ref">false</span>.</td></tr><tr><td>403</td><td>403004</td><td>Read forbidden</td><td>A non-administrator user attempted to query workbook views, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

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

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

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.

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 response 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views).

#### 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the view.</td></tr><tr><td><span class="api-placeholder">view-id</span></td><td>The ID of the view to render as data.</td></tr><tr><td><span class="api-placeholder">max-age-minutes</span></td><td>(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.</td></tr><tr><td><span class="api-placeholder">filter-value</span></td><td>The value of the field that you want to use to filter the workbook view. For example, a workbook with the filter <code>/data?vf_year=2017</code> would only display data from the year 2017. To learn more, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views">View filter queries</a>.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request

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

<table class="api-error-table">
                                <colgroup>
                                    <col class="api-error-table-col-1">
                                    <col class="api-error-table-col-2">
                                    <col class="api-error-table-col-3">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <th>HTTP status</th>
                                        <th><code>error</code> Code</th>
                                        <th>Condition</th>
                                        <th>Details</th>
                                    </tr>
                                    <tr>
                                        <td>400</td>
                                        <td>400080</td>
                                        <td>Bad Request</td>
                                        <td>The view ID in the URI doesn't correspond to a view available on the specified site.</td>
                                    </tr>
                                    <tr>
                                        <td>401</td>
                                        <td>401002</td>
                                        <td>Unauthorized</td>
                                        <td>The authentication token provided in the request header was invalid or has expired.</td>
                                    </tr>
                                    <tr>
                                        <td>403</td>
                                        <td>403032</td>
                                        <td>Read forbidden</td>
                                        <td>A non-administrator user attempted to query workbook views, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td>
                                    </tr>
                                    <tr>
                                        <td>404</td>
                                        <td>404000</td>
                                        <td>Site not found</td>
                                        <td>The site ID in the URI doesn't correspond to an existing site.</td>
                                    </tr>
                                    <tr>
                                        <td>405</td>
                                        <td>405000</td>
                                        <td>Invalid request method</td>
                                        <td>Request type was not <span class="api-command-ref">GET</span>.</td>
                                    </tr>
                                    <tr>
                                        <td>429</td>
                                        <td>429000</td>
                                        <td>Concurrent request limit exceeded</td>
                                        <td>
                                            <p>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.</p>
                                            <p>Introduced September 2021.</p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Query View Image

Downloads an image file 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`

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views).

**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](https://help.tableau.com/current/server/en-us/cli_configuration-set_tsm.htm) 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

Available in API 3.29 (Tableau Cloud June 2026 / Server 2026.2 and later:

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

#### Parameter Values

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1-wide">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><span class="api-placeholder">api-version</span>
                                        </td>
                                        <td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">site-id</span>
                                        </td>
                                        <td>The ID of the site that contains the view.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">view-id</span>
                                        </td>
                                        <td>The ID of the view to return an image for.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">viz-height</span>
                                        </td>
                                        <td>
                                            <p><span style="font-weight: normal;font-style: italic;"> Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later:</span>&nbsp;</p>
                                            <p>(Optional) The height of the rendered pdf image in pixels that, along with the value of <code>vizWidth</code> determine its
							resolution and aspect ratio.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">viz-width</span>
                                        </td>
                                        <td>
                                            <p><span style="font-weight: normal;font-style: italic;"> Available in API 3.23 (Tableau Cloud December 2024 / Server 2024.3) and later:</span>
                                            </p>
                                            <p>(Optional) The width of the rendered pdf image in pixels that, along with the value of <code>vizHeight</code> determine its
							resolution and aspect ratio.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">image-resolution</span>
                                        </td>
                                        <td>(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 <code>high</code> to ensure maximum pixel density.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">max-age-minutes</span>
                                        </td>
                                        <td>(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.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">filter-value</span>
                                        </td>
                                        <td>The value of the field that you want to use to filter the workbook view.
										For example, a workbook with the filter <code>/data?vf_year=2017</code> would only display data from the year 2017.
									To learn more, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views">View filter queries</a>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">image-format</span>
                                        </td>
                                        <td>(Optional) The format of the returned image. Valid values are <code>png</code> (default) or <code>svg</code>. Available in API 3.29 and later.</td>
                                    </tr>
                                </tbody>
                            </table>

#### Request Body

None

#### Response Code

200

#### Response Body

The response `Content-Type` header changes based on the `image-format` parameter:

- Default/PNG: `image/png`
- SVG: `image/svg+xml`

#### cURL Request Example

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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400010</td><td>Bad request</td><td>Invalid query parameter. For example, attempting to query 'jpg' <code>image-format</code>.</td></tr><tr><td>403</td><td>403004</td><td>Read forbidden</td><td>A non-administrator user attempted to query a view preview image, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>403</td><td>403068</td><td>Forbidden</td><td>The endpoint has been disabled on the server. To enable the endpoint, a server administrator must use tsm to configure the <code>sheet_image.enabled</code> setting. For more information, see <a href="https://help.tableau.com/current/server/en-us/cli_configuration-set_tsm.htm">tsm configuration set Options</a> in the Tableau Server help.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>404</td><td>404011</td><td>View not found</td><td>The view ID in the URI doesn't correspond to an existing view in the specified workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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`

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views).

#### 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

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1-wide">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><span class="api-placeholder">api-version</span>
                                        </td>
                                        <td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">site-id</span>
                                        </td>
                                        <td>The ID of the site that contains the view.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">view-id</span>
                                        </td>
                                        <td>The ID of the view to render as a .pdf file.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">filter-value</span>
                                        </td>
                                        <td>The value of the field that you want to use to filter the workbook view.
									For example, a workbook with the filter <code>/data?vf_year=2017</code> would only display data from the year 2017.
									To learn more, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm#Filter-query-views">View filter queries</a>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">viz-height</span>
                                        </td>
                                        <td>(Optional) The height of the rendered pdf image in pixels that, along with the value of <code>vizWidth</code>, determines its
							resolution and aspect ratio.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">viz-width</span>
                                        </td>
                                        <td>(Optional) The width of the rendered pdf image in pixels that, along with the value of <code>vizHeight</code>, determines its
				resolution and aspect ratio.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">max-age-minutes</span>
                                        </td>
                                        <td>(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.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">orientation</span>
                                        </td>
                                        <td>(Optional) The orientation of the pages in the .pdf file produced. The value can be
								<code>Portrait</code>
								or <code>Landscape</code>. If this parameter is not present the page orientation will default to <code>Portrait</code>.
							</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">page-type</span>
                                        </td>
                                        <td>
                                            <p>(Optional) The type of page, which determines the page dimensions of the .pdf file returned. The value can be:
								<code>A3</code>,
								<code>A4</code>,
								<code>A5</code>,
								<code>B5</code>,
								<code>Executive</code>,
								<code>Folio</code>,
								<code>Ledger</code>,
								<code>Legal</code>,
								<code>Letter</code>,
								<code>Note</code>,
								<code>Quarto</code>,
								or <code>Tabloid</code>.</p>
                                            <p>If this parameter is not present the page type will default to <code>Legal</code>.</p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

#### 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.29/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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400080</td><td>Bad Request</td><td>The view ID in the URI doesn't correspond to a view available on the specified site.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403032</td><td>Read forbidden</td><td>A non-administrator user attempted to query workbook views, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the view.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook that contains the view to return a thumbnail image for.</td></tr><tr><td><span class="api-placeholder">view-id</span></td><td>The ID of the view to return a thumbnail image for.</td></tr></tbody></table>

#### 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
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>403</td><td>403004</td><td>Read forbidden</td><td>A non-administrator user attempted to query a view preview image, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>404</td><td>404011</td><td>View not found</td><td>The view ID in the URI doesn't correspond to an existing view in the specified workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:content:read

- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1-wide">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><span class="api-placeholder">api-version</span>
                                        </td>
                                        <td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">site-id</span>
                                        </td>
                                        <td>The ID of the site that contains the workbook.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">content-url</span>
                                        </td>
                                        <td>
                                            <p>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.</p>
                                            <p><code>mySite</code> is the content URL in the following example:</p>
                                            <p><code>http://&lt;server or cloud URL&gt;/#/site/<strong>mySite</strong>/explore</code>
                                            </p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

#### 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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>403</td><td>403018</td><td>Read forbidden</td><td>A non-administrator user attempted to query the workbook, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook LUID or contentUrl in the URI doesn't correspond to an existing workbook, or the querystring <code>?key=contentUrl</code> is not capitalized correctly.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbooks.</td></tr><tr><td><span class="api-placeholder">filter-expression</span></td><td>(Optional) An expression that lets you specify a subset of workbooks to return. You can filter on predefined fields such as <code>name</code>, <code>tags</code>, and <code>createdAt</code>. You can include multiple filter expressions. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm">Filtering and Sorting</a>.</td></tr><tr><td><span class="api-placeholder">sort-expression</span></td><td>(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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm">Filtering and Sorting</a>.</td></tr><tr><td><span class="api-placeholder">page-size</span></td><td>(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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr><tr><td><span class="api-placeholder">page-number</span></td><td>(Optional) The offset for paging. The default is 1. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr><tr><td><span class="api-placeholder">field-expression</span></td><td>(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 <code>_all_</code> or <code>_default_</code>, 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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_fields.htm">Using Fields in the REST API</a>.</td></tr></tbody></table>

**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
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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

<table class="api-parameters-table">
                                <colgroup>
                                    <col style="width:27%;">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><span class="api-placeholder">accelerationEnabled</span>
                                        </td>
                                        <td><span class="api-command-ref">true</span> if data acceleration is enabled, otherwise  <span class="api-command-ref">false</span>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_data_acceleration.htm" class="xref">Data Acceleration (Retired)</a>.
								<i>Tableau's View Acceleration feature and Data Acceleration-related APIs were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.</i></td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">accelerationStatus</span>
                                        </td>
                                        <td>The status can be:<ul><li><span class="api-command-ref">accelerated</span>: The acceleration job succeeded.
									</li><li><span class="api-command-ref">failed</span>: The acceleration job failed.
									</li><li><span class="api-command-ref">inProgress</span>: The acceleration job is running.
									</li><li><span class="api-command-ref">notUseful</span>: The acceleration job completed but none of the queries in the workbook were supported for acceleration.
									</li><li><span class="api-command-ref">waiting</span>: The workbook is enabled for acceleration but no background job has been submitted yet to accelerate it.
								</li></ul><i>Tableau's View Acceleration feature and Data Acceleration-related APIs were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.</i></td>
                                    </tr>
                                </tbody>
                            </table>

#### Version

Version 2.3 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400006</td><td>Invalid page number</td><td>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.</td></tr><tr><td>400</td><td>400007</td><td>Invalid page size</td><td>The page size parameter is not an integer, or is less than one.</td></tr><tr><td>403</td><td>403014</td><td>Page size exceeds upper limit</td><td>The page size parameter exceeds the system-wide upper limit of 1000.</td></tr><tr><td>403</td><td>403018</td><td>Read forbidden</td><td>A non-administrator user attempted to query workbooks for the site, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example: Get workbooks without filter

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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the user.</td></tr><tr><td><span class="api-placeholder">user-id</span></td><td>The ID of the user to get workbooks for.</td></tr><tr><td><span class="api-placeholder">isOwner</span></td><td>(Optional) <span class="api-command-ref">true</span> to return only workbooks that the specified user owns, or <span class="api-command-ref">false</span> to return all workbooks that the specified user has at least read access to. The default is <span class="api-command-ref">false</span>.</td></tr><tr><td><span class="api-placeholder">page-size</span></td><td>(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 <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr><tr><td><span class="api-placeholder">page-number</span></td><td>(Optional) The offset for paging. The default is 1. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:content:read
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400006</td><td>Invalid page number</td><td>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.</td></tr><tr><td>400</td><td>400007</td><td>Invalid page size</td><td>The page size parameter is not an integer, or is less than one.</td></tr><tr><td>403</td><td>403014</td><td>Page size exceeds upper limit</td><td>The page size parameter exceeds the system-wide upper limit of 1000.</td></tr><tr><td>403</td><td>403018</td><td>Read forbidden</td><td>A non-administrator user attempted to query workbooks for the user, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404002</td><td>User not found</td><td>The user ID in the URI doesn't correspond to an existing user.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to return connection information about.</td></tr></tbody></table>

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:content:read
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>403</td><td>403021</td><td>Read forbidden</td><td>A user who is not a server administrator user attempted to query the workbook connections, but the caller doesn't have <span class="api-command-ref">Read</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

`curl "http://MY-SERVER/api/3.29/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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_connectiontype.htm) 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to return the thumbnail image for.</td></tr></tbody></table>

#### 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
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>403</td><td>403004</td><td>Read forbidden</td><td>A non-administrator user attempted to query the workbook preview image, but the caller doesn't have <span class="api-command-ref">Read</span> permission for the workbook.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">GET</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

`curl "http://MY-SERVER/api/3.29/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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**License:** No additional license required.

**Permissions:** Only Tableau administrators can set a custom view as the default view for users. _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:views:update

- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-luid</span></td><td>The LUID for the site.</td></tr><tr><td><span class="api-placeholder">custom-view-luid</span></td><td>The LUID for the custom view being updated.</td></tr></tbody></table>

#### 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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad Request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized Access</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403162</td><td>Unauthorized Access</td><td>The user does not have adminstrator permissions.</td></tr><tr><td>404</td><td>404008</td><td>Resource Not Found</td><td>A custom view with the requested LUID could not be found.</td></tr><tr><td>405</td><td>405000</td><td>Invalid Request Method</td><td>Request type was not GET.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Unhide a Recommendation for a View - Deprecated in API 3.19

Unhides a view from being recommended by the server by removing it from the list of views that are dimissed for a user.

> [!WARNING]
> 
> Starting in API version 3.19 (Tableau Server 2023.1 / Cloud March 2023), this method is deprecated, will no longer be supported, and may be retired in future releases.

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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the group.</td></tr><tr><td><span class="api-placeholder">view-luid</span></td><td>The LUID of the view to be removed from the list of views hidden from recommendation for a user.</td></tr></tbody></table>

#### Request Body

None

#### Permissions

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

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:recommendation_dismissals:delete
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### Response Code

204

#### Response Body

None

#### Version

Version 1.0 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404029</td><td>Content not found</td><td>The content ID in the URI doesn't correspond to an existing content of the requested type.</td></tr><tr><td>404</td><td>404035</td><td>Recommendation not found</td><td>A hidden recommendation for the given content ID was not found.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">DELETE</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

`curl "http://MY-SERVER/api/3.29/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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:views:update

- Scope added in API 3.18 (Tableau Cloud December 2022 / Tableau Server 2023.1).
- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-luid</span></td><td>The LUID for the site.</td></tr><tr><td><span class="api-placeholder">custom-view-luid</span></td><td>The LUID for the custom view being updated.</td></tr></tbody></table>

#### 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1"> <col></colgroup><tbody><tr><td><code>customView name</code></td><td>(Optional) <i>string</i> The new name of the custom view that replaces the existing one.</td></tr><tr><td><code>owner id</code></td><td>(Optional) <i>LUID</i> The LUID of the new owner of custom view that replaces the existing one.</td></tr></tbody></table>

#### 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

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad Request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized Access</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403162</td><td>Unauthorized Access</td><td>The user does not have adminstrator permissions or <b>Read</b> permissions for the custom view..</td></tr><tr><td>404</td><td>404008</td><td>Resource Not Found</td><td>A custom view with the requested LUID could not be found.</td></tr><tr><td>405</td><td>405000</td><td>Invalid Request Method</td><td>Request type was not GET.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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](https://help.tableau.com/current/online/en-us/data_freshness_policy.htm) for a workbook, and enable [View Acceleration](https://help.tableau.com/current/online/en-us/data_acceleration.htm) 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](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**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](https://help.tableau.com/current/server/en-us/data_acceleration.htm). Both administrators and workbook owners can change dataFreshnessPolicy settings.  _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope:** tableau:workbooks:update

- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to update.</td></tr><tr><td><span class="api-placeholder">include-view-acceleration-status-flag</span></td><td><i>Query parameter is optional. Boolean:</i> If <code>includeViewAccelerationStatus=true</code> then the list of views and the acceleration status of each view will be returned.</td></tr></tbody></table>

#### 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](https://help.tableau.com/current/online/en-us/data_freshness_policy.htm) and [View Acceleration](https://help.tableau.com/current/server/en-us/data_acceleration.htm):

- Data Freshness Policy and View Acceleration are independent features.
- If a policy is set without view acceleration for a workbook, then only [query caching](https://help.tableau.com/current/online/en-us/data_freshness_policy.htm#understand-data-freshness-for-query-caches) 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

<table class="api-parameters-table">
                                <colgroup>
                                    <col style="column-width: 30;width: 212px;">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><code>workbook name</code>
                                        </td>
                                        <td>(Optional) New name for the workbook being updated.</td>
                                    </tr>
                                    <tr>
                                        <td><code>workbook showTabs</code>
                                        </td>
                                        <td>(Optional) Specify <span class="api-command-ref">true</span> to have the updated workbook show views in tabs; otherwise,
								<span class="api-command-ref">false</span>. The default is <span class="api-command-ref">false</span>.</td>
                                    </tr>
                                    <tr>
                                        <td><code>workbook recentlyViewed</code>
                                        </td>
                                        <td>(Optional) Set this value to <span class="api-command-ref">true</span> to have the updated workbook show in the site's recently viewed list.
								The default is <span class="api-command-ref">false</span>. Once the flag is set to <span class="api-command-ref">true</span>, setting it to
								<span class="api-command-ref">false</span> 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 <span class="api-command-ref">recently-viewed-flag</span> will revert to <span class="api-command-ref">false</span>.</td>
                                    </tr>
                                    <tr>
                                        <td><code>workbook encryptExtracts</code>
                                        </td>
                                        <td>(Optional) <b>true</b> to encrypt the extracts or <b>false</b> to not encrypt extracts. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm" class="xref">Extract and Encryption Methods</a>.</td>
                                    </tr>
                                    <tr>
                                        <td><code>workbook description</code>
                                        </td>
                                        <td>(Optional) Starting in API&nbsp;3.20, the new description for the updated workbook.</td>
                                    </tr>
                                    <tr>
                                        <td><code>project id</code>
                                        </td>
                                        <td>(Optional) The LUID of a project to assign the workbook to.</td>
                                    </tr>
                                    <tr>
                                        <td><code>owner id</code>
                                        </td>
                                        <td>(Optional) The LUID of a user to assign the workbook to as owner.</td>
                                    </tr>
                                    <tr>
                                        <td><code>dataAccelerationConfig accelerationEnable</code>
                                        </td>
                                        <td>(Optional) Boolean: If <code>true</code>, accelerate the specified view(s). Default is <code>false</code>. <i>Tableau's View Acceleration feature and Data Acceleration-related APIs were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.</i></td>
                                    </tr>
                                    <tr>
                                        <td><code>dataAccelerationConfig accelerateNow</code>
                                        </td>
                                        <td>
                                            <p>
								(Optional) Boolean: If <code>true</code>, make view acceleration available as soon as possible.
								Default is <code>false</code>. <i>Tableau's View Acceleration feature and Data Acceleration-related APIs were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.</i></p>
                                            <p>
                                Note, the <code>view</code> object in the response (visible by using the <code>?includeViewAccelerationStatus=true</code>
                                query parameter) contains the <code>accelerationStatus</code> attribute, which can have the following values:
                                </p>
                                            <ul>
                                                <li><code>Off</code> - Accelerate now is not enabled.</li>
                                                <li><code>Pending</code> - Accelerate now is enabled, but backgrounder processes
                                        are still running to make the acceleration available.</li>
                                                <li><code>On</code> Acceleration is enabled.</li>
                                            </ul>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><code>view id</code>
                                        </td>
                                        <td>(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.</td>
                                    </tr>
                                    <tr>
                                        <td><code>dataFreshnessPolicy option</code>
                                        </td>
                                        <td>(Optional) Enum: The <a href="https://help.tableau.com/current/online/en-us/data_freshness_policy.htm" target="_blank" rel="noopener"> data freshness policy</a> mode for
								scheduling refreshment of the workbook data specified in the request. A valid value is one of:
								<ul><li><code>SiteDefault</code> - Use the default scheduling policy: refresh the data every 12 hours).</li><li><code>AlwaysLive</code> - Refresh as the data changes.</li><li><code>FreshAt</code> - Define a detailed cadence for refreshing the data.</li><li><code>FreshEvery</code>- Define an interval between data refreshes.</li></ul></td>
                                    </tr>
                                    <tr>
                                        <td><code>freshAtSchedule frequency</code>
                                        </td>
                                        <td>(Optional) Enum: The interval of workbook data refresh. A valid value is one of:
								<ul><li><code>Day</code></li><li><code>Week</code></li><li><code>Month</code></li></ul></td>
                                    </tr>
                                    <tr>
                                        <td><code>freshAtSchedule time</code>
                                        </td>
                                        <td>(Optional) Time in <code>HH:MM:SS</code>:  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 <code>time="10:30:00".</code></td>
                                    </tr>
                                    <tr>
                                        <td><code>freshAtSchedule timeZone</code>
                                        </td>
                                        <td>(Optional) Timezone string in IANA format: The timezone of the fresh at schedule time.
								For instance, <code>timezone="America/Los_Angeles"</code>. If no timezone is provided, then
								the local timezone of the Tableau server is used."
							</td>
                                    </tr>
                                    <tr>
                                        <td><code>freshAtSchedule intervals interval</code>
                                        </td>
                                        <td>A value that specifies the interval between refreshes of view acceleration data.
								The value you specify here depends on the
									value specified in <code>freshAtSchedule frequency</code>.
									<p><strong><code>Day</code></strong></p><p>
                                        If the schedule frequency is <code>Daily</code>, no interval is specified. Any information specified
									    in the <span class="api-command-ref">&lt;intervals&gt;</span> element is ignored.</p><p><strong><code>Week</code></strong></p><p>
                                        The interval expression is <code>weekDay="<span class="api-placeholder">weekday</span>"</code>, where
                                        <span class="api-placeholder">weekday</span> is <code>Sunday</code>, <code>Monday</code>, <code>Tuesday</code>,
                                        <code>Thursday</code>, <code>Friday</code>, or specify multiple <span class="api-command-ref">&lt;interval&gt;</span>
                                        elements to indicate that scheduled jobs should run on multiple days during the week.</p><p><strong><code>Month</code></strong></p><p>The interval expression is
                                        <code>monthDay="<span class="api-placeholder">day</span>"</code>, where
                                        <span class="api-placeholder">day</span> is either the day of the month (<code>1</code>, <code>2</code>, etc.) or <code>LastDay</code>.
									</p></td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">freshEverySchedule frequency</span>
                                        </td>
                                        <td>(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 <span class="api-placeholder">freshEverySchedule value</span>.
								A valid value is one of:
								<ul><li><code>Minutes</code></li><li><code>Hours</code></li><li><code>Days</code></li><li><code>Weeks</code></li></ul></td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">freshEverySchedule value</span>
                                        </td>
                                        <td>
								(Optional) Integer: The quantity of frequency units between view acceleration data refreshes. For instance,
								to specify a refresh every 4 hours, the <code>dataFreshnessPolicy</code> would look like:
								</td>
                                    </tr>
                                    <tr>
                                        <td colspan="2">
                                            <table class="api-parameters-table">
                                                <colgroup>
                                                    <col style="column-width: 50;">
                                                    <col style="column-width: 50;">
                                                </colgroup>
                                                <tbody>
                                                    <tr>
                                                        <td>XML</td>
                                                        <td>JSON</td>
                                                    </tr>
                                                    <tr>
                                                        <td>
                                                            <div class="codeSnippet"><a class="codeSnippetCopyButton" role="button">Copy</a>
                                                                <div class="codeSnippetBody"><pre><code>&lt;dataFreshnessPolicy option="FreshEvery"&gt;<br>&nbsp;&nbsp;&lt;freshEverySchedule&nbsp;<br>&nbsp;&nbsp;frequency="hours"&nbsp;<br>&nbsp;&nbsp;value="4" /&gt;<br>&nbsp;&nbsp;&lt;/dataFreshnessPolicy&gt;<br></code></pre>
                                                                </div>
                                                            </div>
                                                        </td>
                                                        <td>
                                                            <div class="codeSnippet"><a class="codeSnippetCopyButton" role="button">Copy</a>
                                                                <div class="codeSnippetBody"><pre><code>"dataFreshnessPolicy": {<br>&nbsp;&nbsp;"option": "FreshEvery",<br>&nbsp;&nbsp;"freshEverySchedule": {<br>&nbsp;&nbsp;"frequency": "hours",<br>&nbsp;&nbsp;"value": 4"<br>&nbsp;&nbsp;}<br>}<br></code></pre>
                                                                </div>
                                                            </div>
                                                        </td>
                                                    </tr>
                                                </tbody>
                                            </table>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

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:

<table style="width: 100%;">
                                <colgroup><col>
                                <col>
                                </colgroup><tbody>
                                    <tr>
                                        <td>XML</td>
                                        <td>JSON</td>
                                    </tr>
                                    <tr>
                                        <td>
                                            <div class="codeSnippet"><a class="codeSnippetCopyButton" role="button">Copy</a>
                                                <div class="codeSnippetBody"><pre><code>&lt;dataFreshnessPolicy option="FreshEvery"&gt;<br>&nbsp;&nbsp;&lt;freshEverySchedule&nbsp;<br>&nbsp;&nbsp;frequency="Weeks"&nbsp;<br>&nbsp;&nbsp;value="1" /&gt;<br>&nbsp;&nbsp;&lt;/dataFreshnessPolicy&gt;<br></code></pre>
                                                </div>
                                            </div>
                                        </td>
                                        <td>
                                            <div class="codeSnippet"><a class="codeSnippetCopyButton" role="button">Copy</a>
                                                <div class="codeSnippetBody"><pre><code>"dataFreshnessPolicy": {<br>&nbsp;&nbsp;"option": "FreshEvery",<br>&nbsp;&nbsp;"freshEverySchedule": {<br>&nbsp;&nbsp;"frequency": "Weeks",<br>&nbsp;&nbsp;"value": 1"<br>&nbsp;&nbsp;}<br>}<br></code></pre>
                                                </div>
                                            </div>
n                            </td>
                                    </tr>
                                </tbody>
                            </table>

#### Version

Version 2.0 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>400</td><td>400036</td><td>Bad request</td><td>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.</td></tr><tr><td>403</td><td>403025</td><td>Project update forbidden</td><td>A non-administrator user tried to change the workbook project, but the caller doesn't have <span class="api-command-ref">Write</span> permission for the target project.</td></tr><tr><td>403</td><td>403027</td><td>Owner update forbidden</td><td>A non-administrator user tried to change the workbook owner.</td></tr><tr><td>403</td><td>403027</td><td>Update forbidden</td><td>A non-administrator user tried to change the workbook, but the caller doesn't have <span class="api-command-ref">Write</span> permission for the workbook.</td></tr><tr><td>403</td><td>403004</td><td>Update forbidden</td><td>A non-administrative user tried to update the workbook, but does not have permissions to publish the updated workbook to the project.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404002</td><td>Owner not found</td><td>The owner ID in the request body doesn't correspond to an existing user.</td></tr><tr><td>404</td><td>404005</td><td>Project not found</td><td>The project ID in the URI doesn't match the project ID provided in the request body.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">PUT</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Update Workbook Connection

Updates the server address, port, authentication type, 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. To update specific connections in a workbook containing multiple connections, see [Update Data Source Connections](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#update_workbook_connections).

**Version:**Available in API 2.0 (Tableau Cloud and later).

**License:** No additional license required.

**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.  _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**Access Scope**: `tableau:workbooks:update`

- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-extra-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to update.</td></tr><tr><td><span class="api-placeholder">connection-id</span></td><td>The ID of the connection to update.</td></tr></tbody></table>

#### Request Body

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

```
{
  "connection": {
    "serverAddress": "server-address",
    "serverPort": "port",
	 "authenticationType": "auth-type",
    "userName": "connection-username",
    "password": "connection-password",
    "embedPassword": "embed-password",
    "queryTaggingEnabled": "query-tagging-enabled"
  }
}
```

#### Attribute Values

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

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1-extra-wide">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td class="api-placeholder"><span class="api-placeholder">serverAddress</span>
                                        </td>
                                        <td>The new server for the connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">port</span>
                                        </td>
                                        <td>The new port for the connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">authenticationType</span>
                                        </td>
                                        <td>
								Added in version 3.27.
                                <p>*The new authentication type for the connection.</p><p>Standard values:</p><ul><li><p><code>auth-user-pass</code>:&nbsp;username and password</p></li><li><p><code>oauth</code></p></li><li><p><code>auth-keypair</code>:&nbsp;keypair authentication</p></li></ul><p>Connector-specific values:</p><ul><li><p><code>sqlserver</code>:&nbsp;SQL&nbsp;Server username and password</p></li><li><p><code>Azure AD Password</code></p></li><li><p><code>AD Service Principal</code></p></li><li><p><code>username-password</code>:&nbsp;Several connectors use this value. For example, SAP&nbsp;HANA, SAP Sybase ASE, SAP NetWeaver Business Warehouse (BW), Denodo, and Salesforce.</p></li></ul><p>If you are unsure of the value for authenticationType for the target connection, there are two ways to determine the value. First, if you have a data source or workbook that is currently using the target authentication type, you can query for it using the REST API methods <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#query_data_sources" target="_blank">Query Datasource Connections</a> or <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_workbook_connections" target="_blank">Query Workbook Connections</a>, which returns the authentication type string in the response. </p><p>Alternatively,  you can inspect the <code>&lt;connection&gt;</code> element in the XML of a workbook or data source which is available locally. Look for the value of the <code>authentication</code> attribute of the connection. </p></td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">userName</span>
                                        </td>
                                        <td>The new username for the connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">password</span>
                                        </td>
                                        <td>The new password for the connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">embedPassword</span>
                                        </td>
                                        <td><code>True</code> to embed the password; otherwise, <code>False</code>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">queryTaggingEnabled</span>
                                        </td>
                                        <td>
                                            <blockquote><p>[!WARNING]</p><p>Starting with API 3.23 (Tableau Cloud June 2024 / Server 2024.2), the <code>queryTaggingEnabled</code> attribute is deprecated,
									will no longer be supported, and may be retired in future releases.<br><br>Instead, for Tableau Server, use TSM to enable query tagging for all content on a server by
									setting <a href="https://help.tableau.com/current/server/en-us/cli_configuration-set_tsm.htm#native_apiUserInfoInGeneratedSQLEnabled" target="_blank"><code>native_api.UserInfoInGeneratedSQLEnabled</code></a> to <code>true</code>.</p></blockquote>
                                            <p>For API 3.22 (Tableau Cloud February 2024 / Server 2024.1) or earlier: If <code>true</code>, query tagging is enabled. If <code>false</code>, query tagging is disabled. The default is <code>false</code>.</p>
                                            <p>For more information on query tagging, see 	<a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_how_to_query_tagging.htm" target="_blank" class="xref">Understand Workbook Impact on Your Database Using Query Tagging</a>.</p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

#### cURL Request Example

```
curl --location --request PUT "/api/api-version/sites/site-id/workbooks/workbook-id/connections/connection-id" \ --header "Content-Type: application/xml" \ --header "X-Tableau-Auth;" \ --data "{   'connection': {     'serverAddress': 'server-address',     'serverPort': 'port', 'authenticationType': 'auth-type', 'userName': 'connection-username',     'password': 'connection-password',     'embedPassword': 'embed-password',     'queryTaggingEnabled': 'query-tagging-enabled'   } }"
```

#### Response Code

200

#### Response Body

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

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>403</td><td>403029</td><td>Update forbidden</td><td>A non-administrator user tried to update the workbook connection, but the caller doesn't have <span class="api-command-ref">Write</span> permission.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook ID in the URI doesn't correspond to an existing workbook.</td></tr><tr><td>404</td><td>404020</td><td>Connection not found</td><td>The connection ID in the URI doesn't correspond to an existing connection.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">PUT</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Update Workbook Connections

Updates the server address, port, authentication type, username, or password for one or more connections in a data source. To update all connections in a given data source with the same connection information, see [Update Workbook Connection](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#update_workbook_connection).

**Version**: Available in API 3.27 and later.

**License**: No additional license required.

**Permissions**: Users who are server administrators or site administrators can change the connection for a data source or enable [query tagging](https://help.tableau.com/current/pro/desktop/en-us/performance_tips.htm). Users who are not server administrators can only update a data source. If they have Write (save) permission for the data source and if they have write permission for the project.

**Access Scope**: `tableau:datasources:update`

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

For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### Path Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-luid</span></td><td>The LUID of the site that contains the data source.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to update.</td></tr></tbody></table>

#### Request Body

```
<tsRequest>
  <connectionLuids>
<connectionLuid>Luid1</connectionLuid>
<connectionLuid>Luid2</connectionLuid>
  </connectionLuids>
  <connection
    serverAddress="newAddress"
    serverPort="newPort"
    authenticationType="new Auth Type"
    userName="Jane Doe"
    password="xxxxxx"
    embedPassword="false"
    queryTaggingEnabled="false" />
  </tsRequest>
```

```
{
  "connectionLuids": [
    "Luid1",
    "Luid2"
  ],
  "connection": {
    "serverAddress": "newAddress",
    "serverPort": "newPort",
    "authenticationType": "new Auth Type",
    "userName": "Jane Doe",
    "password": "xxxxxx",
    "embedPassword": "false",
    "queryTaggingEnabled": "false"
  }
}
```

#### Request Attributes

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

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1-extra-wide">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><span class="api-placeholder">connectionLuids</span>
                                        </td>
                                        <td>An array of connection LUIDs in the workbook that you are updating.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">serverAddress</span>
                                        </td>
                                        <td> The new server for the connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">serverPort</span>
                                        </td>
                                        <td> The new port for the connection</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">authenticationType</span>
                                        </td>
                                        <td>
                                            <p>*The new authentication type for the connection.</p>
                                            <p>Standard values:</p>
                                            <ul>
                                                <li>
                                                    <p><code>auth-user-pass</code>:&nbsp;username and password</p>
                                                </li>
                                                <li>
                                                    <p><code>oauth</code>
                                                    </p>
                                                </li>
                                                <li>
                                                    <p><code>auth-keypair</code>:&nbsp;keypair authentication</p>
                                                </li>
                                            </ul>
                                            <p>Connector-specific values:</p>
                                            <ul>
                                                <li>
                                                    <p><code>sqlserver</code>:&nbsp;SQL&nbsp;Server username and password</p>
                                                </li>
                                                <li>
                                                    <p><code>Azure AD Password</code>
                                                    </p>
                                                </li>
                                                <li>
                                                    <p><code>AD Service Principal</code>
                                                    </p>
                                                </li>
                                                <li>
                                                    <p><code>username-password</code>:&nbsp;Several connectors use this value. For example, SAP&nbsp;HANA, SAP Sybase ASE, SAP NetWeaver Business Warehouse (BW), Denodo, and Salesforce.</p>
                                                </li>
                                            </ul>
                                            <p>If you are unsure of the value for authenticationType for the target connection, there are two ways to determine the value. First, if you have a data source or workbook that is currently using the target authentication type, you can query for it using the REST API methods <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#query_data_sources" target="_blank">Query Datasource Connections</a> or <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm#query_workbook_connections" target="_blank">Query Workbook Connections</a>, which returns the authentication type string in the response. </p>
                                            <p>Alternatively,  you can inspect the <code>&lt;connection&gt;</code> element in the XML of a workbook or data source which is available locally. Look for the value of the <code>authentication</code> attribute of the connection. </p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">userName</span>
                                        </td>
                                        <td>The new username for the connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">password</span>
                                        </td>
                                        <td>The new password for the connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">embedPassword</span>
                                        </td>
                                        <td><code>True</code> to embed the password; otherwise, <code>False</code>.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">queryTaggingEnabled</span>
                                        </td>
                                        <td>
                                            <blockquote><p>[!WARNING]</p><p>Starting with API 3.23 (Tableau Cloud June 2024 / Server 2024.2), the <code>queryTaggingEnabled</code> attribute is deprecated,
									will no longer be supported, and may be retired in future releases.<br><br>Instead, for Tableau Server, use TSM to enable query tagging for all content on a server by
								setting <a href="https://help.tableau.com/current/server/en-us/cli_configuration-set_tsm.htm#native_apiUserInfoInGeneratedSQLEnabled" target="_blank"><code>native_api.UserInfoInGeneratedSQLEnabled</code></a> to <code>true</code>.</p></blockquote>
                                            <p>For API 3.22 (Tableau Cloud February 2024 / Server 2024.1) and earlier: If <code>true</code>, query tagging is enabled. If <code>false</code>, query tagging is disabled. The default is <code>false</code>.</p>
                                            <p>For more information on query tagging, see 	<a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_how_to_query_tagging.htm" target="_blank" class="xref">Understand Workbook Impact on Your Database Using Query Tagging</a>.</p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

#### cURL Request Example

```
curl --location --request PUT "/api/api-version/sites/site-id/workbooks/workbook-id/connections" \ --header "Content-Type: application/xml" \ --header "X-Tableau-Auth;" \ --data "{   'connectionLuids': [     'Luid1',     'Luid2'   ],   'connection': {     'serverAddress': 'newAddress',     'serverPort': 'newPort',     'authenticationType': 'new Auth Type',     'userName': 'Jane Doe',     'password': 'xxxxxx',     'embedPassword': 'false',     'queryTaggingEnabled': 'false'   } }"
```

#### Access Scope

Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).

```
tableau:workbooks:update
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### Response Code

200

#### Response Body

```
<tsResponse>
  <connection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd"
	serverAddress="database.example.com"
	serverPort="12345"
	authenticationType="new Auth Type"
	userName="jajohnson"
	queryTaggingEnabled="false" />
</tsResponse>
```

```
{
  "connection": {
	"id": "12ab34cd-56ef-78ab-90cd-12ef34ab56cd",
	"serverAddress": "database.example.com",
	"serverPort": "12345",
	"authenticationType": "new Auth Type",
	"userName": "jajohnson",
	"queryTaggingEnabled": "false"
  }
}
```

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Bad request</td><td>The content of the request body is missing or incomplete, or contains malformed XML.</td></tr><tr><td>403</td><td>403023</td><td>Update forbidden</td><td>A non-administrator user tried to update a data source, but the caller doesn't have <span class="api-command-ref">Write</span> permission.</td></tr><tr><td>403</td><td>403027</td><td>Owner update forbidden</td><td>A non-administrator user tried to change connection information, but the caller doesn't have <span class="api-command-ref">Write</span> permission.</td></tr><tr><td>403</td><td>403062</td><td>Unsupported operation</td><td>The data source contains multiple connections, but the URI did not include <code>/connections/<span class="api-placeholder">connection-id</span></code> to indicate which connection should be updated.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404004</td><td>Data source not found</td><td>The data source ID in the URI doesn't correspond to an existing data source.</td></tr><tr><td>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">PUT</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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](https://help.tableau.com/current/server/en-us/maintenance_set.htm).

#### URI

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

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook to refresh.</td></tr></tbody></table>

#### Request Body

As of version 3.28, you can specify an incremental refresh on extracts by updating the request body as follows:

```
<tsRequest>
	<extractRefresh incremental="true">
	</extractRefresh>
</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
```

For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### 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" incremental="true" />
    </extractRefreshJob>
  </job>
</tsResponse>
```

#### Version

Version 2.8 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm).

#### Errors

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

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Example

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

## Update Workbook Thumbnail Images

Updates a workbook's thumbnail images.

The method adds a task to the backgrounder queue. Depending upon the length of the queue, the task might not run immediately. The method returns information about the backgrounder job responsible for running the task, including the `job id` that can be used with the [Query Job](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#query_job) method.

**Version**: Available in API 3.27 (Tableau Cloud December 2025 / Server 2025.3) and later.

**License**: No additional license required.

**Permissions**: Server administrators, site administrators, or workbook owner

**Access Scope**: `tableau:tasks:run`

- For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site that contains the workbook.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The ID of the workbook.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request Example

```
curl -X PUT "https://MY-SERVER/api/3.27/sites/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/workbooks/08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6/refreshThumbnails" -H "X-Tableau-Auth: a1B2c3D4e5F6g7H8i9J0kL|a1B2c3D4e5F6g7H8i9J0kL1m2N3o4P5q|12345678-90ab-4cde-8f01-234567890abc"
```

#### Response Code

202

#### Response Body

```
<tsResponse>
  <job id="job-id" mode="Asynchronous" type="RefreshThumbnails" createdAt="date-time">
    <thumbnailsRefreshJob>
      <workbook id="workbook-id" name="workbook-name" />
    </thumbnailsRefreshJob>
  </job>
</tsResponse>
```

```
{
  "job": {
    "thumbnailsRefreshJob": {
      "workbook": {
        "id": "workbook-id",
        "name": "workbook-name"
      }
    },
    "id": "job-id",
    "mode": "Asynchronous",
    "type": "RefreshThumbnails",
    "createdAt": "date-time"
  }
}
```

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>400000</td><td>Generic error</td><td>An unknown error occurred. The content of the request body may be missing or incomplete, or may contain malformed XML.</td></tr><tr><td>403</td><td>403179</td><td>Permissions error</td><td>The user calling the method isn't a site administrator, server administrator, or owner of the workbook.</td></tr><tr><td>404</td><td>404006</td><td>Workbook not found</td><td>The workbook LUID is invalid, or the user doesn't have permission to read the workbook.</td></tr><tr><td>500</td><td>500000</td><td>Internal server error</td><td>The server was unable to create the job.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## 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](https://help.tableau.com/current/server/en-us/cmt-migration_embedded_credentials.htm).

**Version:** Available in API 3.23 (Tableau Cloud June 2024/ Tableau Server 2024.2) and later. _[Version Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**License:** No additional license required.

**Permissions:** This method can only be called by Tableau Cloud and Tableau Server admins.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope:** tableau:embedded\_credentials:upload

- Scope added in API 3.27 (Tableau Cloud December 2025 / Server 2025.3).
- For more information, see [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud) and access scopes for connected apps: [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm), or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

#### URI

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

#### URI Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-luid</span></td><td>The LUID for the site.</td></tr><tr><td><span class="api-placeholder">workbook-luid</span></td><td>The LUID of the workbook to download the encrypted keychain from.</td></tr></tbody></table>

#### 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

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><code>associatedUserLuidMapping</code>
                                        </td>
                                        <td>
                                            <p>
								(Required) The user IDs from the source site mapped to destination site user IDs.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><code>encryptedKeychainList</code>
                                        </td>
                                        <td>(Required) List of encrypted keychains from the source Tableau Server.</td>
                                    </tr>
                                    <tr>
                                        <td><code>encryptedKeychain</code>
                                        </td>
                                        <td>
                                            <p>(Required) Encrypted keychain from the source Tableau Server.</p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

#### cURL Request Example

```
curl --location 'https://example.org/api/3.24/sites/7a2f773d-4a9f-496e-afc6-a60517cb1b86/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/applykeychain' \
 -X PUT \
--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

<table class="api-error-table">
                        <colgroup>
                            <col class="api-error-table-col-1">
                            <col class="api-error-table-col-2">
                            <col class="api-error-table-col-3">
                            <col>
                        </colgroup>
                        <tbody>
                            <tr>
                                <th>HTTP status</th>
                                <th><code>error</code> Code</th>
                                <th>Condition</th>
                                <th>Details</th>
                            </tr>
                            <tr>
                                <td>400</td>
                                <td>400000</td>
                                <td>Bad Request</td>
                                <td>The content of the request body is missing or incomplete, or contains malformed XML.</td>
                            </tr>
                            <tr>
                                <td>401</td>
                                <td>401002</td>
                                <td>Unauthorized Access</td>
                                <td>
                                    <p>The authentication token provided in the request header was invalid or has expired.</p>
                                </td>
                            </tr>
                            <tr>
                                <td>403</td>
                                <td>403054</td>
                                <td>Unauthorized Access</td>
                                <td>A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.</td>
                            </tr>
                            <tr>
                                <td>404</td>
                                <td>404000</td>
                                <td>Site not found</td>
                                <td>The site ID in the URI doesn't correspond to an existing site.</td>
                            </tr>
                            <tr>
                                <td>404	</td>
                                <td>404006	</td>
                                <td>Workbook not found	</td>
                                <td>The workbook ID in URI doesn't correspond to an existing workbook.</td>
                            </tr>
                            <tr>
                                <td>405</td>
                                <td>405000</td>
                                <td>Invalid request method</td>
                                <td>Request type was not <span class="api-command-ref">PUT</span>.</td>
                            </tr>
                        </tbody>
                    </table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Validate Uploaded Workbook

Validates a Tableau workbook (TWB) file that already exists in temporary storage on Tableau Cloud or Tableau Server. The TWB is validated against the TWB XSD schema and verifies that it can be loaded in Tableau.

**Version**: Available in API 3.29 (Tableau Cloud June 2026 / Server 2026.2) and later.

**License**: No additional license required.

**Permissions**: Any authenticated user.

**Access Scope**: `tableau:workbooks:create`

For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

Use this method to validate a TWB file that's already been stored using the file upload REST API ([Initiate File Upload](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_publishing.htm#initiate_file_upload) and [Append to File Upload](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_publishing.htm#append_to_file_upload)). Provide the upload session ID as a query parameter to validate the uploaded file.

The validation performs both syntactic validation (verifying the TWB conforms to the TWB XSD schema) and semantic validation (verifying the content can be interpreted by Tableau).

For more information about the officially supported TWB XSD schema, see the [tableau-document-schemas](https://github.com/tableau/tableau-document-schemas) repository on GitHub.

#### URI

POST /api/api-version/sites/site-id/workbooks/validateUploadedWorkbook?uploadSessionId=upload-session-id

#### URI Parameter Values

<table class="simple-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site.</td></tr><tr><td><span class="api-placeholder">upload-session-id</span></td><td>The upload session ID returned from the <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_publishing.htm#initiate_file_upload" target="_blank">Initiate File Upload</a> endpoint.</td></tr></tbody></table>

#### Request Header

This method can only return a JSON-formatted response. Set the HTTP `Accept` request header appropriately:

`Accept: application/json`

#### Request Body

None

#### cURL Example

```
curl --location --request POST 'https://example.com/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/validateUploadedWorkbook?uploadSessionId=12345:12ab34cd56ef78ab90cd12ef34ab56cd-0:0' --header 'X-Tableau-Auth: aBcDeFgHiJkLmNoPqRsTuV|1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p|12345678-1234-5678-9abc-def012345678' --header 'Accept: application/json'
```

#### Response Code

200

#### Response Body

A validation response that returns a 200 response code, zero validation errors, and zero or more validation warnings indicates successful validation. Warnings are advisory, and won't prevent a workbook from loading in Tableau. Details about the validation warnings are returned in the response body as JSON.

```
{
  "timestamp": "2026-06-10T14:32:18.456Z",
  "uploadId": "12345:12ab34cd56ef78ab90cd12ef34ab56cd-0:0",
  "warnings": [
    {
      "severity": "WARNING",
      "message": "Unknown map source is used",
      "line": 245,
      "column": 18,
      "elementName": "map"
    }
  ]
}
```

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>&nbsp;</td><td>Missing uploadSessionId parameter</td><td>The required <code>uploadSessionId</code> parameter isn't present in the querystring.</td></tr><tr><td>404</td><td>&nbsp;</td><td>Resource not found</td><td>The <code>uploadSessionId</code> parameter couldn't be found.</td></tr><tr><td>422</td><td>&nbsp;</td><td>Unprocessable entity</td><td>The TWB validation task completed, but detected errors. <b>See the response body for detailed validation information.</b></td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Validation errors

A validation response that returns zero or more validation errors indicates failed validation. Unlike validation warnings, validation errors _will_ prevent a workbook from loading in Tableau. Details about the validation errors and warnings are returned in the response body as JSON.

Example response:

{
  "timestamp": "2026-06-10T14:32:18.456Z",
  "errors": \[
    {
      "severity": "ERROR",
      "message": "Missing required closing tag for element",
      "line": 127,
      "column": 5,
      "elementName": "preferences"
    }
  \],
  "warnings": \[
    {
      "severity": "WARNING",
      "message": "Unknown map source is used",
      "line": 245,
      "column": 18,
      "elementName": "map"
    }
  \]
}

## Validate Workbook

Validates a Tableau workbook (TWB) file against the TWB XSD schema and verifies that it can be loaded in Tableau.

**Version**: Available in API 3.29 (Tableau Cloud June 2026 / Server 2026.2) and later.

**License**: No additional license required.

**Permissions**: Any authenticated user.

**Access Scope**: `tableau:workbooks:read`

For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

This endpoint validates TWB file content without storing it on Tableau Cloud or Tableau Server. The validation performs both syntactic validation (verifying the TWB conforms to the TWB XSD schema) and semantic validation (verifying the content can be interpreted by Tableau).

For more information about the officially supported TWB XSD schema, see the [tableau-document-schemas](https://github.com/tableau/tableau-document-schemas) repository on GitHub.

#### URI

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

#### URI Parameter Values

<table class="simple-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site.</td></tr></tbody></table>

#### Request Header

This method can only return a JSON-formatted response. Set the HTTP `Accept` request header appropriately:

`Accept: application/json`

#### Request Body

The request body is the TWB, sent as multipart form data. **Note:** The request body can't be a TWBX (packaged workbook).

**Option 1: Use a code library or client that can assemble the request** - Most clients and code libraries can automatically create a multipart request that's appropriate for sending the TWB. In such cases, you only need to provide:

- the `name` parameter and its value, `tableau_workbook`
- the `filename` parameter and its value, the TWB filename
- the TWB file

**Option 2: Manually assemble the request** - Manually assembling the request has specific requirements:

Set a `Content-Type` request header indicating the body is `multipart/form-data` or `multipart/mixed`, and define the `boundary` string. (A boundary string is a unique string that won't occur in the request body outside of its use as a delimiter.)

Example:  
`Content-Type: multipart/form-data; boundary=12ab34cd-56ef-78ab-90cd-12ef34ab56cd`  

Build the request body

- begin with the boundary string defined in the request header, prepended by "--" ;
- add an inline `Content-Disposition` header that indicates `form-data` encoding, sets `name` equal to `tableau_workbook`, and sets `filename` equal to a string ending in `.twb`;
- conclude with the boundary string defined in the request header, prepended by "--" and appended by "--".

Example:

(The placeholder `{workbook-xml}`represents the raw TWB XML.)

```
--12ab34cd-56ef-78ab-90cd-12ef34ab56cd
Content-Disposition: form-data; name="tableau_workbook"; filename=superstore.twb

{workbook-xml}
--12ab34cd-56ef-78ab-90cd-12ef34ab56cd--
```

For more information on sending the TWB using a multipart request, see the concepts covered in the "Uploading the file in parts" section of [Publishing Resources](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_publish.htm#uploading-the-file-in-parts), or search the Internet using terms like **multipart** and **HTTP**.

#### cURL Example

(The placeholder `{path-to-twb}`represents the local path to the TWB file.)

```
curl --location 'https://example.com/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/validateWorkbook' --header 'X-Tableau-Auth: aBcDeFgHiJkLmNoPqRsTuV|1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p|12345678-1234-5678-9abc-def012345678' --header 'Accept: application/json' --form 'tableau_workbook=@"{path-to-twb}"'
```

#### Response Code

200

#### Response Body

A validation response that returns a 200 response code, zero validation errors, and zero or more validation warnings indicates successful validation. Warnings are advisory, and won't prevent a workbook from loading in Tableau. Details about the validation warnings are returned in the response body as JSON.

Example response:

```
{
  "timestamp": "2026-06-10T14:32:18.456Z",
  "warnings": [
    {
      "severity": "WARNING",
      "message": "Unknown map source is used",
      "line": 245,
      "column": 18,
      "elementName": "map"
    }
  ]
}
```

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>&nbsp;</td><td>Missing required parameter</td><td>The required <code>tableau_workbook</code> parameter isn't present in the request.</td></tr><tr><td>400</td><td>&nbsp;</td><td>Invalid file type or content</td><td>The file is not a valid TWB file or does not contain TWB XML content, or the "filename" parameter doesn't end with ".twb".</td></tr><tr><td>406</td><td>406000</td><td>No acceptable response</td><td>This method can only return a JSON response. Use the <code>Accept:&nbsp;application/json</code> header.</td></tr><tr><td>422</td><td>&nbsp;</td><td>Unprocessable entity</td><td>The TWB validation task completed, but detected errors. <b>See the response body for detailed validation information.</b></td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Validation errors

A validation response that returns zero or more validation errors indicates failed validation. Unlike validation warnings, validation errors _will_ prevent a workbook from loading in Tableau. Details about the validation errors and warnings are returned in the response body as JSON.

Example response:

{
  "timestamp": "2026-06-10T14:32:18.456Z",
  "errors": \[
    {
      "severity": "ERROR",
      "message": "Missing required closing tag for element",
      "line": 127,
      "column": 5,
      "elementName": "preferences"
    }
  \],
  "warnings": \[
    {
      "severity": "WARNING",
      "message": "Unknown map source is used",
      "line": 245,
      "column": 18,
      "elementName": "map"
    }
  \]
}

## Validate Workbook and Upload

Validates a Tableau workbook (TWB) file against the TWB XSD schema and verifies that it can be loaded in Tableau. If validation succeeds, this method stores the TWB in a temporary location on Tableau Cloud or Tableau Server for further use.

**Version**: Available in API 3.29 (Tableau Cloud June 2026 / Server 2026.2) and later.

**License**: No additional license required.

**Permissions**: Any authenticated user.

**Access Scope**: `tableau:workbooks:create`

For more information, see [Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm), [Permissions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm), [Access scopes for UATs](https://help.tableau.com/current/api/cloud-manager/en-us/docs/unified_access_tokens.html#scopes) (Cloud), and access scopes for [Cloud](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm), [Server-Windows,](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) or [Server-Linux](https://help.tableau.com/current/server-linux/en-us/connected_apps_scopes.htm).

The validation performs both syntactic validation (verifying the TWB conforms to the TWB XSD schema) and semantic validation (verifying the content can be interpreted by Tableau).

For more information about the officially supported TWB XSD schema, see the [tableau-document-schemas](https://github.com/tableau/tableau-document-schemas) repository on GitHub.

#### URI

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

#### URI Parameter Values

<table class="simple-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm" class="xref">REST API and Resource Versions</a>.</td></tr><tr><td><span class="api-placeholder">site-id</span></td><td>The ID of the site.</td></tr></tbody></table>

#### Request Header

This method can only return a JSON-formatted response. Set the HTTP `Accept` request header appropriately:

`Accept: application/json`

#### Request Body

The request body is the TWB, sent as multipart form data. **Note:** The request body can't be a TWBX (packaged workbook).

**Option 1: Use a code library or client that can assemble the request** - Most clients and code libraries can automatically create a multipart request that's appropriate for sending the TWB. In such cases, you only need to provide:

- the `name` parameter and its value, `tableau_workbook`
- the `filename` parameter and its value, the TWB filename
- the TWB file

**Option 2: Manually assemble the request** - Manually assembling the request has specific requirements:

Set a `Content-Type` request header indicating the body is `multipart/form-data` or `multipart/mixed`, and define the `boundary` string. (A boundary string is a unique string that won't occur in the request body outside of its use as a delimiter.)

Example:  
`Content-Type: multipart/form-data; boundary=12ab34cd-56ef-78ab-90cd-12ef34ab56cd`  

Build the request body

- begin with the boundary string defined in the request header, prepended by "--" ;
- add an inline `Content-Disposition` header that indicates `form-data` encoding, sets `name` equal to `tableau_workbook`, and sets `filename` equal to a string ending in `.twb`;
- conclude with the boundary string defined in the request header, prepended by "--" and appended by "--".

Example:

(The placeholder `{workbook-xml}`represents the raw TWB XML.)

```
--12ab34cd-56ef-78ab-90cd-12ef34ab56cd
Content-Disposition: form-data; name="tableau_workbook"; filename=superstore.twb

{workbook-xml}
--12ab34cd-56ef-78ab-90cd-12ef34ab56cd--
```

For more information on sending the TWB using a multipart request, see the concepts covered in the "Uploading the file in parts" section of [Publishing Resources](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_publish.htm#uploading-the-file-in-parts), or search the Internet using terms like **multipart** and **HTTP**.

#### cURL Example

(The placeholder `{path-to-twb}`represents the local path to the TWB file.)

```
curl --location 'https://example.com/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/validateWorkbookAndUpload' --header 'X-Tableau-Auth: aBcDeFgHiJkLmNoPqRsTuV|1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p|12345678-1234-5678-9abc-def012345678' --header 'Accept: application/json' --form 'tableau_workbook=@"{path-to-twb}"'
```

#### Response Code

200

#### Response Body

A validation response that returns a 200 response code, zero validation errors, and zero or more validation warnings indicates successful validation. Warnings are advisory, and won't prevent a workbook from loading in Tableau. Details about the validation warnings are returned in the response body as JSON.

```
{
  "timestamp": "2026-06-10T14:32:18.456Z",
  "uploadId": "12345:12ab34cd56ef78ab90cd12ef34ab56cd-0:0",
  "warnings": [
    {
      "severity": "WARNING",
      "message": "Unknown map source is used",
      "line": 245,
      "column": 18,
      "elementName": "map"
    }
  ]
}
```

#### Errors

<table class="api-error-table"><colgroup><col class="api-error-table-col-1"> <col class="api-error-table-col-2"> <col class="api-error-table-col-3"> <col></colgroup><tbody><tr><th>HTTP status</th><th><code>error</code> Code</th><th>Condition</th><th>Details</th></tr><tr><td>400</td><td>&nbsp;</td><td>Missing required parameter</td><td>The required <code>tableau_workbook</code> parameter isn't present in the request.</td></tr><tr><td>400</td><td>&nbsp;</td><td>Invalid file type or content</td><td>The file is not a valid TWB file or does not contain TWB XML content, or the "filename" parameter doesn't end with ".twb".</td></tr><tr><td>406</td><td>406000</td><td>No acceptable response</td><td>This method can only return a JSON response. Use the <code>Accept:&nbsp;application/json</code> header.</td></tr><tr><td>422</td><td>&nbsp;</td><td>Unprocessable entity</td><td>The TWB validation task completed, but detected errors. <b>See the response body for detailed validation information.</b></td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

#### Validation errors

A validation response that returns zero or more validation errors indicates failed validation. Unlike validation warnings, validation errors _will_ prevent a workbook from loading in Tableau. Details about the validation errors and warnings are returned in the response body as JSON.

Example response:

{
  "timestamp": "2026-06-10T14:32:18.456Z",
  "errors": \[
    {
      "severity": "ERROR",
      "message": "Missing required closing tag for element",
      "line": 127,
      "column": 5,
      "elementName": "preferences"
    }
  \],
  "warnings": \[
    {
      "severity": "WARNING",
      "message": "Unknown map source is used",
      "line": 245,
      "column": 18,
      "elementName": "map"
    }
  \]
}