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.
Create Cloud Extract Refresh Task
Creates a custom schedule for an extract refresh on Tableau Cloud.
For Tableau Server, see Add data source to server schedule and
Add workbook to server schedule.
Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)
License: No additional license required.
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
(this scope is included in the scope: tableau:tasks
)
Access Scopes Overview:
Cloud(Link opens in a new window)
URI
POST /api/api-version/sites/site-luid/tasks/extractRefreshes
URI Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions.
|
site-luid | 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.
extractRefresh type
|
enumeration: The type of extract refresh being scheduled. Valid values include:
|
workbook id or datasource id |
LUID: The LUID of the workbook or datasource that is the target of the custom schedule. |
schedule frequency
|
(Required to create subscription) enumeration: The scheduled frequency for triggering the task. Valid values include:
|
||||||||||
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
|
||||||||||
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:
|
cURL Request Example
curl --location --request POST "qa-near.tsi.lan/api/3.24/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>"
Response Code
200
Response Body
<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. |
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.24 . 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.
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.24/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.24 . 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.
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.24/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(Link opens in a new window).
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.24 . 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.
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 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/workbookss/workbook-id/deleteExtract
Path Parameter Values
api-version | The version of the API to use, such as 3.24 . 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.
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.24/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 the Extract from a Data Source
Delete the extract of a data source in a site.
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.24 . 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.
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
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/deleteExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"
Response body:
None.
Delete Extract Refresh Task
Deletes the specified extract refresh task on Tableau Server or Tableau Cloud.
URI
DELETE /api/api-version/sites/site-luid/tasks/extractRefreshes/task-luid
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-luid | The LUID of the site that contains the extract refresh task. |
task-luid | The LUID of the extract refresh task to remove. |
JWT Access Scope
tableau:tasks:delete
(this scope is included in the scope: tableau:tasks
)
This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
Request Body
None
Permissions
Tableau Server 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. 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
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).
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.24 . 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.
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 the specified extract refresh task.
This method shows you information about the scheduled task for the data source extract or a published workbook that connects to the data extract.
Note: This method doesn't work for scheduled tasks associated with virtual connection extracts.
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.24 . 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
tableau:tasks:read
(this scope is included in the scope: tableau:tasks
)
This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
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.
Tableau Server Request
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 Request
For Tableau Cloud an extract refresh task with its frequency is returned.
Response for a server schedule on Tableau Server:
<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. 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, or the task is associated with a virtual connection instead of a workbook or published data source. |
405 | 40500 | 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.
This method shows you information about the scheduled tasks on the specified site for data source extracts or a published workbooks that connect to data extracts.
Note: Virtual connection extracts are listed in the response, but are not identified by an element the way that workbooks and published data sources are.
URI
GET /api/api-version/sites/site-id/tasks/extractRefreshes
Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions. |
site-id | The ID of the site that the user is a member of. |
JWT Access Scope
tableau:tasks:read
(this scope is included in the scope: tableau:tasks
)
This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
cURL Example
curl "http://MY-SERVER/api/3.24/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.
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. For more information, see REST API and Resource Versions.
Errors
405 | 40500 | 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.
For more information on access scopes and connected apps, see Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window).
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>
... additional extract refresh tasks ...
</extracts>
</tsResponse>
Version
Version 2.2 and later. 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.24/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="2" />
<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>
</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(Link opens in a new window).
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.24 . 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.
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.
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).
This method runs the scheduled task for the data source extract or the published workbook that connects to the data 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.
Note: This method doesn't work for scheduled tasks associated with virtual connection extracts.
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.24 . 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
tableau:tasks:run
(this scope is included in the scope: tableau:tasks
)
This scope can be used to enable this REST method to be called from a connected app. For more information, see Tableau Cloud connected app scopes(Link opens in a new window). Available in API 3.20 (Tableau Cloud June 2023). Not available for Tableau Server.
Request Body
You must include a valid request with the POST operation. Currently, the request body can be empty. In the future, you might be able to set options for the task.
<tsRequest>
</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
<tsResponse>
<job id="JOB_ID" mode="MODE" type="RefreshExtract" />
</tsResponse>
Version
Version 2.6 and later. For more information, see REST API and Resource Versions.
Errors
403 | 403004 | Operation unauthorized | The user is not authorized to get the task, or the extract isn't associated with a workbook or published data source. |
403 | 403047 | Extract refresh error | The task specified is not an extract refresh task. |
404 | 404026 | Task not found | The task ID in the URI doesn't correspond to an existing task. |
405 | 40500 | Invalid requests method | 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.24/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
Example response:
<tsResponse version-and-namespace-settings>
<job id="7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6" mode="Asynchronous" type="RefreshExtract" />
</tsResponse>
Update Cloud Extract Refresh Task
Updates a custom schedule for 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. 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:task:update
(this scope is included in the scope: tableau:tasks
)
Access Scopes Overview:
Cloud(Link opens in a new window)
URI
POST /api/api-version/sites/site-luid/tasks/extractRefreshes/task-luid
URI Parameter Values
api-version | The version of the API to use, such as 3.24 . For more information, see REST API and Resource Versions.
|
site-luid | The LUID for the site. |
task-luid | 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:
|
||||||||||
workbook id or datasource id |
LUID: The LUID of the workbook or datasource that is the target of the custom schedule. | ||||||||||
schedule frequency
|
enumeration: The scheduled frequency for triggering the extract refresh. Valid values include:
|
||||||||||
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
|
||||||||||
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:
|
cURL Request Example
curl --location --request POST "qa-near.tsi.lan/api/3.24/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='23:00:00'> <intervals> <interval hours='4'/> </intervals> <intervals> <interval weekDay='Sunday'/> </intervals> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"
Response Code
200
Response Body
<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. |
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. |
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.