---
schema_version: "1"
id: 687a746ef3ad98be526511d2a500fa68ed1a8a7deb2b1c4c09986681917f1e30
title: Virtual Connections Methods
collection: tableau
version: next
locale: en-us
portal_url: https://docs.salesforce.com/tableau/next/en-us/api/rest_api/REST/rest_api_ref_virtual_connections.md
canonical_url: https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_virtual_connections.htm
source_site: help.tableau.com
content_type: documentation
content_hash: 923589b7f39a7565e24c2db905a39e1b110c6def7f106d2446c696ab74e75c0b
description: Virtual connections are a centralized way to share access to databases and tables, allowing for convenient reuse
---
[Skip to main content](#main-content)

# Virtual Connections Methods

Virtual connections are a centralized way to share access to databases and tables, allowing for convenient reuse. A virtual connection has one or more database connections, where server locations, database names, and credentials are defined. Each database connection accesses one database or file. Associated data policies provide security for workbooks, data sources, and flows that use virtual connections.

Using the virtual connections methods of the Tableau Server REST API you can:

- Get a list of virtual connections and details for each.
- Get and update the connection information for a virtual connection.

This functionality relates to the UI elements and concepts described at: [Use a Virtual Connection](https://help.tableau.com/current/server/en-us/dm_vconn_use.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: Virtual Connections](https://www.postman.com/salesforce-developers/salesforce-developers/folder/rnppoei/virtual-connections)

## Add Tags to Virtual Connection

Adds tags to a virtual connection.

**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:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** You must have the View permission for the virtual connection and your site role must be at least Explorer.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:virtual\_connection\_tags:update

- 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-id/virtualconnections/virtualconnection-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/v0.0/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">virtualconnection-id</span></td><td>The LUID for the virtual connection.</td></tr></tbody></table>

#### Request Body

```
<tsRequest>
  <tags>
    <tag label="tag" />
    <!-- ...additional tag elements... -->
  </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">tag</span></td><td>The text of the tag.</td></tr></tbody></table>

#### cURL Request Example

`curl --location --request PUT 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/tags' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml`

**Contents of data.xml.**

```
<tsRequest>
  <tags>
    <tag label="Office" />
    <!-- ...additional tag elements... -->
  </tags>
</tsRequest>
```

#### Response Code

200

#### Response Body

```
<tsResponse>
  <tags>
    <tag label="tag"/>
    <!-- ...additional tags... -->
  </tags>
</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>400</td><td>400049</td><td>Error adding tags</td><td>There was a problem adding tags to the specified virtual connection.</td></tr><tr><td>403</td><td>403004</td><td>Adding tags forbidden</td><td>The user doesn't have permissions to add tags to the virtual connection.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site ID in the URI is not for an existing site.</td></tr><tr><td>404</td><td>404006</td><td>Virtual connection not found</td><td>The virtual connection ID in URI doesn't correspond to an existing virtual connection.</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/v0.0/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Add Virtual Connection Permissions

Adds permissions to the specified virtual connection for a user or group. You can specify multiple sets of permissions using one call.

If a specified permission has already been granted or denied for a given user or group, the system ignores it.

#### URI

PUT /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions

#### 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/v0.0/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 virtual connection.</td></tr><tr><td><span class="api-placeholder">virtualconnection-id</span></td><td>The ID of the virtual connection to set permissions for.</td></tr></tbody></table>

#### Request Body

```
<tsRequest>
  <permissions>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!--   ...additional capabilities...   -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!--   ...additional capabilities...   -->
      </capabilities>
    </granteeCapabilities>
    <!--   ...additional granteeCapability sets...   -->
  </permissions>
</tsRequest>
```

#### Attribute 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">user-id</span>
                                        </td>
                                        <td>The LUID of the user to add permissions for. A request does not need to include both a user and a group grantee.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">group-id</span>
                                        </td>
                                        <td>The LUID of the group to add permissions for. A request does not need to include both a user and a group grantee.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">capability-name</span>
                                        </td>
                                        <td>
                                            <p>
                   The capability to assign. Valid capabilities for a virtual connection are
                       <span class="api-command-ref">Read</span>,
                       <span class="api-command-ref">Connect</span>,
                       <span class="api-command-ref">Overwrite</span>,
                       <span class="api-command-ref">ChangeHierarchy</span>,
					   <span class="api-command-ref">Delete</span>, and
					   <span class="api-command-ref">ChangePermissions</span>.
				  </p>
                                            <p>For more information, see
<a href="https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm" class="xref">Permissions</a>.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">capability-mode</span>
                                        </td>
                                        <td><span class="api-command-ref">Allow</span> to allow the capability,
                                    or <span class="api-command-ref">Deny</span> to deny it.</td>
                                    </tr>
                                </tbody>
                            </table>

#### Permissions

You must be an administrator or have the ChangePermissions permission for the virtual connection (either explicitly or implicitly).

#### Required scope for JWT authorization

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

Authorize use of this method 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), or [Access Scopes for Connected Apps](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm) in the Tableau Cloud Help or [Access Scopes for Connected Apps](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) in the Tableau Server Help.

```
tableau:permissions:update
```

#### Response Code

200

#### Response Body

```
<tsResponse>
  <permissions>
    <virtualConnection id="virtualconnection-id"
      name="virtual-connection-name">
      <owner id="user-id"/>
    </virtualConnection>
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!--   ... additional capabilities ...   -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!--   ... additional capabilities ...   -->
      </capabilities>
    </granteeCapabilities>
    <!--   ... additional granteeCapability sets ...   -->
  </permissions>
</tsResponse>
```

#### Version

Version 3.23 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/v0.0/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>400009</td><td>Invalid capability</td><td>The specified capability is invalid for a virtual connection. Valid capabilities for a virtual connection are <span class="api-command-ref">Read</span>, <span class="api-command-ref">Connect</span>, <span class="api-command-ref">Overwrite</span>, <span class="api-command-ref">ChangeHierarchy</span>, <span class="api-command-ref">Delete</span>, and <span class="api-command-ref">ChangePermissions</span>.</td></tr><tr><td>403</td><td>403004</td><td>Permissions setting forbidden</td><td>The user tried to change permissions for a virtual connection but doesn't have the permission to change them.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The specified site doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404002</td><td>User not found</td><td>The user specified in the request body doesn't correspond to an existing user.</td></tr><tr><td>404</td><td>404012</td><td>Group not found</td><td>The group specified in the request body doesn't correspond to an existing group.</td></tr><tr><td>404</td><td>404013</td><td>Capability not assigned</td><td>The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny).</td></tr><tr><td>404</td><td>404014</td><td>Capability not found</td><td>A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than <span class="api-command-ref">Allow</span> or <span class="api-command-ref">Deny</span> for any mode value.</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><tr><td>400</td><td>409004</td><td>Invalid LUID</td><td>The virtual connection LUID in the URI was not found.</td></tr></tbody></table>

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

#### Example

`curl --location --request PUT 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest> <permissions> <granteeCapabilities> <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" /> <capabilities> <capability name="read" mode="allow" /> </capabilities> </granteeCapabilities> </permissions> </tsRequest>'`

## Add Virtual Connection to Server Schedule

Adds a task to refresh a virtual connection to an existing server schedule on Tableau Server.  
_For Tableau Cloud, see [Create Cloud Extract Refresh Task](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm#create_cloud_extract_refresh_task)._

This method identifies and refreshes only the tables in the virtual connection that are configured as extracts; live tables are ignored.

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

**License**: Data Management, Enterprise, Server+, Cloud+, or Tableau+ Bundle.

**Permissions**: Tableau Server users who are not server administrators or site administrators can only add a virtual connection to a schedule if they own the virtual connection, or are the project leader for the project that contains the virtual connection.

**Access Scope**: `tableau:schedules:update`

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/schedules/schedule-id/virtualconnections

#### 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/v0.0/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">schedule-id</span></td><td>The LUID for the schedule that you are associating with the virtual connection.</td></tr></tbody></table>

#### Request Body

```
<tsRequest>
  <task>
    <extractRefresh transactionLevel="transaction-level" incremental="incremental-flag">
      <virtualConnection id="virtualconnection-id" />
      <startingItemIds>
        <startingItemId>starting-item-id</startingItemId>
        <!-- . . . more <startingItemId> elements . . . -->
      </startingItemIds>
    </extractRefresh>
  </task>
</tsRequest>
```

#### Attribute 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">transaction-level</span>
                                </td>
                                <td>
                                    <p>Optional. <span class="uicontrol">DATABASE</span> or <span class="uicontrol">TABLE</span>. Default is <span class="uicontrol">DATABASE</span>.</p>
                                    <ul>
                                        <li>If set to <span class="uicontrol">DATABASE</span>: If any table extract refresh fails, none of the extracts are updated.</li>
                                        <li>If set to <span class="uicontrol">TABLE</span>: If a table extract fails, only that table's extract isn't updated.</li>
                                    </ul>
                                </td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">incremental-flag</span>
                                </td>
                                <td>
                                    <p>Optional, boolean. Default is <span class="uicontrol">false</span>.</p>
                                    <ul>
                                        <li>If set to <span class="uicontrol">false</span>, do a full refresh. Fully refresh all extracts including those configured for incremental extract.</li>
                                        <li>If set to <span class="uicontrol">true</span>, do an incremental refresh. Add new rows to incremental extracts. Full refresh other extracts.</li>
                                    </ul>
                                </td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">virtualconnection-id</span>
                                </td>
                                <td>
							The LUID of the virtual connection to add to the schedule.
						</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">starting-item-id</span>
                                </td>
                                <td>The LUID of an extract table in the virtual connection. You may have more than one <code>&lt;startingItemId&gt;</code> element inside of a <code>&lt;startingItemIds&gt;</code> element.</td>
                            </tr>
                        </tbody>
                    </table>

#### cURL Request Example

```
curl --request PUT 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/virtualconnections' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest><task><extractRefresh><virtualConnection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" /></extractRefresh></task></tsRequest>'
```

#### Response Code

200

#### Response Body

```
<tsResponse>
  <task>
    <extractRefresh id="9dd16fd7-8bbc-4c0d-9f75-9c7330a29396"
      priority="50"
      consecutiveFailedCount="0"
      type="ExtractServiceFullRefreshExtractTask"
      transactionLevel="DATABASE">
      <schedule id="c09d0586-80b3-4bb4-a1fa-508436243792"
        name="Weekday early mornings"
        state="Active"
        priority="50"
        createdAt="2026-07-15T12:28:01Z"
        updatedAt="2026-07-17T07:11:19Z"
        type="Extract"
        frequency="Weekly"
        nextRunAt="2026-07-20T04:00:00Z"/>
      <virtualConnection id="e3ebe049-8f94-4501-8fb0-faba6ccbbc85"/>
      <startingItemIds>
        <startingItemId>3577de68-2779-4962-b13d-3265ec98a4cb</startingItemId>
      </startingItemIds>
    </extractRefresh>
  </task>
</tsResponse>
```

#### Errors

<table class="api-error-table">
                        <colgroup>
                            <col class="api-error-table-col-1" style="width: 56px;">
                            <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>

                            </tr>
                            <tr>
                                <td>400</td>
                                <td>400223</td>
                                <td>Virtual connection table not found.</td>
                                <td>A LUID in <code>startingItemIds</code> is not an extract-eligible table on the virtual connection.</td>
                            </tr>
                            <tr>
                                <td>400</td>
                                <td>400225</td>
                                <td>Duplicate virtual connection table.</td>
                                <td><code>startingItemIds</code> contains the same table LUID more than once.</td>
                            </tr>
                            <tr>
                                <td>400</td>
                                <td>404049</td>
                                <td>No virtual connection specified.</td>
                                <td>The request body must include a virtual connection in the <code>extractRefresh</code> element.</td>
                            </tr>
                            <tr>
                                <td>400</td>
                                <td>409004</td>
                                <td>Invalid parameter.</td>
                                <td><code>startingItemIds</code> contains a value that is not a valid LUID.</td>
                            </tr>
                            <tr>
                                <td>400</td>
                                <td>409090</td>
                                <td>No extract-eligible tables.</td>
                                <td>The virtual connection has no active revision, or none of its tables are configured for extract refresh.</td>
                            </tr>
                            <tr>
                                <td>403</td>
                                <td>403078</td>
                                <td>Unable to create the task.</td>
                                <td>
                                    <p>One of the following applies:</p>
                                    <ul>
                                        <li>The user is not a system or site administrator and does not own the virtual connection.</li>
                                        <li>The virtual connection already has a refresh scheduled on this schedule.</li>
                                        <li>The virtual connection is in a personal space.</li>
                                        <li>The extract refresh operation is not allowed for the virtual connection.</li>
                                    </ul>
                                </td>
                            </tr>
                            <tr>

                            </tr>
                            <tr>
                                <td>404</td>
                                <td>404023</td>
                                <td>Schedule not found.</td>
                                <td>Check the schedule LUID.</td>
                            </tr>
                            <tr>
                                <td>404</td>
                                <td>404049</td>
                                <td>Virtual connection not found.</td>
                                <td>Check the virtual connection LUID.</td>
                            </tr>
                            <tr>
                                <td>405</td>
                                <td>405000</td>
                                <td>Method not allowed.</td>
                                <td>Request type must be PUT.</td>
                            </tr>
                        </tbody>
                    </table>

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

## Create Cloud Extract Refresh Task

Creates a custom schedule for an extract refresh on Tableau Cloud. The target of the schedule can be a data source, a workbook, or a virtual connection.  
_For Tableau Server, see [Add data source to server schedule](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_data_source_to_schedule), [Add workbook to server schedule](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_workbook_to_schedule), and [Add virtual connection to server schedule](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#add_virtual_connection_to_schedule)._

**Version:** Available in API 3.20 (Tableau Cloud June 2023) and later. Virtual connection support added in API 3.30. Not available for Tableau Server. _[Version Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)_

**License:** No additional license required for a data source or workbook target. A virtual connection target requires Data Management, Enterprise, Server+, Cloud+, or Tableau+ Bundle.

**Permissions:** Administrators and any user with the creator role can create a custom schedule for an extract refresh.  _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:tasks:create

- 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-id/tasks/extractRefreshes

#### 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/v0.0/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></tbody></table>

#### Request Body

```
<tsRequest>
  <extractRefresh type="FullRefresh">
    <workbook id="54321fd-6365-44d5-925b-644e5281b605" />
  </extractRefresh>
  <schedule frequency="Daily">
    <frequencyDetails start="18:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Sunday"/>
        <interval weekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>
```

```
{
  "extractRefresh": {
    "type": "FullRefresh",
    "workbook": {
      "id": "54321fd-6365-44d5-925b-644e5281b605"
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
```

#### Request Attributes

All request attributes are **required** to create a custom schedule for an extract refresh, except where noted below.

<table class="api-parameters-table">
                        <colgroup>
                            <col width="30%">
                            <col width="70%">
                        </colgroup>
                        <tbody>
                            <tr>
                                <td><code>extractRefresh type</code>
                                </td>
                                <td>The type of extract refresh being scheduled. Valid values include:
						<ul><li><code>FullRefresh</code></li><li><code>IncrementalExtract</code></li></ul></td>
                            </tr>
                            <tr>
                                <td><code>extractRefresh transactionLevel</code>
                                </td>
                                <td>
                                    <p><i>(Optional) :</i> Only used with a virtual connection.</p>
                                    <p>Optional. <span class="uicontrol">DATABASE</span> or <span class="uicontrol">TABLE</span>. Default is <span class="uicontrol">DATABASE</span>.</p>
                                    <ul>
                                        <li>If set to <span class="uicontrol">DATABASE</span>: If any table extract refresh fails, none of the extracts are updated.</li>
                                        <li>If set to <span class="uicontrol">TABLE</span>: If a table extract fails, only that table's extract isn't updated.</li>
                                    </ul>
                                </td>
                            </tr>
                            <tr>
                                <td><code>workbook id</code> <br> or <code>datasource id</code> <br> or <code>virtualConnection id</code></td>
                                <td>The LUID of the workbook, data source, or virtual connection that is the target of the custom schedule.</td>
                            </tr>
                            <tr>
                                <td><code>startingItemId</code>
                                </td>
                                <td>
                                    <p>Only used with a virtual connection, when <code>extractRefresh type</code> is <code>FullRefresh</code></p>
                                    <p>The LUID of an extract table in the virtual connection. You may have more than one <code>&lt;startingItemId&gt;</code> element inside of a <code>&lt;startingItemIds&gt;</code> element. See Virtual Connection Example.</p>
                                </td>
                            </tr>
                            <tr>
                                <td><code>tableLuid</code>
                                </td>
                                <td>
                                    <p>Only used with a virtual connection, when <code>extractRefresh type</code> is <code>IncrementalExtract</code></p>
                                    <p>The LUID of an extract table in the virtual connection. You may have more than one <code>&lt;tableLiud&gt;</code> element inside of a <code>&lt;tableLiuds&gt;</code> element. See Virtual Connection Example.</p>
                                </td>
                            </tr>
                        </tbody>
                    </table> <table class="api-parameters-table">
                        <colgroup>
                            <col width="30%">
                            <col width="70%">
                        </colgroup>
                        <tbody>
                            <tr>
                                <td><code>schedule frequency</code>
                                </td>
                                <td><i>(Required to create subscription) enumeration:</i> The scheduled frequency for triggering the task. Valid values include:
							<ul><li>Hourly</li><li>Daily</li><li>Weekly</li><li>Monthly</li></ul></td>
                            </tr>
                            <tr>
                                <td><code>frequencyDetails start</code>
                                </td>
                                <td><i>(Required to create subscription) time:</i> If the schedule frequency is <code>Daily, Weekly, or Monthly</code>, then <code>start</code>
						is the time of day on which scheduled jobs should run. If the frequency is <code>Hourly</code>, then <code>start</code> is the beginning of the
								time range during which jobs should be started. The valid format is <code>HH:MM:SS</code>.
					</td>
                            </tr>
                            <tr>
                                <td><code>frequencyDetails end</code>
                                </td>
                                <td>
                                    <p><i>(Required to create subscription) time:</i> If the schedule frequency is <code>Hourly</code>, or <code>Daily</code> with an interval of
							<code>hours</code> less than <code>24</code>, then <code>end</code> is the time of day on which scheduled jobs should stop being run.
							The valid format is <code>HH:MM:SS</code>. Time should be specified in 5 minute increments and the difference between start
							and end times should be increments of 60 minutes. For example, a valid <code>frequencyDetail</code> would be:
</p><pre><code>&lt;frequencyDetail start="20:45:00" end="21:45:00"&gt;
  . . .
&lt;/frequencyDetail&gt;</code></pre>
                                </td>
                            </tr>
                            <tr>
                                <td><code>interval <i>{interval type}</i></code>
                                </td>
                                <td><i>(Required to create subscription) string:</i> Defines when and how often a scheduled job executes within the time parameters set in the <code>start</code> and <code>end</code>
							 values of the <code>frequencyDetails</code> of the <code>schedule</code>. The type and valid values for
							an interval expression depend on the declared <code>frequency</code> of the <code>schedule</code> as follows:<br><br><table><colgroup><col width="20%"><col width="80%"></colgroup><tbody><tr align="left"><th><b>Frequency</b></th><th><b>Valid interval values</b></th></tr><tr><td><code>Hourly</code></td><td> The value of an interval for an <code>Hourly</code> schedule can be only one of either:
							<ul><li><code>hours="1"</code>
									The number of hours between jobs. <code>1</code> is the only valid value.</li><li><code>minutes="60"</code>
									 The number of minutes between jobs. <code>60</code> is the only valid value.</li><li><code>weekDay="<i>weekday"</i></code> The weekday(s) the job will be run on.
									Valid values are:  <code>Sunday, Monday, Tuesday, Wednesday,
								 	Thursday, Friday, and Saturday</code>. <br><br>
									For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in <code>frequencyDetails</code>
									use an interval like:
											<pre><code>&lt;intervals&gt;
  &lt;interval hours="1"/&gt;
  &lt;interval weekDay="Sunday"/&gt;
  &lt;interval weekDay="Wednesday"/&gt;
&lt;intervals&gt;</code></pre></li></ul><br></td></tr><tr><td><code>Daily</code></td><td>
									The value of <code>Daily</code> can have multiple <code>weekday</code> elements, but only one <code>hours</code> declaration.
										An <code>hours</code> interval is required.
									<ul><li><code>hours="<i>interval</i>"</code> The interval between execution of jobs on the weekday(s) specified.
											Valid values are <code>2, 4, 6, 8, 12, or 24</code>. Note that if the <code><i>interval</i></code> value of a daily schedule
												is less than <code>24</code>, a <code>frequencyDetail end</code> time must be supplied. </li><li><code>weekDay="<i>weekday</i>"</code> The weekday(s) the job will be run on.
											Valid values are:  <code>Sunday, Monday, Tuesday, Wednesday,
										 	Thursday, Friday, or Saturday</code>. <br><br>
											For example, to schedule to run a job every 4 hours	on Sunday and Wednesday, during the time range specified in <code>frequencyDetails</code>
											use an interval like:<br><pre><code>&lt;intervals&gt;
  &lt;interval hours="4"/&gt;
  &lt;interval weekDay="Sunday"/&gt;
  &lt;interval weekDay="Wednesday"/&gt;
&lt;intervals&gt;</code></pre></li></ul></td></tr><tr><td><code>Weekly</code></td><td><code>weekDay="<i>weekday</i>"</code>
												The day of the week the schedule should run on. You can only specify a single day for a Weekly schedule. Valid values are:
											<code>Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.</code></td></tr><tr><td><code>Monthly</code></td><td> <p>The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval:</p><p>Specify the day(s) using the number of the day in the month;
											</p><ul><li><code>monthDay="<i>day</i>"</code> The number of the day of the month. Valid values are the whole numbers
												<code>1</code> to <code>31</code> or <code>LastDay</code>. If you specify <code>monthDay</code> by day number
												then you can use multiple <code>interval</code> instances to choose for the job to
												run on multiple days in the month. If you use <code>LastDay</code> then only one instance of <code>interval</code>
												can be used in the schedule to specify the last day of the month.</li></ul><p></p><p>Specify the day by describing which occurrence of a weekday within the month.
										</p><ul><li><code>monthDay="<i>occurrence_of_weekday</i>" Weekday="<i>weekday</i>"</code>
													The occurrence of the specified weekday within the month when a job should be run.
													Valid values for <code><i>occurrencee_of_weekday</i></code> are	<code>First, Second, Third, Fourth, Fifth, or LastDay</code>.
													Valid values for <code><i>weekday</i></code> are
													<code>Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday</code>.
													If the value is <code>lastDay</code> then the job will run on
													the last occurrence of the specified weekday in the month.<br><br>
													For example, to make a schedule that that would run a job on the third Thursday of each month, you would use:<br><pre><code>&lt;interval monthDay="Third" weekDay="Thursday"/&gt;</code></pre></li></ul><p></p></td></tr></tbody></table></td>
                            </tr>
                        </tbody>
                    </table>

#### Virtual Connection Example

When the target is a virtual connection, use `virtualConnection id` instead of `workbook id` or `datasource id`. The following example includes only the `<extractRefresh>` and child elements for brevity; see the primary example above for the a full request without the elements that apply only to virtual connections.

_Incremental refresh of specific tables, with a table-level transaction:_

```
<extractRefresh type="IncrementalRefresh" transactionLevel="TABLE">
  <virtualConnection id="33a16da9-e96b-4190-83ed-c85192683052" />
  <tableLuids>
    <tableLuid>b4e39d59-19c3-4380-8ea4-9bfa4ed8fb84</tableLuid>
    <!-- . . . more <tableLuid> elements . . . -->
  </tableLuids>
</extractRefresh>
```

#### cURL Request Example

`curl --location --request POST "https://10ax.online.tableau.com/api/3.29/sites/a946d998-2ead-4894-bb50-1054a91dcab3/tasks/extractRefreshes" --header "Content-Type: application/xml" --data "<tsRequest> <extractRefresh type='FullRefresh'> <workbook id='0057ccac-872a-11e5-bb51-f763326b1350' /> </extractRefresh> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> </intervals> <intervals> <interval weekDay='Sunday'/> </intervals> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"`

200

#### Response Body

When the target is a virtual connection, the response's `extractRefresh` element includes a `transactionLevel` attribute and a `virtualConnection` element (with a sibling `startingItemIds`, if starting items were specified) in place of `datasource` or `workbook`.

```
<tsResponse>
  <extractRefresh
    id="13237fd-6365-44d5-925b-644e5281b605"
    consecutiveFailedCount="0"
    type="IncrementalRefresh" >
      <datasource id="0057ccac-872a-11e5-bb51-f763326b1350" />
  </extractRefresh>
  <schedule id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
    createdAt="2023-04-06T23:43:12-0700"
    updatedAt="2023-04-06T23:43:12-0700"
    frequency="Daily"
    nextRunAt="2023-04-06T23:43:12-0700">
        <frequencyDetails start="18:30:00" end="23:30:00">
        <intervals>
          <interval hours="4"/>
          <interval weekDay="Sunday"/>
          <interval weekDay="Wednesday"/>
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>
```

```
{
  "extractRefresh": {
    "id": "13237fd-6365-44d5-925b-644e5281b605",
    "consecutiveFailedCount": "0",
    "type": "IncrementalRefresh",
    "datasource": {
      "id": "0057ccac-872a-11e5-bb51-f763326b1350"
    }
  },
  "schedule": {
    "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
    "createdAt": "2023-04-06T23:43:12-0700",
    "updatedAt": "2023-04-06T23:43:12-0700",
    "frequency": "Daily",
    "nextRunAt": "2023-04-06T23:43:12-0700",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}
```

#### 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>400225</td><td>Duplicate starting item</td><td><code>startingItemIds</code> contains a duplicate table LUID.</td></tr><tr><td>409</td><td>409090</td><td>Extract operation not allowed</td><td>The virtual connection has no extract-configured tables; all tables are live.</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>404</td><td>404026</td><td>Task not found</td><td>The task for the extract refresh could not be found.</td></tr><tr><td>409</td><td>409004</td><td>invalid parameter value</td><td>The request is malformed or contains an invalid or missing schedule or interval parameter value. When the difference between <code>start</code> and <code>end</code> times are not increments of one hour, this error will result.</td></tr></tbody></table>

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

## Delete Extracts from Virtual Connection

Deletes the extracts from a virtual connection, which changes it from extract to live mode.

This operation applies to the entire virtual connection. You can't target individual tables.

**Version**: Available in API 3.30.

**License**: Data Management, Enterprise, Server+, Cloud+, or Tableau+ Bundle.

**Permissions**: Extracts for virtual connections can be deleted by Tableau server or site administrators, and by users who own the virtual connection or are an owner or leader of the project where the virtual connection resides.

**Access Scope**: `tableau:extracts:delete`

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

POST /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/deleteExtract

#### 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/v0.0/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">virtualconnection-id</span></td><td>The LUID for the virtual connection whose extract is to be deleted.</td></tr></tbody></table>

#### Request Body

The request body is an empty tsRequest element.

              `<tsRequest/>`
              
            

```
{}
```

#### cURL Request Example

```
curl --request POST 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/deleteExtract' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest/>'
```

#### Response Code

204 No Content

#### 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>409128</td><td>No extract to delete.</td><td>The virtual connection has no extract. Neither the active revision nor any of its tables has extracts enabled.</td></tr><tr><td>400</td><td>409099</td><td>Unable to delete the extract.</td><td>A generic error occurred while converting the virtual connection to live and deleting its extract.</td></tr><tr><td>403</td><td>409098</td><td>User not authorized to delete the extract.</td><td>The user must be able to see the virtual connection and must have permission to convert its extract to live.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found.</td><td>Check the virtual connection LUID. This error also occurs if the virtual connection has no active revision.</td></tr></tbody></table>

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

## Delete Tag from Virtual Connection

Deletes a tag from a virtual connection.

**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:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** You must have the View permission for the virtual connection and your site role must be at least Explorer.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:virtual\_connection\_tags:delete

- 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

DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-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/v0.0/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">virtualconnection-id</span></td><td>The LUID for the virtual connection.</td></tr><tr><td><span class="api-placeholder">tag-name</span></td><td>The text of the tag.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request Example

`curl --location --request DELETE 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/tags/office' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'`

#### Response Code

204

#### 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>400077</td><td>Error deleting tag</td><td>There was a problem deleting the tag from the specified virtual connection.</td></tr><tr><td>403</td><td>403004</td><td>Deleting tags forbidden</td><td>The user doesn't have permissions to add delete tags from the virtual connection.</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>404004</td><td>Virtual connection not found</td><td>The virtual connection ID in the URI doesn't correspond to an existing virtual connection.</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 virtual 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">DELETE</span>.</td></tr></tbody></table>

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

## Delete Virtual Connection

Deletes a virtual connection.

**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:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** You must have the Delete permission for the virtual connection and your site role must be at least Creator.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:virtual\_connections:delete

- 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

DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id

#### 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/v0.0/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">virtualconnection-id</span></td><td>The LUID for the virtual connection.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request Example

_(Use the icon in the top right corner to copy the text.)_

```
curl --request DELETE 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
```

#### Response Code

204

#### 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>403</td><td>403004</td><td>User not authorized.</td><td>Check to make sure the user has the required permissions.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found</td><td>Check the virtual connection LUID.</td></tr><tr><td>409</td><td>409122</td><td>Generic error</td><td>An unknown error occurred.</td></tr></tbody></table>

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

## Delete Virtual Connection Permission

Removes the specified virtual connection permission for the specified group or user.

#### URI

DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions/users/user-id/capability-name/capability-mode

#### 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/v0.0/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 virtual connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">virtualconnection-id</span>
                                        </td>
                                        <td>The ID of the virtual connection to remove the permission for.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">group-id</span>
                                        </td>
                                        <td>The LUID of the group to remove the permission for. A request does not need to include both a user and a group grantee.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">user-id</span>
                                        </td>
                                        <td>The LUID of the user to remove the permission for. A request does not need to include both a user and a group grantee.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">capability-name</span>
                                        </td>
                                        <td>
                                            <p>
                                    The capability to remove the permission for.
                                    Valid capabilities for a virtual connection are
                       <span class="api-command-ref">Read</span>,
                       <span class="api-command-ref">Connect</span>,
                       <span class="api-command-ref">Overwrite</span>,
                       <span class="api-command-ref">ChangeHierarchy</span>,
					   <span class="api-command-ref">Delete</span>, and
					   <span class="api-command-ref">ChangePermissions</span>.
					</p>
                                            <p>For more information, see <a href="https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm" class="xref">Permissions</a>.</p>
                                        </td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">capability-mode</span>
                                        </td>
                                        <td><span class="api-command-ref">Allow</span> to remove the allow permission, or <span class="api-command-ref">Deny</span> to
                                    remove the deny permission.</td>
                                    </tr>
                                </tbody>
                            </table>

#### Request Body

None

#### Permissions

You must be an administrator or have the Delete permission for the virtual connection (either explicitly or implicitly).

#### Required scope for JWT authorization

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

Authorize use of this method 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), or [Access Scopes for Connected Apps](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm) in the Tableau Cloud Help or [Access Scopes for Connected Apps](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) in the Tableau Server Help.

```
tableau:permissions:delete
```

#### Response Code

204

#### Response Body

None

#### Version

Version 3.23 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/v0.0/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>400009</td><td>Invalid capability</td><td>The specified capability is invalid for a virtual connection. Valid capabilities for a virtual connection are <span class="api-command-ref">Read</span>, <span class="api-command-ref">Connect</span>, <span class="api-command-ref">Overwrite</span>, <span class="api-command-ref">ChangeHierarchy</span>, <span class="api-command-ref">Delete</span>, and <span class="api-command-ref">ChangePermissions</span>.</td></tr><tr><td>403</td><td>403004</td><td>Permissions setting forbidden</td><td>The user tried to change permissions for a virtual connection but doesn't have the permission to change them.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The specified site doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404002</td><td>User not found</td><td>The user specified in the request body doesn't correspond to an existing user.</td></tr><tr><td>404</td><td>404012</td><td>Group not found</td><td>The group ID in the URI doesn't correspond to an existing group.</td></tr><tr><td>404</td><td>404013</td><td>Capability not assigned</td><td>The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny).</td></tr><tr><td>404</td><td>404014</td><td>Capability not found</td><td>A capability specified in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than <span class="api-command-ref">Allow</span> or <span class="api-command-ref">Deny</span> for any mode value.</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><tr><td>400</td><td>409004</td><td>Invalid LUID</td><td>The virtual connection LUID in the URI was not found.</td></tr></tbody></table>

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

#### Example

`curl --location --request DELETE 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/read/allow' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'`

## Download Virtual Connection

Downloads a virtual connection in `.tvcx` format.  
_To download a JSON representation of a virtual connection instead, see [Download Virtual Connection as JSON](#download_virtual_connection_as_json)._

A `.tvcx` file is a packaged virtual connection. You can publish a downloaded `.tvcx` file with [Publish Virtual Connection](#publish_virtual_connection).

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

**License**: Data Management, Enterprise, Server+, Cloud+, or Tableau+ Bundle.

**Permissions**: You must have the Overwrite permission for the virtual connection and your site role must be at least Creator, or you must be a site or server administrator.

**Access Scope**: `tableau:virtual_connections: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/virtualconnections/virtualconnection-id/content

#### 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/v0.0/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 virtual connection.</td></tr><tr><td><span class="api-placeholder">virtualconnection-id</span></td><td>The LUID of the virtual connection to download. To get the LUID, use <a href="#list_virtual_connections">List Virtual Connections</a>.</td></tr></tbody></table>

Unlike [Download Data Source](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#download_data_source), this method has no `includeExtract` parameter. If the virtual connection uses extracts, the download always includes them. Encrypted extracts are decrypted before packaging, so the downloaded `.tvcx` file can be published to any site.

#### Request Body

None

#### cURL Request Example

_(Use the icon in the top right corner to copy the text.)_

```
curl "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/content" -X GET -H "X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3" -o my-virtualconnection.tvcx
```

The response is a file that contains the virtual connection.

#### Response Code

200

#### Response Headers

`Content-Type: application/octet-stream`

`Content-Disposition: name="tableau_virtual_connection_content"; filename="virtualconnection-filename.tvcx"`

#### Response Body

The virtual connection in `.tvcx` format, a binary ZIP archive with the following contents:

```
virtualconnection-name.tvcx (ZIP)
  virtualconnection-name.tvc        The virtual connection schema (tables, columns,
                                    connections, and policy collection)
  Data/Extracts/*.hyper             Hyper extracts. Present only if the virtual
                                    connection uses extracts.
```

A `.tvcx` file for a virtual connection that has only live tables contains just the `.tvc` schema file.

#### 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>400200</td><td>Download virtual connection error</td><td>The virtual connection ID is not a valid ID, or the .tvcx file could not be built.</td></tr><tr><td>403</td><td>403174</td><td>Download virtual connection forbidden</td><td>The user does not have permission to download the virtual connection.</td></tr><tr><td>404</td><td>404000</td><td>Site not found</td><td>The site LUID in the URI doesn't correspond to an existing site.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found</td><td>The virtual connection does not exist.</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/v0.0/api/rest_api/en-us/REST/rest_api_concepts_errors.htm).

## Download Virtual Connection as JSON

Downloads a JSON-representation of a virtual connection.  
_To download a virtual connection as a `.tvcx` file, see [Download Virtual Connection](#download_virtual_connection)._

**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:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** You must have the Overwrite permission for the virtual connection and your site role must be at least Creator.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:virtual\_connections:read

- 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

GET /api/api-version/sites/site-id/virtualconnections/virtualconnection-id

#### 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/v0.0/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">virtualconnection-id</span></td><td>The LUID for the virtual connection.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request Example

_(Use the icon in the top right corner to copy the text.)_

```
curl "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd" -X GET -H "Content-Type: application/xml" -H "X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3"
```

#### Response Code

200

#### Response Body

```
<tsResponse>
  <virtualConnection name="virtualconnection-name">
    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"/>
    <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    <content>virtualconnection-as-json</content>
  </virtualConnection>
</tsResponse>
```

```
{
  "virtualConnection": {
    "project": {
      "id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
    },
    "owner": {
      "id": "9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"
    },
    "content": "virtualconnection-as-json",
    "name": "virtualconnection-name"
  }
}
```

The response body contains the project LUID, owner LUID, and a content element (for XML output) or content property (for JSON output) containing the virtual connection schema rendered as JSON.

If the response is XML, the content element is unescaped JSON.

If the response is JSON, the content property is escaped JSON.

#### 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>400200</td><td>Generic error</td><td>An unknown error occurred.</td></tr><tr><td>403</td><td>403174</td><td>User not authorized.</td><td>Check to make sure the user has the required permissions.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found</td><td>Check the virtual connection LUID.</td></tr></tbody></table>

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

## Download Virtual Connection Revision as JSON

Downloads a JSON-representation of an earlier revision of a virtual connection.

**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:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** You must have the Overwrite permission for the virtual connection and your site role must be at least Creator.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:virtual\_connections:read

- 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

GET /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/revisions/revision-number

#### 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/v0.0/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">virtualconnection-id</span></td><td>The LUID for the virtual connection.</td></tr><tr><td><span class="api-placeholder">revision-number</span></td><td>The revision number (revisionNumber) of the virtual connection, as returned by the <a href="#get_virtual_connection_revisions">Get Virtual Connection Revisions</a> method. This is an integer, not a LUID.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request Example

_(Use the icon in the top right corner to copy the text.)_

```
curl 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/revisions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'
```

#### Response Code

200

#### Response Body

```
<tsResponse>
  <virtualConnection name="virtualconnection-name">
    <project id="project-id"/>
    <owner id="owner-id"/>
    <content>virtualconnection-as-json</content>
  </virtualConnection>
</tsResponse>
```

```
{
  "virtualConnection": {
    "project": {
      "id": "project-id"
    },
    "owner": {
      "id": "owner-id"
    },
    "content": "virtualconnection-as-json",
    "name": "virtualconnection-name"
  }
}
```

The response body contains the project LUID, owner LUID, and a content element (for XML output) or content property (for JSON output) containing the virtual connection schema rendered as JSON.

If the response is XML, the content element is unescaped JSON.

If the response is JSON, the content property is escaped JSON.

#### 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>400200</td><td>Generic error</td><td>An unknown error occurred. Check to make sure the revision number is a revision and not the active virtual connection.</td></tr><tr><td>403</td><td>403174</td><td>User not authorized.</td><td>Check to make sure the user has the required permissions.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found</td><td>Check the virtual connection LUID. Check that the revision number exists.</td></tr></tbody></table>

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

## List Virtual Connection Revisions

Lists revisions for a virtual connection.

**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:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** You must have the Overwrite permission for the virtual connection and your site role must be at least Creator.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:virtual\_connections:read

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

**Note:** This method can only succeed if version history is enabled for the specified site. 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/virtualconnections/virtual-connection-id/revisions

GET /api/api-version/sites/site-id/virtualconnections/virtual-connection-id/revisions/?pageSize\=page-size&pageNumber\=page-number

#### 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/v0.0/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">virtual-connection-id</span></td><td>The LUID for the virtual connection.</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/v0.0/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/v0.0/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request Example

_(Use the icon in the top right corner to copy the text.)_

```
curl 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/revisions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3 '
```

#### Response Code

200

#### Response Body

```
<tsResponse>
  <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="page-count"/>
  <revisions>
    <revision revisionNumber="revision-number" publishedAt="datetime" deleted="deleted-flag" current="current-flag">
      <publisher id="publisher-id" name="publisher-username"/>
    </revision>
    <revision revisionNumber="revision-number" publishedAt="datetime" deleted="deleted-flag" current="current-flag">
      <publisher id="publisher-id" name="publisher-username"/>
    </revision>
    <!-- ...Additional revisions... -->
</revisions>
</tsResponse>
```

```
"pagination": {
    "pageNumber": "page-number",
    "pageSize": "page-size",
    "totalAvailable": "page-count"
  },
  "revisions": {
    "revision": [
      {
        "publisher": {
          "id": "publisher-id",
          "name": "publisher-username"
        },
        "revisionNumber": "revision-number",
        "publishedAt": "datetime",
        "deleted": deleted-flag,
        "current": current-flag
      },
      {
        "publisher": {
          "id": "publisher-id",
          "name": "publisher-username"
        },
        "revisionNumber": "revision-number",
        "publishedAt": "datetime",
        "deleted": deleted-flag,
        "current": current-flag
      },
      {
        ...Additional revisions...
      }
    ]
  }
}
```

The `current` property of a revision shows `false` for all revisions except for the currently active virtual connection revision, in which case it shows `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>400058</td><td>Generic error</td><td>An unknown error occurred.</td></tr><tr><td>403</td><td>403054</td><td>User not authorized.</td><td>User doesn't have permissions to revisions on this virtual connection. Check the user's permissions.</td></tr><tr><td>403</td><td>403173</td><td>User not authorized.</td><td>User forbidden from listing virtual connection revisions. Check the user's permissions and site role.</td></tr><tr><td>403</td><td>403053</td><td>Revision history is disabled on the site.</td><td>Check the revision history setting.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found</td><td>Check the virtual connection LUID.</td></tr></tbody></table>

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

## List Virtual Connections

Returns a list of available virtual connection names and IDs.

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

**License:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** By default, all users can view virtual connections.  _[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.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

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

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

GET /api/api-version/sites/site-id/virtualconnections/?sort=sort-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/v0.0/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 that contains the virtual connection.</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/v0.0/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/v0.0/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</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 virtual connection 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/v0.0/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm">Filtering and Sorting</a>.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request Example

`curl --location --request GET "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections" \ --header "X-Tableau-Auth: 3bl3fJb0T6qxhaCqneNhWg"Nmv6zrJfYeiiovCuEs2grrBAZlREbRGl"a946d998-2ead-4894-bb50-1054a91dcab3"`

#### Response Code

200

#### Response Body

```
<tsResponse>   <pagination pageNumber="page-number" pageSize="page-size" totalAvailable="total-available" />  <virtualConnections>    <virtualConnection       createdAt="datetime-created"       hasExtracts="has-extracts-flag"       id="virtual-connection-id"       isCertified="is-certified-flag"       name="virtualconnection-name"       updatedAt="datetime-updated"       webpageUrl="web-page-url"/>  </virtualConnections></tsResponse>
```

```
{  "pagination": {    "pageNumber": "page-number",    "pageSize": "page-size",    "totalAvailable": "total-available"  },  "virtualConnections": {    "virtualConnection": {      "createdAt": "datetime-created",      "hasExtracts": "has-extracts-flag",      "id": "virtual-connection-id",      "isCertified": "is-certified-flag",      "name": "virtualconnection-name",      "updatedAt": "datetime-updated",      "webpageUrl": "web-page-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><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>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 virtual connections 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>A parameter in the request body is missing or invalid.</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 <b>GET</b>.</td></tr></tbody></table>

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

## List Virtual Connection Database Connections

Returns information about database connections in the specified virtual connection

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

**License:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** Users who are not administrators can query a virtual connection only if they have explicit or implicit \[Connect\] (view) permission for the virtual connection.  _[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.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

GET /api/api-version/sites/site-id/virtualconnections/virtual-connection-id/connections

GET /api/api-version/sites/site-id/virtualconnections/virtual-connection-id/connections?pageSize=page-size&pageNumber=page-number  

#### 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/v0.0/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 that contains the virtual connection.</td></tr><tr><td><span class="api-placeholder">virtual-connection-id</span></td><td>The LUID for the virtual connection that includes the database connections.</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/v0.0/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/v0.0/api/rest_api/en-us/REST/rest_api_concepts_paging.htm">Paginating Results</a>.</td></tr></tbody></table>

#### Request Body

None

#### cURL Request Example

`curl --location --request GET "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections/26bc30d8-90d6-4af1-922d-ac285e7b08fb/connections?X-Tableau-Auth =3bl3fJb0T6qxhaCqneNhWg"Nmv6zrJfYeiiovCuEs2grrBAZlREbRGl"a946d998-2ead-4894-bb50-1054a91dcab3"`

#### Response Code

200

#### Response Body

```
<tsResponse>  <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" />  <virtualConnectionConnections>    <connection      id="connection-id"       serverAddress="server-address"       dbClass="database-type"       serverPort="port-number"       userName="connection-user-name"/>  </virtualConnectionConnections></tsResponse>
```

```
{  "pagination": {    "pageNumber": "pageNumber",    "pageSize": "page-size",    "totalAvailable": "total-available"  },  "virtualConnectionConnections": {    "connection": {      "id": "connection-id",      "serverAddress": "server-address",      "dbClass": "database-type",      "serverPort": "port-number",      "userName": "connection-user-name"    }  }}
```

#### 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 virtual connections 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>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>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 <b>GET</b>.</td></tr></tbody></table>

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

## Publish Virtual Connection

Publishes a virtual connection on the specified site, either from a packaged virtual connection file (`.tvcx`) or from a downloaded JSON representation.

If the virtual connection does not exist, it is published as a new virtual connection. If it already exists and you choose to overwrite it, the virtual connection is published as a revision of the existing virtual connection.

You can publish in either of these ways:

- **`.tvcx` file**. Send a packaged virtual connection file, as returned by [Download Virtual Connection](#download_virtual_connection). A `.tvcx` file can include extracts.
- **JSON representation**. Send the virtual connection schema, as returned by [Download Virtual Connection as JSON](#download_virtual_connection_as_json), inline in the request body.

**Version**: Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later. Support for publishing a `.tvcx` file added in API 3.30.

**License**: Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions**: You must have the Overwrite permission for the virtual connection and your site role must be at least Creator, or you must be a Tableau administrator.

**Access Scope**: `tableau:virtual_connections:create`. 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).

To publish a `.tvcx` file, you can call this method in two ways. You can publish a virtual connection in a single request. To do that, you include the content of the `.tvcx` file in the body of the request. The maximum size of a file that can be published in a single request is about 64 MB.

Alternatively, you can publish a `.tvcx` file in multiple parts. To do that, you initiate a file upload by calling [Initiate File Upload](https://help.tableau.com/v0.0/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/v0.0/api/rest_api/en-us/REST/rest_api_ref_publishing.htm#append_to_file_upload), and then commit the upload by calling Publish Virtual Connection. In this case, Publish Virtual Connection doesn't contain the file to publish. We recommend this approach for files larger than about 64 MB, such as files that include large extracts.

**Virtual connections with extracts**  
A `.tvcx` file for a virtual connection that uses extracts contains the Hyper extract files, in addition to the virtual connection schema. A `.tvcx` file for a live virtual connection contains only the schema. This method accepts both kinds of file.

**Draft or active**  
When you publish a JSON representation, the virtual connection can be published as a draft or as an active virtual connection, as set by the `publishAsDraft` parameter. A virtual connection that you publish from a `.tvcx` file is always published as an active virtual connection, whether or not the file includes extracts. The `publishAsDraft` parameter does not apply to a `.tvcx` file.

For more information, see [Publishing Resources](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_concepts_publish.htm).

#### URI

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

POST /api/api-version/sites/site-id/virtualconnections?publishAsDraft=publish-as-draft-flag

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

POST /api/api-version/sites/site-id/virtualconnections?uploadSessionId=upload-session-id&overwrite=overwrite-flag

#### 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/v0.0/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 to publish to.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">publish-as-draft-flag</span>
                                </td>
                                <td>(Optional) <span class="api-command-ref">true</span> to publish the virtual connection as a draft, or <span class="api-command-ref">false</span> to publish it as an active virtual connection. The default is <span class="api-command-ref">true</span>. This parameter applies only when you publish a JSON representation. The parameter is case sensitive.
                        <p>If the virtual connection contains an extract, the <span class="api-command-ref">publishAsDraft</span> parameter value is ignored and the virtual connection is published as a draft.</p><p class="note"><b>Note:</b> If you are using the REST&nbsp;API to publish a virtual connection as a draft, note the virtual connection's LUID (<code>virtualconnection id</code>) in the response body. Use that LUID to build a URL to further edit, create extracts for, or publish the virtual connection using the virtual connection editor in the regular web interface. For more information, see "Draft in Progress"&nbsp;in the <a href="https://help.tableau.com/current/online/en-us/dm_vconn_publish_save.htm#draft-in-progress" target="_blank">Tableau Cloud Product Help</a> and <a href="https://help.tableau.com/current/server/en-us/dm_vconn_publish_save.htm#draft-in-progress" target="_blank">Tableau Server Product Help</a>.</p></td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">overwrite-flag</span>
                                </td>
                                <td><span class="api-command-ref">true</span> to overwrite a virtual connection that has the same name in the target project, or <span class="api-command-ref">false</span>
                                        to fail if the specified virtual connection 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 virtual connection doesn't already exist, the operation succeeds.
                    </td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">upload-session-id</span>
                                </td>
                                <td>(Optional, <code>.tvcx</code> files only) 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/v0.0/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>
                        </tbody>
                    </table>

#### Request Body

The request body depends on whether you publish a `.tvcx` file or a JSON representation.

**Publishing a .tvcx file**

The content type in the header of requests to publish a `.tvcx` file must use the mixed multipart content type with a boundary string definition, in the form of: `Content-Type: multipart/mixed; boundary=boundary-string`. The server uses this content type to tell a `.tvcx` request from a JSON request. A request with any other content type, such as `application/octet-stream` or `multipart/form-data`, is handled as a request to publish a JSON representation and fails.

**Publishing a file in the request body**

```
--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml

<tsRequest>
  <virtualConnection name="virtualconnection-name">
    <project id="project-id" />
    <owner id="owner-id" />
  </virtualConnection>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_virtual_connection"; filename="virtualconnection-name.tvcx"
Content-Type: application/octet-stream

content-of-virtualconnection-file
--boundary-string--
```

**Committing a file previously uploaded**

```
--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml

<tsRequest>
  <virtualConnection name="virtualconnection-name">
    <project id="project-id" />
    <owner id="owner-id" />
  </virtualConnection>
</tsRequest>
--boundary-string--
```

**Publishing a JSON representation**

```
<tsRequest>
  <virtualConnection name="virtualconnection-name">
    <project id="project-id" />
    <owner id="owner-id" />
    <content>virtualconnection-as-json</content>
  </virtualConnection>
</tsRequest>
```

```
{
  "virtualConnection": {
    "project": {
      "id": "project-id"
    },
    "owner": {
      "id": "owner-id"
    },
    "content": "virtualconnection-as-json",
    "name": "virtualconnection-name"
  }
}
```

#### Request Attributes

**For a .tvcx file**

<table class="api-parameters-table">
                        <colgroup>
                            <col class="api-parameters-table-col-1-extra-wide">
                            <col>
                        </colgroup>
                        <tbody>
                            <tr>
                                <td><span class="api-placeholder">boundary-string</span>
                                </td>
                                <td>(Required) 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=boundary-string</code></p></td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">virtualconnection-name</span>
                                </td>
                                <td>(Required) The name to assign to the virtual connection when it is saved on the server. This is typically derived from the file name.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">project-id</span>
                                </td>
                                <td>(Optional) The LUID of the project to publish to. If you omit it, the virtual connection is published to the default project.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">owner-id</span>
                                </td>
                                <td>(Optional) The LUID of the owner of the virtual connection. If you omit it, the authenticated user becomes the owner.</td>
                            </tr>
                            <tr>
                                <td><code>tableau_virtual_connection</code> file part
                    </td>
                                <td>The <code>.tvcx</code> file. Include it when you publish in a single request. Omit it when you commit a file that was uploaded in parts. If you include both a file part and the <code>uploadSessionId</code> parameter, or if you include neither, the request fails.</td>
                            </tr>
                        </tbody>
                    </table>

**For a JSON representation**

<table class="api-parameters-table">
                        <colgroup>
                            <col class="api-parameters-table-col-1-extra-wide">
                            <col>
                        </colgroup>
                        <tbody>
                            <tr>
                                <td><span class="api-placeholder">virtualconnection-name</span>
                                </td>
                                <td>The name of the virtual connection you are publishing. If publishing an existing virtual connection as a revision, the virtual connection name is ignored.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">project-id</span>
                                </td>
                                <td>The LUID of the project you are publishing to.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">owner-id</span>
                                </td>
                                <td>This attribute is required, but is ignored.</td>
                            </tr>
                            <tr>
                                <td><span class="api-placeholder">virtualconnection-as-json</span>
                                </td>
                                <td>
                                    <p>The virtual connection schema rendered as JSON, as obtained using the <a href="#download_virtual_connection_as_json">Download Virtual Connection as JSON</a> or <a href="#download_virtual_connection_revision_as_json">Download Virtual Connection Revision as JSON</a> method. The schema appears in the <span class="uicontrol">content</span> element (for XML output) or <span class="uicontrol">content</span> property (for JSON output).</p>
                                    <p><strong>Note:</strong> Changing the downloaded schema and then using it with this method isn't supported.</p>
                                    <p>When using the Publish Virtual Connection method, we recommend using the virtual connection schema format that matches the format you used for downloading it. This is important because the virtual connection schema returned by the download methods has escape characters in it if the output was JSON. If you download and publish using different formats, you will have to make changes to the JSON representation of the virtual connection.</p>
                                    <p>In other words:</p>
                                    <ul>
                                        <li>If the output of the <a href="#download_virtual_connection_as_json">Download Virtual Connection as JSON</a> method was XML (except for the <code>content</code> element, which is always a form of JSON), use XML when using this Publish Virtual Connection method.</li>
                                        <li>If the output of the <a href="#download_virtual_connection_as_json">Download Virtual Connection as JSON</a> method was JSON (in which case it will have escape characters in the <code>content</code> property), use JSON when using this Publish Virtual Connection method.</li>
                                        <li>Alternatively, you can escape or unescape the schema yourself if you are downloading and publishing using different formats.</li>
                                    </ul>
                                    <p>For more information on the difference between using XML and using JSON with the REST&nbsp;API, see <a href="https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_concepts_fundamentals.htm#Using" class="xref">Fundamentals of the Tableau Server REST API</a>.</p>
                                </td>
                            </tr>
                        </tbody>
                    </table>

#### cURL Example

**Publishing a .tvcx file**

`curl "http://MY_SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections?overwrite=false" -X POST -H "X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3" -H "Content-Type: multipart/mixed; boundary=----TabBoundary" --data-binary @publish-vconn-request.txt`

The file `publish-vconn-request.txt` contains the multipart request body shown above in **Publishing a file in the request body**.

**Publishing a JSON representation**

`curl --location 'http://MY_SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections?overwrite=true&publishAsDraft=false' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml`

**Content of data.xml**:

```
<tsRequest>
  <virtualConnection name="Batters">
    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"/>
    <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
    <content>virtualconnection-as-json</content>
  </virtualConnection>
</tsRequest>
```

Replace virtualconnection-as-json in this example with the virtual connection schema you downloaded using the [Download Virtual Connection as JSON](#download_virtual_connection_as_json) method.

#### Response Code

201

#### Response Body

The response is the same whether you publish a JSON representation or a `.tvcx` file.

```
<tsResponse>
  <virtualConnection id="virtualconnection-id" name="virtualconnection-name">
    <project id="project-id" />
  </virtualConnection>
</tsResponse>
```

```
{
  "virtualConnection": {
    "project": {
      "id": "project-id"
    },
    "id": "virtualconnection-id",
    "name": "virtualconnection-name"
  }
}
```

#### 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>
                                    <p>When you publish a .tvcx file, the request is not valid for one of these reasons:</p>
                                    <ul>
                                        <li>The request does not include <code>request_payload</code> or the <code>virtualConnection</code> element.</li>
                                        <li>The <code>virtualConnection</code> element does not include a <code>name</code>.</li>
                                        <li>The request includes both the .tvcx file and <code>uploadSessionId</code>, or it includes neither. Include only one.</li>
                                        <li>The file for the <code>uploadSessionId</code> is no longer available.</li>
                                        <li>The .tvcx file is not valid.</li>
                                        <li>The virtual connection could not be published with the extract in the .tvcx file.</li>
                                    </ul>
                                </td>
                            </tr>
                            <tr>
                                <td>400</td>
                                <td>400201</td>
                                <td>Publish virtual connection error</td>
                                <td>The virtual connection could not be published. This includes content that is not valid virtual connection JSON, or a .tvcx file or its contents that
					could not be read.</td>
                            </tr>
                            <tr>
                                <td>403</td>
                                <td>403008</td>
                                <td>Insufficient site storage</td>
                                <td>The content would exceed the site's storage quota. Applies when publishing a .tvcx file.</td>
                            </tr>
                            <tr>
                                <td>403</td>
                                <td>403175</td>
                                <td>Publish virtual connection forbidden</td>
                                <td>The user does not have permission to publish the virtual connection.</td>
                            </tr>
                            <tr>
                                <td>404</td>
                                <td>404015</td>
                                <td>File upload not found</td>
                                <td>The <code>uploadSessionId</code> does not match an upload owned by the user. Applies when publishing a .tvcx file.</td>
                            </tr>
                            <tr>
                                <td>404</td>
                                <td>404049</td>
                                <td>Virtual connection not found</td>
                                <td>The virtual connection could not be found while publishing it with the extract in the .tvcx file.</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>409123</td>
                                <td>Virtual connection exists</td>
                                <td>A virtual connection with the same name already exists in the project and <code>overwrite</code> is false. Applies when publishing a .tvcx file.</td>
                            </tr>
                        </tbody>
                    </table>

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

## List Virtual Connection Permissions

Returns a list of permissions for a specific virtual connection.

#### URI

GET /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions

#### 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/v0.0/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 virtual connection.</td></tr><tr><td><span class="api-placeholder">virtualconnection-id</span></td><td>The ID of the virtual connection to get permissions for.</td></tr></tbody></table>

#### Request Body

None

#### Permissions

You must be an administrator or have the Read (View) permission for the virtual connection (either explicitly or implicitly).

#### Required scope for JWT authorization

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

Authorize use of this method 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), or [Access Scopes for Connected Apps](https://help.tableau.com/current/online/en-us/connected_apps_scopes.htm) in the Tableau Cloud Help or [Access Scopes for Connected Apps](https://help.tableau.com/current/server/en-us/connected_apps_scopes.htm) in the Tableau Server Help.

```
tableau:permissions:read
```

#### Response Code

200

#### Response Body

```
<tsResponse>
    <permissions>
        <parent id="project-id"
            type="Project"/>
        <virtualConnection id="virtualconnection-id"
            name="virtualconnection-name">
            <owner id="owner-id"/>
        </virtualConnection>
        <granteeCapabilities>
            <group id="group-id"/>
            <capabilities>
                <capability name="capability-name"
                    mode="capability-mode"/>
                <!--   ...additional capabilities...   -->
            </capabilities>
        </granteeCapabilities>
        <granteeCapabilities>
            <user id="user-id"/>
            <capabilities>
                <capability name="capability-name"
                    mode="capability-mode"/>
                <!--   ...additional capabilities...   -->
            </capabilities>
        </granteeCapabilities>
        <!--   ...additional granteeCapability sets...   -->
    </permissions>
</tsResponse>
```

**Note**: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call [Create Project](#create_project) or for an existing project by calling [Update Project](#update_project). For more information, see [Lock Content Permissions to the Project](https://help.tableau.com/current/server/en-us/help.htm#permissions_project_lock.htm).

#### Version

Version 3.23 and later. For more information, see [REST API and Resource Versions](https://help.tableau.com/v0.0/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>404004</td><td>Virtual Connection not found</td><td>The virtual connection ID in the URI doesn't correspond to an existing virtual 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">GET</span>.</td></tr></tbody></table>

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

#### Example

`curl --location 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3'`

## Update Virtual Connection

Updates a virtual connection's name, owner, project, or certification status.

**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:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** You must have the Overwrite permission for the virtual connection and your site role must be at least Creator.   _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:virtual\_connections:update

- 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-id/virtualconnections/virtualconnection-id

#### 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/v0.0/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">virtualconnection-id</span></td><td>The LUID for the virtual connection.</td></tr></tbody></table>

#### Request Body

_(Use the icon in the top right corner to copy the text.)_

```
<tsRequest>
  <virtualConnection name="virtualconnection-name"
    isCertified="certified-flag"
    certificationNote="certification-message">
    <project id="project-id"/>
    <owner id="owner-id"/>
  </virtualConnection>
</tsRequest>
```

_(Use the icon in the top right corner to copy the text.)_

```
{
  "virtualConnection": {
    "name": "virtualconnection-name",
    "isCertified": "certified-flag",
    "certificationNote": "certification-message",
    "project": {
      "id": "project-id"
    },
    "owner": {
      "id": "owner-id"
    }
  }
}
```

#### Request Attributes

<table class="api-parameters-table">
                                <colgroup>
                                    <col class="api-parameters-table-col-1">
                                    <col>
                                </colgroup>
                                <tbody>
                                    <tr>
                                        <td><span class="api-placeholder">virtualconnection-name</span>
                                        </td>
                                        <td>The name of the virtual connection.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">certification-flag</span>
                                        </td>
                                        <td>Boolean. If true, the virtual connection is certified. If false, it won't.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">certification-message</span>
                                        </td>
                                        <td>The certification label's message.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">project-id</span>
                                        </td>
                                        <td>The LUID of the project the virtual connection is located in.</td>
                                    </tr>
                                    <tr>
                                        <td><span class="api-placeholder">owner-id</span>
                                        </td>
                                        <td>
                                            <p>The LUID of the user that owns the virtual connection.</p>
                                        </td>
                                    </tr>
                                </tbody>
                            </table>

Request attributes that are different from the virtual connection's current properties result in updating the virtual connection.

#### cURL Request Example

_(Use the icon in the top right corner to copy the text.)_

```
curl --request PUT 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml
```

**Contents of data.xml.**

_(Use the icon in the top right corner to copy the text.)_

```
<tsRequest>
  <virtualConnection name="Batters"
    isCertified="true"
    certificationNote="Approved by Marketing">
    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"/>
    <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
  </virtualConnection>
</tsRequest>
```

#### Response Code

200

#### Response Body

```
<tsResponse>
  <virtualConnection id="virtualconnection-id"
    isCertified="certified-flag"
    name="virtualconnection-name">
    <project id="project-id"/>
    <owner id="owner-id"/>
  </virtualConnection>
</tsResponse>
```

```
{
  "virtualConnection": {
    "project": {
      "id": "project-id"
    },
    "owner": {
      "id": "owner-id"
    },
    "id": "virtualconnection-id",
    "isCertified": certified-flag,
    "name": "virtualconnection-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>400203</td><td>Generic error</td><td>An unknown error occurred.</td></tr><tr><td>403</td><td>403004</td><td>User not authorized to change virtual connection</td><td>Check to make sure the user has the required permissions.</td></tr><tr><td>403</td><td>403176</td><td>User not authorized to change virtual connection's owner</td><td>Check to make sure the user has the required permissions.</td></tr><tr><td>403</td><td>403177</td><td>User not authorized to move assets into the target project.</td><td>Check to make sure the user has the required permissions.</td></tr><tr><td>403</td><td>403178</td><td>User not authorized to move the virtual connection</td><td>Check to make sure the user has the required permissions.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found</td><td>Check the virtual connection LUID.</td></tr><tr><td>409</td><td>409124</td><td>A virtual connection with the chosen name already exists in the project.</td><td>Try a different virtual connection name.</td></tr></tbody></table>

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

## Update Virtual Connection Database Connections

Updates the server address, port, username, or password for the specified database connection in a virtual connection.

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

**License:** Requires [Tableau Data Management](https://help.tableau.com/current/online/en-us/dm_overview.htm).

**Permissions:** Users who are administrators or have the site role of Creator or higher can update a database connection.  _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:virtualconnectionconnections:update

- 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-id/virtualconnections/virtual-connection-id/connections/connection-id/modify

#### 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/v0.0/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 that contains the virtual connection.</td></tr><tr><td><span class="api-placeholder">virtual-connection-id</span></td><td>The LUID for the virtual connection that includes the database connections.</td></tr><tr><td><span class="api-placeholder">connection-id</span></td><td>The ID of the database connection. To determine what connections are in a virtual connection, call <a href="#ref_list_virtual_connection_database_connections" target="_blank">List Virtual Connection Database Connections</a>.</td></tr></tbody></table>

#### Request Body

```
<tsRequest> <connection   serverAddress="server-address"   serverPort="port-number"   userName="test"   password="password" /></tsRequest>
```

```
{  "connection": {    "serverAddress": "server-address",    "serverPort": "port-number",    "userName": "test",    "password": "password"  }}
```

#### Request Attributes

<table class="api-parameters-table"><colgroup><col style="width:36%;"> <col></colgroup><tbody><tr><td><code>connection serverAddress</code></td><td>The new server for the database connection.</td></tr><tr><td><code>connection serverPort</code></td><td>The new port for the database connection</td></tr><tr><td><code>connection userName</code></td><td>The new username for the database connection.</td></tr><tr><td><code>connection password</code></td><td>The new password for the database connection.</td></tr></tbody></table>

#### cURL Request Example

`curl --location --request PUT "https://MY_SERVER/api/3.18/sites/a946d998-2ead-4894-bb50-1054a91dcab3/virtualconnections/26bc30d8-90d6-4af1-922d-ac285e7b08fb/connections/26bc30d8-90d6-4af1-922d-ac285e7b08fb"`

#### Response Code

200

#### Response Body

Copy

```
<tsResponse>  <virtualConnectionConnections>    <connection       id="connection-id"       serverAddress="server-address"       serverPort="port-number"      userName="connection-user-name"      password="password"/>  </virtualConnectionConnections></tsResponse>
```

Copy

```
{  "virtualConnectionConnections": {    "connection": {      "id": "connection-id",      "serverAddress": "server-address",      "serverPort": "port-number",      "userName": "connection-user-name",      "password": "password"    }  }}
```

#### 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</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403004</td><td>Operation unauthorized</td><td>The user isn’t authorized to perform the task.</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 <b>PUT</b>.</td></tr></tbody></table>

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

## Update Virtual Connection Now

Runs an extract refresh on the specified virtual connection.

This method identifies and refreshes only the tables in the virtual connection that are configured as extracts; live tables are ignored. No additional input is required from the caller.

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

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

**License**: Data Management, Enterprise, Server+, Cloud+, or Tableau+ Bundle.

**Permissions**: Users who are not server administrators or site administrators can only refresh extracts for virtual connections if they own the virtual connection, or if they are the project leader for the project.

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

POST /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/refresh

#### 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/v0.0/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">virtualconnection-id</span></td><td>The LUID for the virtual connection to refresh.</td></tr></tbody></table>

#### Request Body

The request body is an empty tsRequest element.

```
<tsRequest/>
```

```
{}
```

#### cURL Request Example

_(Use the icon in the top right corner to copy the text.)_

```
curl --request POST 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/refresh' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest/>'
```

#### Response Code

202

#### Response Body

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

```
{
  "job": {
    "id": "job-id",
    "mode": "Asynchronous",
    "type": "RefreshExtract",
    "createdAt": "date-time",
    "extractRefreshJob": {
      "virtualConnection": {
        "id": "virtualconnection-id",
        "name": "virtualconnection-name"
      }
    }
  }
}
```

#### 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>403180</td><td>Full refresh not allowed.</td><td>A full refresh extract operation is not allowed for the virtual connection.</td></tr><tr><td>400</td><td>403181</td><td>Incremental refresh not allowed.</td><td>The request specified an incremental refresh, but an incremental refresh extract operation is not allowed for the virtual connection.</td></tr><tr><td>400</td><td>409090</td><td>No extract-eligible tables.</td><td>The virtual connection has no active revision or no extract-eligible tables. Live tables are not refreshed.</td></tr><tr><td>403</td><td>403199</td><td>User not authorized to refresh the virtual connection.</td><td>The user must have either the Manage Extract or the Allow Extract Refresh permission on the virtual connection.</td></tr><tr><td>403</td><td>409082</td><td>Run Now is disabled for the site.</td><td>Enable Run Now for the site, then try the request again.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found.</td><td>Check the virtual connection LUID.</td></tr><tr><td>405</td><td>405000</td><td>Method not allowed.</td><td>Direct virtual connection extract refresh is not enabled for this site.</td></tr><tr><td>409</td><td>409093</td><td>Operation already in queue.</td><td>An extract refresh job for the virtual connection is already in the queue.</td></tr></tbody></table>

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