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.22. For more information, see REST API and Resource Versions.
site-luid The LUID for the site.

Request Body

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

Copy 
{
  "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:
  • FullRefresh
  • IncrementalRefresh
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:
  • 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:

FrequencyValid 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>
WeeklyweekDay=“weekday" The day of the week the schedule should run on. Multiple days can be specified 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:
    Copy
    <interval monthDay="Third" weekDay="Thursday"/>

cURL Request Example

curl --location --request POST "qa-near.tsi.lan/api/3.22/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

Copy 
<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>
Copy 
{
  "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.22. 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.22/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.22. 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.22/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.22. 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.22. 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.22/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.22. 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.22/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.22. 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.22. 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.

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

Copy 
<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>
Copy 
[
  {
    "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 frequencye is returned.

Response for a server schedule on Tableau Server:

Copy 
<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>
Copy 
{
  "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.
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.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. 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.22/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 Request

For Tableau Server a lst of extract refresh tasks with their server schedules is returned.

Copy 
<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>
Copy 
{
  "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 Request

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

Response for a server schedule on Tableau Server:

Copy 
<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>
Copy 
{
  "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.22/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.22. 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.

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.22. 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.
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.22/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

PUT /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.22. 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

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

Copy 
{
  "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		 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:
  • 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:

FrequencyValid 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>
WeeklyweekDay=“weekday" The day of the week the schedule should run on. Multiple days can be specified 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"/>

cURL Request Example

curl --location --request PUT "qa-near.tsi.lan/api/3.22/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

Copy 
<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>
Copy 
{
  "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.


Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!