Extract and Encryption Methods

Extracts(Link opens in a new window) 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 or Update Site methods
Set the scope of encryption to be all extracts on a site, or allow the users to use: Publish Data Source, Publish Workbook, Update Data Source, or Update Workbook 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(Link opens in a new window).

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(Link opens in a new window).

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(Link opens in a new window)

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, Add workbook to server schedule, and Add virtual connection to server 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(Link opens in a new window)

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(Link opens in a new window)

JWT Access Scope: tableau:tasks:create

For more information, see Access scopes for UATs(Link opens in a new window) (Cloud) and access scopes for connected apps: Cloud(Link opens in a new window), Server-Windows(Link opens in a new window), or Server-Linux(Link opens in a new window).

URI

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

URI Parameter Values

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

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.

`extractRefresh type`	The type of extract refresh being scheduled. Valid values include: `FullRefresh` `IncrementalExtract`
`extractRefresh transactionLevel`	(Optional) : Only used with a virtual connection. Optional. DATABASE or TABLE. Default is DATABASE. If set to DATABASE: If any table extract refresh fails, none of the extracts are updated. If set to TABLE: If a table extract fails, only that table's extract isn't updated.
`workbook id` or `datasource id` or `virtualConnection id`	The LUID of the workbook, data source, or virtual connection that is the target of the custom schedule.
`startingItemId`	Only used with a virtual connection, when `extractRefresh type` is `FullRefresh` The LUID of an extract table in the virtual connection. You may have more than one `<startingItemId>` element inside of a `<startingItemIds>` element. See Virtual Connection Example.
`tableLuid`	Only used with a virtual connection, when `extractRefresh type` is `IncrementalExtract` The LUID of an extract table in the virtual connection. You may have more than one `<tableLiud>` element inside of a `<tableLiuds>` element. See Virtual Connection Example.

schedule frequency

(Required to create subscription) enumeration: The scheduled frequency for triggering the task. Valid values include:

Hourly
Daily
Weekly
Monthly

frequencyDetails start (Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.

frequencyDetails end

(Required to create subscription) time: If the schedule frequency is Hourly, or Daily with an interval of hours less than 24, then end is the time of day on which scheduled jobs should stop being run. The valid format is HH:MM:SS. 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 frequencyDetail would be:

<frequencyDetail start="20:45:00" end="21:45:00">
  . . .
</frequencyDetail>

interval {interval type}

(Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in the start and end values of the frequencyDetails of the schedule. The type and valid values for an interval expression depend on the declared frequency of the schedule as follows:

Frequency	Valid interval values
`Hourly`	The value of an interval for an `Hourly` schedule can be only one of either: `hours="1"` The number of hours between jobs. `1` is the only valid value. `minutes="60"` The number of minutes between jobs. `60` is the only valid value. `weekDay="weekday"` The weekday(s) the job will be run on. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday`. For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in `frequencyDetails` use an interval like: `<intervals> <interval hours="1"/> <interval weekDay="Sunday"/> <interval weekDay="Wednesday"/> <intervals>`
`Daily`	The value of `Daily` can have multiple `weekday` elements, but only one `hours` declaration. An `hours` interval is required. `hours="interval"` The interval between execution of jobs on the weekday(s) specified. Valid values are `2, 4, 6, 8, 12, or 24`. Note that if the `interval` value of a daily schedule is less than `24`, a `frequencyDetail end` time must be supplied. `weekDay="weekday"` The weekday(s) the job will be run on. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday`. For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in `frequencyDetails` use an interval like: `<intervals> <interval hours="4"/> <interval weekDay="Sunday"/> <interval weekDay="Wednesday"/> <intervals>`
`Weekly`	`weekDay="weekday"` The day of the week the schedule should run on. You can only specify a single day for a Weekly schedule. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.`
`Monthly`	The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval: Specify the day(s) using the number of the day in the month; `monthDay="day"` The number of the day of the month. Valid values are the whole numbers `1` to `31` or `LastDay`. If you specify `monthDay` by day number then you can use multiple `interval` instances to choose for the job to run on multiple days in the month. If you use `LastDay` then only one instance of `interval` can be used in the schedule to specify the last day of the month. Specify the day by describing which occurrence of a weekday within the month. `monthDay="occurrence_of_weekday" Weekday="weekday"` The occurrence of the specified weekday within the month when a job should be run. Valid values for `occurrencee_of_weekday` are `First, Second, Third, Fourth, Fifth, or LastDay`. Valid values for `weekday` are `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday`. If the value is `lastDay` then the job will run on the last occurrence of the specified weekday in the month. For example, to make a schedule that that would run a job on the third Thursday of each month, you would use: `<interval monthDay="Third" weekDay="Thursday"/>`

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

HTTP status	`error` Code	Condition	Details
400	400000	Bad Request	The content of the request body is missing or incomplete, or contains malformed XML.
400	400225	Duplicate starting item	`startingItemIds` contains a duplicate table LUID.
409	409090	Extract operation not allowed	The virtual connection has no extract-configured tables; all tables are live.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
404	404026	Task not found	The task for the extract refresh could not be found.
409	409004	invalid parameter value	The request is malformed or contains an invalid or missing schedule or interval parameter value. When the difference between `start` and `end` times are not increments of one hour, this error will result.

For more information, see Handling Errors.

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(Link opens in a new window).

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

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The LUID of the site.
workbook-id	The LUID of the workbook.
encryption-flag	If `true`, then Tableau will attempt to encrypt the created extracts. If `false`, or no `encrypt` 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 `encrypt` equals `true` and encryption is disabled in the site or workbook.

Request Body

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

Request Parameter Values

datasource-id	LUID of the embedded data source to be extracted.
extract-all-datasources-flag	Boolean. If `true`, then all data sources in the workbook will have an extract created for them. If `false`, then a data source must be supplied in the request.

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(Link opens in a new window) (Cloud) and access scopes for connected apps: Cloud(Link opens in a new window), Server-Windows(Link opens in a new window), or Server-Linux(Link opens in a new window).

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.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not POST.
409	409070	Invalid request method	The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

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

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The LUID of the site.
datasource-id	The LUID of the datasource.
encryption-flag	If `true`, then Tableau will attempt to encrypt the created extracts. If `false`, or no `encrypt` 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 `encrypt` equals `true` and encryption is disabled in the site or workbook.

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

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.

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not POST.
409	409070	Invalid request method	The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

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

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

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

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

Response Code

200

Response Body

None

Version

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

Errors

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

For more information, see Handling Errors.

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(Link opens in a new window), Permissions(Link opens in a new window), Access scopes for UATs(Link opens in a new window) (Cloud), and access scopes for Cloud(Link opens in a new window), Server-Windows,(Link opens in a new window) or Server-Linux(Link opens in a new window).

URI

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

URI Parameter Values

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The LUID for the site.
virtualconnection-id	The LUID for the virtual connection whose extract is to be deleted.

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

HTTP status	`error` Code	Condition	Details
400	409128	No extract to delete.	The virtual connection has no extract. Neither the active revision nor any of its tables has extracts enabled.
400	409099	Unable to delete the extract.	A generic error occurred while converting the virtual connection to live and deleting its extract.
403	409098	User not authorized to delete the extract.	The user must be able to see the virtual connection and must have permission to convert its extract to live.
404	404049	Virtual connection not found.	Check the virtual connection LUID. This error also occurs if the virtual connection has no active revision.

For more information, see Handling Errors.

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

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The LUID of the site.
datasource-id	The LUID of the workbook containing the extract to be deleted.

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

Response Code

200

Response Body

None.

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not POST.
409	409070	Invalid request method	The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

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

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The LUID of the site.
datasource-id	The LUID of the datasource whose extract is to be deleted.

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

Response Code

204 No Content

Response Body

None.

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Bad request	The content of the request body is missing or incomplete, or contains malformed XML.
404	404000	Site not found	The specified site doesn't correspond to an existing site.
405	405000	Invalid request method	Request type was not POST.
409	409070	Invalid request method	The data source cannot be extracted because it is file based or in another unsupported form.

For more information, see Handling Errors.

Example

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

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The LUID of the site that contains the extract refresh task.
task-id	The LUID of the extract refresh task to remove.

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)

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.

Errors

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

For more information, see Handling Errors.

Encrypt Extracts in a Site

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

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

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

Response Code

200

Response Body

None

Version

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

Errors

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

For more information, see Handling Errors.

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

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that the user is a member of.
task-id	The ID of the extract refresh that you want information about.

JWT Access Scope

Available in API 3.20 (Tableau Cloud June 2023).

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

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.

Errors

403	403004	Operation unauthorized	The user is not authorized to get the task.
404	404026	Task not found	The task ID in the URI doesn't correspond to an existing task.
405	405000	Invalid requests method	Request type was not GET

For more information, see Handling Errors.

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

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

JWT Access Scope

Available in API 3.20 (Tableau Cloud June 2023).

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

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.

Errors

405

405000

Invalid requests method

Request type was not GET

For more information, see Handling Errors.

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 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(Link opens in a new window).

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

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

JWT Access Scope

Not available.

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.

Errors

HTTP status	`error` Code	Condition	Details
400	400006	Invalid page number	The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
400	400047	Invalid schedule type	The schedule type does not represent an extract refresh task. (For example, it might be a subscription task.)
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404	Schedule not found	The schedule ID in the URI doesn't correspond to an existing schedule.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

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

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

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

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

Response Code

200

Response Body

None

Version

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

Errors

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

For more information, see Handling Errors.

Run Extract Refresh Task

Runs the specified extract refresh task.

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 method to create the task. To get information about the extract refresh task, use the 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 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

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The ID of the site that the user is a member of.
task-id	The ID of the extract refresh task that you want to run.

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)

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.

Errors

HTTP status	`error` Code	Condition	Details
400	400047	Extract refresh error	The task specified is not an extract refresh task.
400	409090	Extract operation not allowed	The extract operation is not allowed for the asset that the task refreshes.
403	403004	Operation on resource unauthorized	The user is not authorized to run the task.
403	409082	Run now disabled	The Run Now setting is disabled for the site.
404	404003	Unknown resource	The task ID in the URI doesn't correspond to an existing task.
404	404049	Virtual connection not found	The virtual connection that the task refreshes no longer exists.
405	405000	Method not allowed	The request type was not POST.
409	409093	Operation already in queue	The extract refresh job is already in the queue.

For more information, see Handling Errors.

Example

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

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(Link opens in a new window)

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(Link opens in a new window)

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(Link opens in a new window) (Cloud) and access scopes for connected apps: Cloud(Link opens in a new window), Server-Windows(Link opens in a new window), or Server-Linux(Link opens in a new window).

URI

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

URI Parameter Values

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The LUID for the site.
task-id	The LUID of the extract refresh task. Use Get extract refresh tasks on site to find tasks by name.

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.

extractRefresh type

enumeration: The type of extract refresh being scheduled. Valid values include:

FullRefresh
IncrementalRefresh

workbook id
or datasource id
or virtualConnection id LUID: The LUID of the workbook, data source, or virtual connection that is the target of the custom schedule.

extractRefresh transactionLevel

(Optional) : Only used with a virtual connection.

Optional. DATABASE or TABLE. Default is DATABASE.

If set to DATABASE: If any table extract refresh fails, none of the extracts are updated.
If set to TABLE: If a table extract fails, only that table's extract isn't updated.

startingItemId

Only used with a virtual connection, when extractRefresh type is FullRefresh

The LUID of an extract table in the virtual connection. You may have more than one <startingItemId> element inside of a <startingItemIds> element. See Virtual Connection Example.

tableLuid

Only used with a virtual connection, when extractRefresh type is IncrementalExtract

The LUID of an extract table in the virtual connection. You may have more than one <tableLiud> element inside of a <tableLiuds> element. See Virtual Connection Example.

schedule frequency

enumeration: The scheduled frequency for triggering the extract refresh. Valid values include:

Hourly
Daily
Weekly
Monthly

frequencyDetails start time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.

frequencyDetails end

time: If the schedule frequency is Hourly, or Daily with an interval of hours less than 24, then end is the time of day on which scheduled jobs should stop being run. The valid format is HH:MM:SS. 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 frequencyDetail would be:

<frequencyDetail start="20:45:00" end="21:45:00">
    . . . 
</frequencyDetail>
                                            

interval {interval type}

string: Defines when and how often a scheduled job executes within the time parameters set in the start and end values of the frequencyDetails of the schedule. The type and valid values for an interval expression depend on the declared frequency of the schedule as follows:

Frequency	Valid interval values
`Hourly`	The value of an interval for an `Hourly` schedule can be only one of either: `hours=“1"` The number of hours between jobs. `1` is the only valid value. `minutes=“60"` The number of minutes between jobs. `60` is the only valid value. `weekDay=“weekday"` The weekday(s) the job will be run on. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday`. For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in `frequencyDetails` use an interval like: Copy `<intervals> <interval hours="1"/> <interval weekDay="Sunday"/> <interval weekDay="Wednesday"/> <intervals>`
`Daily`	The value of `Daily` can have multiple `weekday` elements, but only one `hours` declaration. An `hours` interval is required. `hours=“interval"` The interval between execution of jobs on the weekday(s) specified. Valid values are `2, 4, 6, 8, 12, or 24`. Note that if the `interval` value of a daily schedule is less than `24`, a `frequencyDetail end` time must be supplied. `weekDay=“weekday"` The weekday(s) the job will be run on. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday`. For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in `frequencyDetails` use an interval like: Copy `<intervals> <interval hours="4"/> <interval weekDay="Sunday"/> <interval weekDay="Wednesday"/> <intervals>`
`Weekly`	`weekDay=“weekday"` The day of the week the schedule should run on. You can only specify a single day for a Weekly schedule. Valid values are: `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.`
`Monthly`	The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval: Specify the day(s) using the number of the day in the month; `monthDay=“day"` The number of the day of the month. Valid values are the whole numbers `1` to `31` or `LastDay`. If you specify `monthDay` by day number then you can use multiple `interval` instances to choose for the job to run on multiple days in the month. If you use `LastDay` then only one instance of `interval` 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: Copy `<intervals/> <interval monthDay="1"/> <interval monthDay="15"/> </intervals/>` Specify the day by describing which occurrence of a weekday within the month. `monthDay=“occurrence_of_weekday" Weekday=“weekday"` The occurrence of the specified weekday within the month when a job should be run. Valid values for `occurrencee_of_weekday` are `First, Second, Third, Fourth, Fifth, or LastDay`. Valid values for `weekday` are `Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday`. If the value is `lastDay` then the job will run on the last occurrence of the specified weekday in the month. For example, to make a schedule that that would run a job on the third Thursday of each month, you would use: Copy `<interval monthDay="Third" weekDay="Thursday"/>`

Virtual Connection Example

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

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

For more information, see Handling Errors.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help

Extract and Encryption Methods

About Extract Encryption

Use Postman

Create Cloud Extract Refresh Task

URI

URI Parameter Values

Request Body

Request Attributes

Virtual Connection Example

cURL Request Example

Response Body

Errors

Create Extracts for Embedded Data Sources in a Workbook

URI

Path Parameter Values

Request Body

Request Parameter Values

Permissions

Access Scope

Response Code

Response Body

Version

Errors

Example

Create an Extract for a Data Source

URI

Parameter Values

Request Body

Permissions

Access Scope

Response Code

Response Body

Version

Errors

Example

Decrypt Extracts in a Site

URI

Parameter Values

Request Body

Permissions

Access Scope

Response Code

Response Body

Version

Errors

Delete Extracts from Virtual Connection

URI

URI Parameter Values

Request Body

cURL Request Example

Response Code

Response Body

Errors

Delete Extracts of Embedded Data Sources from a Workbook

URI

Path Parameter Values

Permissions

Request Body

Request Parameter Values

Access Scope

Response Code

Response Body

Version

Errors

Example

Delete Extract from Data Source

URI

Parameter Values

Permissions

Access Scope

Response Code

Response Body

Version

Errors

Example

Delete Extract Refresh Task

URI

Parameter Values

JWT Access Scope