---
schema_version: "1"
id: 8c80f8654406900094841e6f4747bac61ba6c278f8592886d253b8a45a71b2c0
title: Extract and Encryption 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_extract_and_encryption.md
canonical_url: https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_extract_and_encryption.htm
source_site: help.tableau.com
content_type: documentation
content_hash: a492df6f51bc83d89d13459e4c0f126960443018f58d4a2e86222885848173d0
description: Extracts are saved subsets of data that you can use to improve performance, or to take advantage of Tableau functionality not available or supported in your original data)
---
[Skip to main content](#main-content)

# Extract and Encryption Methods

**[Extracts](https://help.tableau.com/current/pro/desktop/en-us/extracting_data.htm)** are saved subsets of data that you can use to improve performance, or to take advantage of Tableau functionality not available or supported in your original data).

Using the extract methods of the Tableau Server REST API you can:

- Set the schedule for extract refresh task for a data source
- Set the schedule for extract refresh task for all data sources in a workbook to a schedule
- Get a list of extract refresh tasks for a specific site or schedule
- Run a specific extract refresh task
- Create an extract from a published data source (used by all workbooks in a site that consume the data source)
- Create extracts from the data sources of a published workbook (includes embedded data sources and embedding of published data sources for workbook-specific extract configuration)
- Delete the extract of a data source
- Delete the extracts of a workbook
- Delete the refresh task for an extract
- Enable encryption and decryption of extracts on a site when you use [Create Site](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref.htm#create_site) or [Update Site](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref.htm#update_site) methods
- Set the scope of encryption to be all extracts on a site, or allow the users to use: [Publish Data Source](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref.htm#create_site), [Publish Workbook](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref.htm#create_site), [Update Data Source](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref.htm#create_site), or [Update Workbook](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref.htm#create_site) methods to enable or disable encryption for each workbook or data source on a site
- Encrypt and decrypt extracts on a site
- Reencrypt extracts on a site with new security keys

This functionality relates to the UI elements and concepts described at: [Extract Your Data](https://help.tableau.com/current/pro/desktop/en-us/extracting_data.htm).

## About Extract Encryption

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see [Extract Encryption at Rest](https://help.tableau.com/current/server/en-us/security_ear.htm).

The extract encryption mode is set at the site level. To set the mode, use the Create Site or Update Site methods with the `extractEncryptionMode` attribute. The extract encryption modes are:

- **enforced**: enforce encryption of all extracts on the site.
- **enabled**: allow users to specify to encrypt all extracts associated with specific published workbooks or data sources.
- **disabled**: disable extract encryption on the site.

To get the site extract encryption mode, use the Query Site method, which shows the `extractEncryptionMode` attribute in its response body.

When the site extract encryption mode is set to **enforced**, all content is encrypted. You can use the reencrypt-extracts method to reencrypt all extracts on a site.

When the site extract encryption mode is set to **enabled**, users can decide to encrypt or decrypt the extracts associated with specific published workbooks or data sources. To do this, use the Publish Data Source, Publish Workbook, Update Data Source, or Update Workbook methods with the `encryptExtracts` attribute. Set the `encryptExtracts` attribute to **true** to encrypt the extracts. The user must be the owner or administrator. To get the extract encryption status, use the Query Data Source or Get Workbook methods, which show the `encryptExtracts` attribute in the response body.

When the site extract encryption mode is set to **enabled**, the owner or administrator can encrypt, decrypt, and reencrypt all extracts associated with workbooks or data sources on a site.

When the site extract encryption mode is set to **disabled**, all encrypted extracts will be decrypted. Depending on the number and size of extracts, this operation may consume significant server resources.

## 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: Extracts and Encryption](https://www.postman.com/salesforce-developers/salesforce-developers/folder/2y5yr97/extracts-and-encryption)

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

## Create Extracts for Embedded Data Sources in a Workbook

Create extracts for all embedded data sources of a workbook. Optionally, encrypt the extracts if the site and workbook using them are configured to allow it.

When you create an extract for a data source in a workbook, the extract is available only to the workbook and may have configuration specific to the workbook, such as hiding of unused fields.  
  
You can create workbook extracts for both embedded and published data sources used by the workbook. When you create a workbook data source for a published data source, then refreshing the workbook extract will retrieve any changes to data from the published datasource, or from the published data source's extract if it is using one.

**Note:** This method will fail and result in an error if your Server Administrator has disabled the **RunNow** setting for the site. For more information, see [Tableau Server Settings](https://help.tableau.com/current/server/en-us/maintenance_set.htm).

#### URI

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

POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract?encrypt=encryption-flag

#### Path Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/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.</td></tr><tr><td><span class="api-placeholder">workbook-id</span></td><td>The LUID of the workbook.</td></tr><tr><td><span class="api-placeholder">encryption-flag</span></td><td>If <code>true</code>, then Tableau will attempt to encrypt the created extracts. If <code>false</code>, or no <code>encrypt</code> parameter is appended to the URI, then the extract won't be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when <code>encrypt</code> equals <code>true</code> and encryption is disabled in the site or workbook.</td></tr></tbody></table>

#### Request Body

```
<tsRequest>
  <datasources includeAll="extract-all-datasources-flag">
	<datasource id="datasource-id" />
  </datasources>
</tsRequest>
```

#### Request 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">datasource-id</span></td><td>LUID of the embedded data source to be extracted.</td></tr><tr><td><span class="api-placeholder">extract-all-datasources-flag</span></td><td>Boolean. If <code>true</code>, then all data sources in the workbook will have an extract created for them. If <code>false</code>, then a data source must be supplied in the request.</td></tr></tbody></table>

#### Permissions

Extracts for data sources embedded in a workbook can be created by Tableau server or site administrators, and users who own the workbook, or are an owner or leader of the project where the workbook resides.

#### Access Scope

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

```
tableau:extracts: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).

#### Response Code

`200`

#### Response Body

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

#### Version

Version 3.5 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>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>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>409070</td><td>Invalid request method</td><td>The data source cannot be extracted because it is file based or in another unsupported form.</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 "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@create-extracts-for-workbook.xml"`

**Content of** `create-extracts-for-workbook.xml`

```
<tsResponse>
  <datasources includeAll="false" />
    <datasource id="6b4cf715-c90b-49d6-be85-920a47bae433" />
  </datasources>
</tsRequest>
```

**Response body:**

```
<tsResponse>
  <job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
	<extractCreationJob>
	  <workbook id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_WORKBOOK_NAME"/>
	  <jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
    </extractCreationJob>
  </job>
</tsResponse>
```

## Create an Extract for a Data Source

Create an extract for a data source in a site. Optionally, encrypt the extract if the site and workbooks using it are configured to allow it.

#### URI

POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract

POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract?encrypt=encryption-flag

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/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.</td></tr><tr><td><span class="api-placeholder">datasource-id</span></td><td>The LUID of the datasource.</td></tr><tr><td><span class="api-placeholder">encryption-flag</span></td><td>If <code>true</code>, then Tableau will attempt to encrypt the created extracts. If <code>false</code>, or no <code>encrypt</code> parameter is appended to the URI, then the extract won't be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when <code>encrypt</code> equals <code>true</code> and encryption is disabled in the site or workbook.</td></tr></tbody></table>

#### Request Body

None

#### Permissions

Extracts for data sources can be created by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

#### Access Scope

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

```
tableau:extracts: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).

#### Response Code

200

#### Response Body

```
<tsResponse>
  <job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
    <extractCreationJob>
	  <datasource id="datasource-id" name="datasource-name" />
  </extractCreationJob>
</tsResponse>
```

#### Version

Version 3.5 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>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>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>409070</td><td>Invalid request method</td><td>The data source cannot be extracted because it is file based or in another unsupported form.</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 "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"`

**Response body:**

```
<tsResponse>
  <job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
    <extractCreationJob>
        <datasource id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_DATASOURCE_NAME"/>
      <jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
    </extractCreationJob>
  </job>
</tsResponse>
```

## Decrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see [Extract Encryption at Rest](https://help.tableau.com/current/server/en-us/security_ear.htm).

Decrypts all extracts on a site.

**Note:** Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

#### URI

POST /api/api-version/sites/site-id/decrypt-extracts

#### 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.</td></tr></tbody></table>

#### Request Body

None

#### Permissions

Tableau Server administrators can call this method.

#### Access Scope

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

```
tableau:extract_encryption:delete
```

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

#### Response Code

200

#### Response Body

None

#### Version

Version 3.5 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>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>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">POST</span>.</td></tr></tbody></table>

For more information, see [Handling Errors](https://help.tableau.com/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 Extracts of Embedded Data Sources from a Workbook

Delete all extracts of embedded data sources in a workbook.

**Note:** Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

#### URI

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

#### Path Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/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.</td></tr><tr><td><span class="api-placeholder">datasource-id</span></td><td>The LUID of the workbook containing the extract to be deleted.</td></tr></tbody></table>

#### Permissions

Extracts for data sources can be deleted by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

#### Request Body

```
<tsRequest>
  <datasources includeAll="true"/>
</tsRequest>
```

#### Request Parameter Values

None.

#### Access Scope

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

```
tableau:extracts:delete
```

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

#### Response Code

`200`

#### Response Body

None.

#### Version

Version 3.5 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>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>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>409070</td><td>Invalid request method</td><td>The data source cannot be extracted because it is file based or in another unsupported form.</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 "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@delete-extracts-for-workbook.xml"`

**Content of** `create-extracts-for-workbook.xml`

```
<tsResponse>
  <datasources includeAll="true" />
</tsRequest>
```

**Response body:**

None. Response code is `200`.

## Delete Extract from Data Source

Delete the extract from a data source.

#### URI

POST /api/api-version/sites/site-id/datasources/datasource-id/deleteExtract

#### 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.</td></tr><tr><td><span class="api-placeholder">datasource-id</span></td><td>The LUID of the datasource whose extract is to be deleted.</td></tr></tbody></table>

#### Permissions

Extracts for data sources can be deleted by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.

#### Access Scope

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

```
tableau:extracts:delete
```

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

#### Response Code

`204 No Content`

#### Response Body

None.

#### Version

Version 3.5 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>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>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>409070</td><td>Invalid request method</td><td>The data source cannot be extracted because it is file based or in another unsupported form.</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 "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"`

## Delete Extract Refresh Task

Deletes the specified extract refresh task on Tableau Server or Tableau Cloud.

On Tableau Cloud, deleting a task also deletes its custom schedule. On Tableau Server, it removes the item from the shared schedule but doesn't delete the schedule.

#### URI

DELETE /api/api-version/sites/site-id/tasks/extractRefreshes/task-id

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1-wide"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code><span class="mc-variable Variables.REST-API-Version variable">3.29</span></code>. For more information, see <a href="https://help.tableau.com/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 extract refresh task.</td></tr><tr><td><span class="api-placeholder">task-id</span></td><td>The LUID of the extract refresh task to remove.</td></tr></tbody></table>

#### JWT Access Scope

Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

`tableau:tasks:delete` (this scope is included in the scope: `tableau:tasks`)

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

#### Request Body

None

#### Permissions

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

#### Response Code

204

#### Response Body

None

#### Version

Version 3.6 and later. Virtual connection support added in 3.30. 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>404026</td><td>Task not found</td><td>The task id in the URI doesn't correspond to an existing extract refresh task.</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).

## Encrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see [Extract Encryption at Rest](https://help.tableau.com/current/server/en-us/security_ear.htm).

Encrypts all extracts on a site.

**Note:** Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

#### URI

POST /api/api-version/sites/site-id/encrypt-extracts

#### 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.</td></tr></tbody></table>

#### Request Body

None

#### Permissions

Tableau Server administrators can call this method.

#### Access Scope

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

```
tableau:extract_encryption: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).

#### Response Code

200

#### Response Body

None

#### Version

Version 3.5 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>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>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">POST</span>.</td></tr></tbody></table>

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

## Get Extract Refresh Task

Returns information about a site's scheduled extract refresh task for a data source, workbook, or virtual connection.

#### URI

GET /api/api-version/sites/site-id/tasks/extractRefreshes/task-id

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1"> <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 the user is a member of.</td></tr><tr><td><span class="api-placeholder">task-id</span></td><td>The ID of the extract refresh that you want information about.</td></tr></tbody></table>

#### JWT Access Scope

Available in API 3.20 (Tableau Cloud June 2023).

`tableau:tasks:read` (this scope is included in the scope: `tableau:tasks`)

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

#### Request Body

None

#### Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of extract refresh tasks that they own.

#### Response Code

200

#### Response Body

Tableau Server and Tableau Cloud return different payloads in response to this request.

Output for virtual connections includes `transactionLevel` and table ids in addition to the output that's standard for data sources and workbooks.

### Tableau Server Response

For Tableau Server an extract refresh task with a server schedule is returned.

```
<tsResponse>
  <task>
    <extractRefresh id="refresh_task_id"
      priority="nn"
      consecutiveFailedCount="n"
      type="REFRESH_EXTRACT">
        <schedule id="schedule_id"
          name="schedule_name"
          state="state"
          priority="nn"
          createdAt="DATE_TIME"
          updatedAt="DATE_TIME"
          type="Extract"
          frequency="frequency"
          nextRunAt="DATE_TIME" />
        <datasource id="datasource_id" />
    </extractRefresh>
  </task>
  <task>
    <!-- ... additional tasks ... -->
  </task>
</tsResponse>
```

```
[
  {
    "extractRefresh": {
      "id": "refresh_task_id",
      "priority": "nn",
      "consecutiveFailedCount": "n",
      "type": "REFRESH_EXTRACT",
      "schedule": {
        "id": "schedule_id",
        "name": "schedule_name",
        "state": "state",
        "priority": "nn",
        "createdAt": "DATE_TIME",
        "updatedAt": "DATE_TIME",
        "type": "Extract",
        "frequency": "frequency",
        "nextRunAt": "DATE_TIME"
      },
      "datasource": {
        "id": "datasource_id"
      }
    }
  },
  []
]
```

### Tableau Cloud Response

For Tableau Cloud an extract refresh task with its frequency is returned.

```
<tsResponse>
  <task>
    <extractRefresh id="0ece2369-c4eb-4382-be0f-961039d708a0" priority="50" consecutiveFailedCount="5" type="RefreshExtractTask">
      <schedule frequency="Weekly" nextRunAt="2023-06-08T04:50:00Z">
        <frequencyDetails start="21:50:00">
          <intervals>
            <interval weekDay="Wednesday"/>
          </intervals>
        </frequencyDetails>
       </schedule>
      <workbook id="7e766949-7166-4b3d-90ba-784f7575743b"/>
    </extractRefresh>
  </task>
</tsResponse>
```

```
{
  "task": {
    "extractRefresh": {
      "id": "0ece2369-c4eb-4382-be0f-961039d708a0",
      "priority": "50",
      "consecutiveFailedCount": "5",
      "type": "RefreshExtractTask",
      "schedule": {
        "frequency": "Weekly",
        "nextRunAt": "2023-06-08T04:50:00Z",
        "frequencyDetails": {
          "start": "21:50:00",
          "intervals": {
		    "interval": [
		      { "weekDay": "Thursday" }
		    ]
		  }
        }
      },
      "workbook": {
        "id": "7e766949-7166-4b3d-90ba-784f7575743b"
      }
    }
  }
}
```

#### Version

Version 2.6 and later. Virtual connection support added in 3.30. 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><td>403</td><td>403004</td><td>Operation unauthorized</td><td>The user is not authorized to get the task.</td></tr><tr><td>404</td><td>404026</td><td>Task not found</td><td>The task ID in the URI doesn't correspond to an existing task.</td></tr><tr><td>405</td><td>405000</td><td>Invalid requests 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 Extract Refresh Tasks in Site

Returns a list of extract refresh tasks for the site. Tasks include extract refreshes for data sources, workbooks, and virtual connections.

#### URI

GET /api/api-version/sites/site-id/tasks/extractRefreshes

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1"> <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.</td></tr></tbody></table>

#### JWT Access Scope

Available in API 3.20 (Tableau Cloud June 2023).

`tableau:tasks:read` (this scope is included in the scope: `tableau:tasks`)

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

#### cURL Example

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

#### Request Body

None

#### Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of extract refresh tasks that they own.

#### Response Code

200

#### Response Body

Tableau Server and Tableau Cloud return different payloads in response to this request.

Output for virtual connections includes `transactionLevel` and table ids in addition to the output that's standard for data sources and workbooks.

### Tableau Server Response

On Tableau Server, a list of extract refresh tasks with their server schedules is returned.

```
<tsResponse>
  <tasks>
    <task>
      <extractRefresh id="refresh_task_id"
        priority="nn"
        consecutiveFailedCount="n"
        type="REFRESH_EXTRACT">
          <schedule id="schedule_id"
            name="schedule_name"
            state="state"
            priority="nn"
            createdAt="DATE_TIME"
            updatedAt="DATE_TIME"
            type="Extract"
            frequency="frequency"
            nextRunAt="DATE_TIME" />
          <datasource id="datasource_id" />
      </extractRefresh>
    </task>
    <task>
      <!-- ... additional tasks ... -->
    </task>
  </tasks>
</tsResponse>
```

```
{
  "tasks": [
    {
      "extractRefresh": {
        "id": "refresh_task_id",
        "priority": "nn",
        "consecutiveFailedCount": "n",
        "type": "REFRESH_EXTRACT",
        "schedule": {
          "id": "schedule_id",
          "name": "schedule_name",
          "state": "state",
          "priority": "nn",
          "createdAt": "DATE_TIME",
          "updatedAt": "DATE_TIME",
          "type": "Extract",
          "frequency": "frequency",
          "nextRunAt": "DATE_TIME"
        },
        "datasource": {
          "id": "datasource_id"
        }
      }
    },
    []
  ]
}
```

### Tableau Cloud Response

On Tableau Cloud, a list of extract tasks with their frequency is returned.

```
<tsResponse>
  <tasks>
    <task>
      <extractRefresh id="0ece2369-c4eb-4382-be0f-961039d708a0" priority="50" consecutiveFailedCount="5" type="RefreshExtractTask">
        <schedule frequency="Weekly" nextRunAt="2023-06-08T04:50:00Z">
          <frequencyDetails start="21:50:00">
            <intervals>
              <interval weekDay="Wednesday"/>
            </intervals>
          </frequencyDetails>
        </schedule>
        <workbook id="7e766949-7166-4b3d-90ba-784f7575743b"/>
      </extractRefresh>
    </task>
  </tasks>
</tsResponse>
```

```
{
  "tasks": {
    "task": {
      "extractRefresh": {
        "id": "0ece2369-c4eb-4382-be0f-961039d708a0",
        "priority": "50",
        "consecutiveFailedCount": "5",
        "type": "RefreshExtractTask",
        "schedule": {
          "frequency": "Weekly",
          "nextRunAt": "2023-06-08T04:50:00Z",
          "frequencyDetails": {
            "start": "21:50:00",
            "intervals": {
			  "interval": [
			    { "weekDay": "Thursday" }
			  ]
			}
          }
        },
        "workbook": {
          "id": "7e766949-7166-4b3d-90ba-784f7575743b"
        }
      }
    }
  }
}
```

#### Version

Version 2.6 and later. Virtual connection support added in 3.30. 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><td>405</td><td>405000</td><td>Invalid requests 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 Extract Refresh Tasks in Server Schedule

Returns a list of the extract refresh tasks for a specified server schedule on the specified site on Tableau Server.

To get the ID of a schedule, call the [List Server Schedules](#query_schedules) method. Note that the List Server Schedules method is global to the server; schedules are not specific to a site. Therefore, the URI for the List Server Schedules method does not include `/sites/` or a site ID. However, individual scheduled tasks are specific to a site, and the URI for Query Extract Refresh Tasks must include the site information.

For more information about refresh tasks, see [Manage Refresh Tasks](https://help.tableau.com/current/server/en-us/help.htm#task.htm).

_Not available for Tableau Cloud._

#### URI

GET /api/api-version/sites/site-id/schedules/schedule-id/extracts

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

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1"> <col></colgroup><tbody><tr><td><span class="api-placeholder">api-version</span></td><td>The version of the API to use, such as <code>2.2</code>. For more information, see <a href="https://help.tableau.com/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 refresh tasks.</td></tr><tr><td><span class="api-placeholder">schedule-id</span></td><td>The ID of the schedule to get extract information for.</td></tr><tr><td><span class="api-placeholder">page-size</span></td><td>(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see <a href="https://help.tableau.com/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>

#### JWT Access Scope

Not available.

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

#### Request Body

None

#### Permissions

This method can only be called by server administrators and site administrators. When a site administrator calls this method, the payload contains only the tasks that are associated with the site that the user is signed in to.

#### Response Code

200

#### Response Body

```
<tsResponse>
  <pagination pageNumber="pageNumber"
     pageSize="page-size"
     totalAvailable="total-available" />
  <extracts>
    <extract id="task-id"
      priority="task-priority"
      type="incremental-or-full" >
        <workbook id="workbook-id" />
    </extract>
    <extract id="task-id"
      priority="task-priority"
      type="incremental-or-full" >
        <datasource id="datasource-id" />
    </extract>
    <extract id="task-id"
      priority="task-priority"
      type="incremental-or-full" >
        <virtualConnection id="virtualconnection-id" />
    </extract>
    ... additional extract refresh tasks ...
  </extracts>
</tsResponse>
```

#### Version

Version 2.2 and later. Virtual connection support added in 3.30. 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>400006</td><td>Invalid page number</td><td>The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.</td></tr><tr><td>400</td><td>400007</td><td>Invalid page size</td><td>The page size parameter is not an integer, or is less than one.</td></tr><tr><td>400</td><td>400047</td><td>Invalid schedule type</td><td>The schedule type does not represent an extract refresh task. (For example, it might be a subscription task.)</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>404</td><td><span style="background-color:yellow;">404</span></td><td>Schedule not found</td><td>The schedule ID in the URI doesn't correspond to an existing schedule.</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 "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/schedules/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba/extracts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"`

**Example response:**

```
<tsResponse version-and-namespace-settings>
<pagination pageNumber="1" pageSize="100" totalAvailable="3" />
  <extracts>
    <extract id="639c7e80-0d11-44b2-9b5b-018ffc5eddb4" priority="60" type="FullRefresh">
      <datasource />
    </extract>
    <extract id="303f6c45-fb48-47aa-88d3-0dd87f5f5c74" priority="50" type="FullRefresh">
      <workbook />
    </extract>
    <extract id="9dd16fd7-8bbc-4c0d-9f75-9c7330a29396" priority="50" type="ExtractServiceFullRefreshExtractTask">
      <virtualConnection id="e3ebe049-8f94-4501-8fb0-faba6ccbbc85" />
    </extract>
  </extracts>
</tsResponse>
```

## Reencrypt Extracts in a Site

Extract encryption at rest is a data security feature that allows you to encrypt .hyper extracts while they are stored on Tableau Server. For more information, see [Extract Encryption at Rest](https://help.tableau.com/current/server/en-us/security_ear.htm).

Reencrypt all extracts on a site with new encryption keys. If no site is specified, extracts on the default site will be reencrypted.

**Note:** Depending on the number and size of extracts, this operation may consume significant server resources. Consider running this command outside of normal business hours.

#### URI

POST /api/api-version/sites/site-id/reencrypt-extracts

#### 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.</td></tr></tbody></table>

#### Request Body

None

#### Permissions

Tableau Server administrators can call this method.

#### Access Scope

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

```
tableau:extract_encryption:update
```

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

#### Response Code

200

#### Response Body

None

#### Version

Version 3.5 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>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>405</td><td>405000</td><td>Invalid request method</td><td>Request type was not <span class="api-command-ref">POST</span>.</td></tr></tbody></table>

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

## Run Extract Refresh Task

Runs the specified extract refresh task.

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

This method runs the scheduled task for the data source extract, the published workbook that connects to the data extract, or the virtual connection extract. You must first schedule the task for the extract refresh. You can do this using the [Create Schedule](#create_schedule) method to create the task. To get information about the extract refresh task, use the [Get Extract Refresh Tasks](#get_extract_refresh_tasks) method, which returns the extractRefresh ID that you use as the task-id.

The method adds the refresh task to the backgrounder queue. Depending upon the backgrounder load, the task might not run immediately. The method returns information about the backgrounder job responsible for running the extract refresh task, including a **job id** that can be used with the [Query Job](#query_job) method to query the status of the extract refresh.

An extract refresh task can be initiated by a REST API call, a tabcmd command, or a job calling the task on a schedule. A REST request to start a refresh task will fail if the task has been put in the task queue in any of these ways, or is already in progress.

#### URI

POST /api/api-version/sites/site-id/tasks/extractRefreshes/task-id/runNow

#### Parameter Values

<table class="api-parameters-table"><colgroup><col class="api-parameters-table-col-1"> <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 the user is a member of.</td></tr><tr><td><span class="api-placeholder">task-id</span></td><td>The ID of the extract refresh task that you want to run.</td></tr></tbody></table>

#### JWT Access Scope

Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.

`tableau:tasks:run` (this scope is included in the scope: `tableau:tasks`)

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

#### Request Body

The request body is an empty tsRequest element.

```
<tsRequest/>
```

#### Permissions

Tableau Server users who are not server administrators or site administrators can only run the extract refresh tasks that they own.

#### Response Code

200

#### Response Body

The content type (workbook, data source, or virtual connection) is indicated in the response.

```
  <tsResponse>
    <job id="a1b2c3d4-0000-0000-0000-000000000001" mode="Asynchronous" type="RefreshExtract" createdAt="2026-10-11T18:04:12Z">
      <extractRefreshJob>
        <workbook id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" name="Sales Dashboard" />
      </extractRefreshJob>
    </job>
  </tsResponse>
```

#### Version

Version 2.6 and later. Virtual connection support added in 3.30. 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>400047</td><td>Extract refresh error</td><td>The task specified is not an extract refresh task.</td></tr><tr><td>400</td><td>409090</td><td>Extract operation not allowed</td><td>The extract operation is not allowed for the asset that the task refreshes.</td></tr><tr><td>403</td><td>403004</td><td>Operation on resource unauthorized</td><td>The user is not authorized to run the task.</td></tr><tr><td>403</td><td>409082</td><td>Run now disabled</td><td>The Run Now setting is disabled for the site.</td></tr><tr><td>404</td><td>404003</td><td>Unknown resource</td><td>The task ID in the URI doesn't correspond to an existing task.</td></tr><tr><td>404</td><td>404049</td><td>Virtual connection not found</td><td>The virtual connection that the task refreshes no longer exists.</td></tr><tr><td>405</td><td>405000</td><td>Method not allowed</td><td>The request type was not <b>POST</b>.</td></tr><tr><td>409</td><td>409093</td><td>Operation already in queue</td><td>The extract refresh job is already in the queue.</td></tr></tbody></table>

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

#### Example

`curl "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/extractRefreshes/9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c/runNow" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @empty_request.xml`

## Update Cloud Extract Refresh Task

Updates an extract refresh task on Tableau Cloud.

_For Tableau Server, see [Update server schedule](https://help.tableau.com/v0.0/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#update_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.

**Permissions:** Administrators and the owner of a custom schedule for an extract refresh task can update the schedule.  _[Permissions Overview](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_permissions.htm)_

**JWT Access Scope**: tableau:tasks: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

POST /api/api-version/sites/site-id/tasks/extractRefreshes/task-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">task-id</span></td><td>The LUID of the extract refresh task. Use <a href="#get_extract_refresh_tasks">Get extract refresh tasks on site</a> to find tasks by name.</td></tr></tbody></table>

#### Request Body

```
<tsRequest>
  <extractRefresh type="FullRefresh">
    <workbook id="13237fd-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": "13237fd-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 **optional** to update a custom schedule for a subscription.

<table class="api-parameters-table">
                            <colgroup>
                                <col width="30%">
                                <col width="70%">
                            </colgroup>
                            <tbody>
                                <tr>
                                    <td><code>extractRefresh type</code>
                                    </td>
                                    <td><i>enumeration:</i> The type of extract refresh being scheduled. Valid values include:
						<ul><li><code>FullRefresh</code></li><li><code>IncrementalRefresh</code></li></ul></td>
                                </tr>
                                <tr>
                                    <td><code>workbook id</code> <br> or <code>datasource id</code> <br> or <code>virtualConnection id</code></td>
                                    <td><i> LUID:</i> The LUID of the workbook, data source, or virtual connection that is the target of the custom schedule.</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>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>
                                <tr>
                                    <td><code>schedule frequency</code>
                                    </td>
                                    <td><i>enumeration:</i> The scheduled frequency for triggering the extract refresh. Valid values include:
							<ul><li>Hourly</li><li>Daily</li><li>Weekly</li><li>Monthly</li></ul></td>
                                </tr>
                                <tr></tr>
                                <tr>
                                    <td><code>frequencyDetails start</code>
                                    </td>
                                    <td><i>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>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>
                                        <div class="codeSnippet">
                                            <div class="codeSnippetBody"><pre><code>&lt;frequencyDetail start="20:45:00" end="21:45:00"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;. . .&nbsp;<br>&lt;/frequencyDetail&gt;</code></pre>
                                            </div>
                                        </div>
                                    </td>
                                </tr>
                                <tr>
                                    <td><code>interval <i>{interval type}</i></code>
                                    </td>
                                    <td><i>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:
											<br><div class="codeSnippet"><a class="codeSnippetCopyButton" role="button">Copy</a><div class="codeSnippetBody"><pre><code>&lt;intervals&gt;<br>&nbsp;&nbsp;&lt;interval hours="1"/&gt;<br>&nbsp;&nbsp;&lt;interval weekDay="Sunday"/&gt;<br>&nbsp;&nbsp;&lt;interval weekDay="Wednesday"/&gt;<br>&nbsp;&lt;intervals&gt;</code></pre></div></div></li></ul></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><div class="codeSnippet"><a class="codeSnippetCopyButton" role="button">Copy</a><div class="codeSnippetBody"><pre><code>&lt;intervals&gt;<br>&nbsp;&nbsp;&lt;interval hours="4"/&gt;<br>&nbsp;&nbsp;&lt;interval weekDay="Sunday"/&gt;<br>&nbsp;&nbsp;&lt;interval weekDay="Wednesday"/&gt;<br>&lt;intervals&gt;</code></pre></div></div></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.
												For example, to make a schedule that that would run a job on the first and fifteenth of each month, you would use:<br><div class="codeSnippet"><a class="codeSnippetCopyButton" role="button">Copy</a><div class="codeSnippetBody"><pre><code>&lt;intervals/&gt;<br>&nbsp;&nbsp;&lt;interval monthDay="1"/&gt;<br>&nbsp;&nbsp;&lt;interval monthDay="15"/&gt;<br>&lt;/intervals/&gt;</code></pre></div></div></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><div class="codeSnippet"><a class="codeSnippetCopyButton" role="button">Copy</a><div class="codeSnippetBody"><pre><code>&lt;interval monthDay="Third" weekDay="Thursday"/&gt;</code></pre></div></div></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/r2345998-2ead-4894-bb50-1054a9109876" --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='22:30:00'> <intervals> <interval hours='4'/> </intervals> <intervals> <interval weekDay='Sunday'/> </intervals> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"` ``

#### Response Code

200

#### Response Body

For a virtual connection task, the response includes a `virtualConnection` element in place of `workbook` or `datasource`, a `transactionLevel` attribute, and a `startingItemIds` element if starting tables were set.

```
<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 request did not include a valid schedule payload.</td></tr><tr><td>400</td><td>409004</td><td>Invalid parameter</td><td>A value in the request is invalid or missing. This includes an invalid or missing schedule or interval value, or <code>start</code> and <code>end</code> times that are not valid for the schedule. For hourly and daily schedules that use hour intervals, the difference between <code>start</code> and <code>end</code> must be a multiple of one hour. This error also includes <code>transactionLevel</code> sent for a task that is not a virtual connection task, a <code>startingItemIds</code> entry that is not a valid ID, or more <code>startingItemIds</code> entries than the maximum allowed per request.</td></tr><tr><td>400</td><td>400225</td><td>Duplicate table ID</td><td><code>startingItemIds</code> contains the same table ID more than once.</td></tr><tr><td>400</td><td>400223</td><td>Table not found</td><td>A table ID in <code>startingItemIds</code> is not in the virtual connection's active revision.</td></tr><tr><td>400</td><td>400224</td><td>Table not in extract mode</td><td>A table ID in <code>startingItemIds</code> refers to a table that is in live mode.</td></tr><tr><td>401</td><td>401002</td><td>Unauthorized Access</td><td>The authentication token provided in the request header was invalid or has expired.</td></tr><tr><td>403</td><td>403004</td><td>Unauthorized Access</td><td>The user is not authorized to make this request.</td></tr><tr><td>403</td><td>403200</td><td>Virtual connection task forbidden</td><td>The user cannot see, or cannot manage or refresh the extract of, the virtual connection that the task refreshes.</td></tr><tr><td>404</td><td>404026</td><td>Task not found</td><td>The task does not exist, is not an extract refresh task, or targets content that no longer exists.</td></tr><tr><td>404</td><td>404023</td><td>Schedule not found</td><td>The task's existing schedule could not be found while merging the new schedule values.</td></tr><tr><td>405</td><td>405000</td><td>Method not allowed</td><td>The site is not on Tableau Cloud, or the task refreshes a virtual connection and virtual connection custom-schedule tasks are disabled for the site.</td></tr><tr><td>409</td><td>409130</td><td>Task state invalid</td><td>The stored virtual connection task is in an unexpected state and must be repaired or recreated.</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).