Jobs, Tasks, and Schedules Methods

Using the jobs, tasks, and schedules methods of the Tableau Server REST API you can do the operations listed in the following categories:

Extract Refresh Tasks: (task to refresh the extract of a data source of a site) - See Extract and Encryption Methods

Data Acceleration Tasks: (Tableau Server only)

Get a list of data acceleration tasks for a site
Delete a data acceleration task

Jobs: (work items of a task carried out by the Tableau service)

Get a filtered, sorted list of jobs for a site and the details of specific jobs
Cancel jobs that are in progress

Server Schedules (Tableau Server only): (the configuration of when tasks will be initiated on Tableau Server)

For Tableau Cloud, you configure the frequency attributes of a Cloud task, instead of adding the task to a separate Server Schedule as described for Tableau Server on this page. See Extract and Encryption Methods and Subscription Methods to schedule tasks on Tableau Cloud.

Create, update, and delete schedules
Create, update, and delete custom schedules for extract refresh and subscription tasks
List schedules, and get the details of specific tasks, jobs and schedules on a site

This functionality relates to the UI elements and concepts described at: Extract Refresh Schedules(Link opens in a new window).

The Tableau Server Client library(Link opens in a new window), a Python wrapper for the REST API, offers the following related items: Jobs Methods(Link opens in a new window); and Schedules Methods(Link opens in a new window).

Add Data Source to Server Schedule

Adds a task to refresh a data source to an existing server schedule on Tableau Server.
For Tableau Cloud, see Create Cloud Extract Refresh Task.

URI

PUT /api/api-version/sites/site-id/schedules/schedule-id/datasources

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 contains the view.
schedule-id	The ID of the schedule that you are associating with the data source.

Request Body

<tsRequest>
  <task>
    <extractRefresh>
      <datasource id="datasource-id" />
    </extractRefresh>
  </task>
</tsRequest>

Attribute Values

datasource-id

The ID of the data source to add to the schedule.

Permissions

Tableau Server users who are not server administrators or site administrators can only add a data source to a schedule if they own the data source, or are the project leader for the project that contains the data source.

Response Code

200

Response Body

<tsResponse>
  <task>
    <extractRefresh>
      <schedule id="schedule-id" />
      <datasource id="datasource-id" />
    </extractRefresh>
  </task>
</tsResponse>

Version

Version 2.8 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.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403032	Update Forbidden	A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI is unknown.
404	404004	Resource not found	The data source ID in the request body is unknown.
405	405000	Invalid request method	Request type was not PUT.
500	500000	Internal Server Error	The schedule ID in the URI is unknown.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/datasources" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml

Content of add-to-schedule.xml:

<tsRequest>
  <task>
    <extractRefresh>
      <datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" />
    </extractRefresh>
  </task>
</tsRequest>

Example response:

<tsResponse>
  <task>
    <extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
      <schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
      <datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" />
    </extractRefresh>
  </task>
</tsResponse>

Add Workbook to Server Schedule

Adds a task to refresh or accelerate a workbook to an existing schedule on Tableau Server.

The task type must match the schedule type. For a list of schedule types, see Create a Schedule.
For Tableau Cloud, see Create Cloud Extract Refresh Task.

This method is not available for Tableau Cloud.

Starting in Tableau version 2022.1 (API v3.16), with the introduction of View Acceleration(Link opens in a new window), the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases resulting in error codes being returned.

URI

PUT /api/api-version/sites/site-id/schedules/schedule-id/workbooks

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 contains the view.
schedule-id	The ID of the schedule that you are associating with the workbook.

Request Body

<tsRequest>
  <task>
    <extractRefresh>
      <workbook id="workbook-id" />
    </extractRefresh>
  </task>
  <task>
    <dataAcceleration>
      <workbook id="workbook-id" />
    </dataAcceleration>
  </task>
</tsRequest>

Attribute Values

workbook-id

The ID of the workbook to add to the schedule.

Permissions

Only Tableau Server users who are server administrators or site administrators can add a workbook to a data acceleration schedule. Tableau Server users who are not server administrators or site administrators can only add a workbook to other types of schedules if they own the workbook, or are the project leader for the project that contains the workbook.

Response Code

200

Response Body

<tsResponse>
  <task>
    <extractRefresh id="extractRefresh-id" type="extractRefresh-type">
      <schedule id="schedule-id" />
      <workbook id="workbook-id" />
    </extractRefresh>
  </task>
</tsResponse>

Version

Starting in Tableau Server 10.5 (API 2.8) you can add a task to refresh a workbook extract. In Tableau Server 2020.2 (API 3.8) through 2021.4 (API 3.15), you can add a task to add data acceleration to a workbook.

Starting in Tableau version 2022.1 (API v3.16), with the introduction of View Acceleration(Link opens in a new window), the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases resulting in error codes being returned.

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.
401	401002	Unauthorized Access	The authentication token provided in the request header was invalid or has expired.
403	403032	Update Forbidden	A non-administrator user called this method, but the caller doesn't have sufficient permissions.
404	404000	Site not found	The site ID in the URI is unknown.
404	404006	Resource not found	The workbook ID in the request body is unknown.
405	405000	Invalid request method	Request type was not PUT.
500	500000	Internal Server Error	The schedule ID in the URI is unknown.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/sites/ 1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/workbooks" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"

Content of add-to-schedule.xml:

<tsRequest>
  <task>
    <extractRefresh>
      <workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
    </extractRefresh>
  </task>
</tsRequest>

Example response:

<tsResponse>
  <task>
    <extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
      <schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
      <workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
    </extractRefresh>
  </task>
</tsResponse>

Cancel Job

Cancels a job specified by job ID. To get a list of job IDs for jobs that are currently queued or in-progress, use the Query Jobs method.

The following jobs can be canceled using the Cancel Job method:

Full extract refresh
Incremental extract refresh
Subscription
Flow Run
Data Acceleration (Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)
Bridge full extract refresh
Bridge incremental extract refresh
Queue upgrade Thumbnail (Job that puts the upgrade thumbnail job on the queue)
Upgrade Thumbnail

URI

PUT /api/api-version/sites/site-id/jobs/job-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 where the job is running.
job-id	The ID of the job to cancel.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

None

Version

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

Errors

HTTP status	`error` Code	Condition	Details
403	403032	Update forbidden	A non-administrator user tried to cancel a job.
403	403091	Can not cancel job, because it's already complete.	The job ID provided is for a job that has already succeeded or failed.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	405000	Invalid request method	Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/jobs/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Create Server Schedule

Creates a new server schedule on Tableau Server.
For Tableau Cloud, see Create Cloud Extract Refresh Task and Create subscription.

Schedules are not specific to sites. For more information, see Creating a Flow Schedule(Link opens in a new window), Extracts and Refresh Schedules(Link opens in a new window) and Create or Modify a Schedule(Link opens in a new window) in the Tableau Server documentation. Scheduling flows requires Tableau Prep Conductor to be enabled on your Tableau Server. For more information, see Enable Tableau Prep Conductor(Link opens in a new window).

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

POST /api/api-version/schedules

Parameter Values

api-version The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.

Request Body

<tsRequest>
  <schedule name="schedule-name"
	priority="schedule-priority"
	type="schedule-type"
	frequency="schedule-frequency"
	executionOrder="schedule-execution-order">
	  <frequencyDetails start="start-time" end="end-time">
	    <intervals>
	      <interval interval-expression />
	    </intervals>
 	  </frequencyDetails>
  </schedule>
</tsRequest>

Attribute Values

schedule-name	The name to give to the schedule. This name identifies the schedule in the server environment when users select a schedule and manage schedule information.
schedule-priority	An integer value between 1 and 100 that determines the default priority of the schedule if multiple tasks are pending in the queue. Lower numbers have higher priority.
schedule-type	`Flow` to create a flow schedule, `Extract` to create an extract refresh schedule, `Subscription` to create a subscription schedule, or `DataAcceleration` to create a data acceleration schedule. (Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)
schedule-execution-order	`Parallel` to allow jobs associated with this schedule to run at the same time, or `Serial` to require the jobs to run one after the other.
schedule-frequency	This represents the granularity of the schedule. `Hourly`. Jobs can be scheduled to run at intervals specified in run one or more times per day at intervals specified in minutes or hours. Valid intervals are 15 and 30 minutes and 2, 4, 6, 8, and 12 hours. `Daily`. Jobs can be scheduled to run once per day. `Weekly`. Jobs can be scheduled to run one or more times per week. `Monthly`. Jobs can be scheduled to run once per month on a specific day. The value you provide for schedule-frequency determines whether you must include an end-time value, and what is required in the contents of the <intervals> element.
start-time	The time of day on which scheduled jobs should run (or if the frequency is hourly, on which they should start being run), in the format `HH:MM:SS` (for example, `18:30:00`). This value is required for all schedule frequencies. The entered time will be applied based on the time zone of your server.
end-time	If the schedule frequency is `Hourly`, the time of day on which scheduled jobs should stop being run, in the format `HH:MM:SS` (for example, `23:30:00`). Hourly jobs will occur at the specified intervals between the start time and the end time. For other schedule frequencies, this value is not required; if the attribute is included, it is ignored. The entered time will be applied based on the time zone of your server.
interval-expression	A value that specifies the interval between jobs associated with the schedule. The value you specify here depends on the value specified in schedule-frequency. `Hourly` The interval expression is only one of the following: `hours="interval"` where interval is `1`, `2`, `4`, `6`, `8`, or `12`, representing how many hours between jobs. `minutes="interval"` where interval is `15` or `30`, representing how many minutes between jobs. You can specify an interval in hours or minutes, but not both. `Daily` If the schedule frequency is `Daily`, no interval is specified. Any information specified in the <intervals> element is ignored. `Weekly` The interval expression is `weekDay="weekday"`, where weekday is `Sunday`, `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, or `Saturday`. You can specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week. `Monthly` The interval expression is `monthDay="day"`, where day is either the day of the month (`1`, `2`, etc.) or `LastDay`. Note: If you want to specify multiple days in the month, you can do this using the web interface. You cannot create or update such a monthly schedule using REST API.

Permissions

This method can only be called by server administrators.

Response Code

201

Response Body

<tsResponse>
  <schedule id="schedule-id"
    name="schedule-name"
	state="Active-or-Suspended"
    priority="schedule-priority"
	createdAt="datetime-created"
	updatedAt="datetime-updated"
	type="Extract-or-Subscription-or-Flow"
	frequency="schedule-frequency"
	nextRunAt="datetime-next-run"
	executionOrder="Parallel-or-Serial">
	  <frequencyDetails frequency-expression >
	    <intervals>
	      <interval interval-expression />
	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsResponse>

Version

Version 2.3 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.
400	400064	Error creating schedule	An unspecified error occurred while trying to create the schedule.
400	409004	Bad request	The content of the request body is missing or incomplete. For hourly, daily, or monthly schedules, this often means that the content of the <intervals> element does not match the expected format. The <detail> element of the error provides detail about the expected format.
405	405000	Invalid request method	Request type was not POST.
409	409021	Schedule name conflict	The schedule name in the request already belongs to an existing schedule.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/schedules/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-schedule.xml

Content of create-schedule.xml for an hourly schedule

<tsRequest>
  <schedule name="hourly-schedule-1"
    priority="50"
	type="Extract"
	frequency="Hourly"
	executionOrder="Parallel">
	  <frequencyDetails start="18:30:00" end="23:00:00">
		<intervals>
		  <interval hours="2" />
		</intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse >
  <schedule
    id="4d652179-36bf-47e4-a9dc-e069227c72d0"
    name="hourly-schedule-1"
    state="Active"
    priority="50"
    createdAt="2016-05-07T01:51:19Z"
    updatedAt="2016-05-07T01:51:19Z"
    type="Extract"
    frequency="Hourly"
    nextRunAt="2016-05-07T03:30:00Z"
    executionOrder="Parallel">
      <frequencyDetails start="18:30:00" end="23:00:00">
        <intervals>
           <interval hours="2" />
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>

Content of create-schedule.xml for a daily schedule

For a daily schedule, frequencyDetails is set to Daily. The start attribute is required. No intervals element is required. Daily schedules on any recurrence must have the same start and end minute. The hour can be different. However, if the daily schedule is set to only happen once a day, then it needs only a start time and not an end time.

<tsRequest>
  <schedule
    name="daily-schedule-1"
    priority="50"
    type="Subscription"
    frequency="Daily"
    executionOrder="Parallel">
      <frequencyDetails start="02:15:00" />
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule
	id="4d652179-36bf-47e4-a9dc-e069227c72d0"
	name="daily-schedule-1"
	state="Active"
	priority="50"
	createdAt="2016-05-07T01:43:33Z"
	updatedAt="2016-05-07T01:43:33Z"
	type="Subscription"
	frequency="Daily"
	nextRunAt="2016-05-07T09:15:00Z"
	executionOrder="Parallel">
	  <frequencyDetails start="02:15:00" />
  </schedule>
</tsResponse>

Content of create-schedule.xml for a weekly schedule

For a weekly schedule, frequencyDetails is set to Weekly. A start attribute is required. The intervals element is required, and must include between 1 and 7 interval subelements that contain a weekDay attribute. Valid values for the weekDay attribute are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

<tsRequest>
  <schedule name="weekly-schedule-1"
	priority="50"
	type="Subscription"
	frequency="Weekly"
	executionOrder="Serial">
  	  <frequencyDetails start="18:30:00">
	    <intervals>
	      <interval weekDay="Sunday" />
	      <interval weekDay="Wednesday" />
 	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0"
    name="weekly-schedule-1"
    state="Active"
    priority="50"
    createdAt="2016-05-07T02:01:30Z"
    updatedAt="2016-05-07T02:01:30Z"
    type="Subscription"
    frequency="Weekly"
    nextRunAt="2016-05-09T01:30:00Z"
    executionOrder="Serial">
      <frequencyDetails start="18:30:00">
        <intervals>
          <interval weekDay="Sunday" />
          <interval weekDay="Wednesday" />
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>

Content of create-schedule.xml for a monthly schedule

For a monthly schedule, frequencyDetails is set to Monthly. A start attribute is required. The intervals element is required, and must include 1 interval subelement that contains a monthDay attribute. Valid values for the monthDay attribute are integers between 1 and 31 and the string LastDay.

<tsRequest>
  <schedule name="monthly-schedule-1"
	priority="50"
	type="Subscription"
	frequency="Monthly"
	executionOrder="Parallel">
	  <frequencyDetails start="06:00:00">
	    <intervals>
	      <interval monthDay="15" />
	    </intervals>
	  </frequencyDetails>
  </schedule>
</tsRequest>

Response body

<tsResponse>
  <schedule
	id="4d652179-36bf-47e4-a9dc-e069227c72d0"
	name="monthly-schedule-1"
	state="Active"
	priority="50"
	createdAt="2016-05-07T02:08:25Z"
	updatedAt="2016-05-07T02:08:25Z"
	type="Subscription"
	frequency="Monthly"
	nextRunAt="2016-06-03T13:00:00Z"
	executionOrder="Parallel">
	  <frequencyDetails start="06:00:00">
	    <intervals>
	      <interval monthDay="15" />
	    </intervals>
  	  </frequencyDetails>
  </schedule>
</tsResponse>

Delete Data Acceleration Task

Deletes a data acceleration task.

URI

DELETE /api/api-version/sites/site-id/tasks/dataAcceleration/dataAcceleration-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 contains the task.
dataAcceleration-id	The ID of the task to remove.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

None

Version

In Tableau Server 2020.2 (API 3.8) through 2021.4 (API 3.15) data acceleration is supported.

Starting in Tableau version 2022.1 (API v3.16), with the introduction of View Acceleration(Link opens in a new window), the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases resulting in error codes being returned.

For more information, see REST API and Resource Versions.

Errors

HTTP status	`error` Code	Condition	Details
403	409087	Permission denied	The user isn't authorized to view data acceleration tasks.
403	409087	Permission denied	The user isn't authorized to access the workbook.
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 task.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/dataAcceleration/7a2a7c6d-5e4f-3a2b-1c0d-9e8f7a6b3r4q" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Delete Server Schedule

Deletes the specified schedule on Tableau Server.
For Tableau Cloud, see Delete Extract Refresh Task and Delete Subscription.

URI

DELETE /api/api-version/schedules/schedule-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.
schedule-id	The ID of the schedule to delete. To determine what schedules are available, call List Server Schedules.

Request Body

None

Permissions

This method can only be called by server administrators.

Response Code

204

Response Body

None

Version

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

Errors

HTTP status	`error` Code	Condition	Details
400	400059	Error deleting the schedule.	An unspecified error occurred during the deletion operation.
404	404023	Schedule not found	The specified schedule doesn't correspond to an existing schedule on the site.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Get Data Acceleration Tasks in a Site

Returns a list of data acceleration tasks for the site.

URI

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

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 contains the task.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
<tasks>
 <task>
  <dataAcceleration id="id" consecutiveFailedCount="0" type="DataAccelerationTask">
    <schedule id="id" name="name" state="Active" priority="75" createdAt="2020-02-25T02:49:31Z" updatedAt="2020-02-25T04:00:44Z" type="DataAcceleration" frequency="Hourly" nextRunAt="2020-02-25T08:00:00Z">
     <frequencyDetails start="00:00:00" end="00:00:00">
	  <intervals>
		<interval hours="4"/>
	  </intervals>
     </frequencyDetails>
   </schedule>
   <workbook id="id"/>
  </dataAcceleration>
 </task>
 <task>
 ... additional tasks ...
 </task>
</tasks>
</tsResponse>

Version

For more information, see REST API and Resource Versions.

Errors

403	409087	Permission denied	The user isn't authorized to view data acceleration tasks.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
405	40500	Invalid requests 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/tasks/dataAcceleration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:


<tsResponse version-and-namespace-settings>
  <task>
   <dataAcceleration id="9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c" consecutiveFailedCount="0" type="DataAccelerationTask">
    <schedule id="9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5r4c" name="name" state="Active" priority="75" createdAt="2020-02-25T02:49:31Z" updatedAt="2020-02-25T04:00:44Z" type="DataAcceleration" frequency="Hourly" nextRunAt="2020-02-25T08:00:00Z">
     <frequencyDetails start="00:00:00" end="00:00:00">
      <intervals>
       <interval hours="4"/>
      </intervals>
     </frequencyDetails>
   </schedule>
  <workbook id="9t8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c"/>
 </dataAcceleration>
  </task>
</tsResponse>

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.

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 frequency 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, 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)

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.

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 Response

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

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.

Get Server Schedule

Returns detailed information about the specified server schedule on Tableau Server.

Not available for Tableau Cloud.

Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.

URI

GET /api/api-version/schedules/schedule-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.
schedule-id	The ID of the specific schedule. Note: You can get the schedule id from running the List Server Schedules method. For more information, see Jobs, Tasks, and Schedules Methods

Request Body

None

Permissions

On Tableau Server, any user able to schedule extract refreshes and any site or server administrator can get schedules.

Response Code

200

Response Body

<tsResponse >
   <schedule id = "schedule id"
	name = "schedule-name"
	state="Active-or-Suspended"
	priority= "priority"
	createdAt="datetime-created"
	updatedAt="datetime-last-updated"
	type="schedule-type"
	frequency="extractrefresh-or-flow-or-subscription"
	nextRunAt="datetime-nextrun"
	executionOrder="Parallel-or-Serial" >
	   <frequencyDetails start="time"
		<intervals>
		  <interval schedule-frequency/>
		</intervals>
	   </frequencyDetails>
   </schedule>
</tsResponse>

Version

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

Errors

HTTP status	`error` Code	Condition	Details
404	404027	Schedule not found	The flow ID in the URI doesn't correspond to an existing flow.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/schedules/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
   <schedule id="60456a5c-0293-4fed-9391-6d94a5f42b48"
	name="My Schedule"
	state="Active"
	priority="50"
	createdAt="2020-02-24T22:18:20Z"
	updatedAt="2020-02-24T22:18:20Z"
	type="Extract"
	frequency="Monthly"
	nextRunAt="2020-02-25T19:20:00Z"
	executionOrder="Parallel">
	   <frequencyDetails start="11:20:00">
		<intervals>
		   <interval monthDay="Customized Monthly"/>
		</intervals>
	   </frequencyDetails>
   </schedule>
</tsResponse>

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>

Query Job

Returns status information about an asynchronous process that is tracked using a job. This method can be used to query jobs that are used to do the following:

Import users from Active Directory (the result of a call to Create Group).
Synchronize an existing Tableau Server group with Active Directory (the result of a call to Update Group).
Run extract refresh tasks (the result of a call to Run Extract Refresh Task).
Publish a workbook asynchronously (the result of a call to Publish Workbook).
Run workbook or view subscriptions (the result of a call to Create Subscription or Update Subscription)
Run a flow task (the result of a call to Run Flow Task)
Status of Tableau Server site deletion (the result of a call to asynchronous Delete Site(Link opens in a new window) beginning API 3.18)
Note: To query a site deletion job, the server administrator must be first signed into the default site (contentUrl=" ").

URI

GET /api/api-version/sites/site-id/jobs/job-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 where the job is running.
job-id	The ID of the job to get status information for.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
    <job id="job-id"
     mode="job-mode"
     type="job-type"
     progress="percent-completed"
     createdAt="time-job-created"
     updatedAt="time-job-last-updated"
     completedAt="time-job-completed"
     finishCode="status-code">
        <extractRefreshJob>
            <notes> ... view, workbook, or datasource id and name ... </notes>
        </extractRefreshJob>
        <statusNotes>
            <statusNote type="classifier"
             value="value"
             text="note" /> ... additional job notes ...
        </statusNotes>
    </job>
</tsResponse>

The createdAt, updatedAt, and CompletedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Note: When using this method to query the progress of asynchronous workbook publishing, progress will switch from 0 when the job is in-progress to 100 when it is complete, finishCode will switch from 1 when the job is in-progress to 0 when it is complete, and no <statusNotes> elements are provided.

The finishCode indicates the status of the job: 0 for success, 1 for error, or 2 for canceled.

The <statusNotes> element contains one or more notes that provide details about the status of a job in a format that can be used for logging, auditing, and error recovery. Each status note contains three attributes:

type. An enumerated value (a string) that indicates the classification of the note.
value. A value that indicates the number of records reported by the current status, such as the count of records processed.
text. A description of the status that can be displayed to users. If you are working with a localized (translated) version of Tableau Server, this text is also localized. You should not rely on this text for any application logic. If you need to take action based on a specific status, test the value of the type attribute.

The following table lists job status types. Some values are returned only when the job is synchronizing groups (Update Group).

Type	Value	Text
CountOfUsersAddedToGroup	Integer	Description of how many users were added to the group during the import.
CountOfUsersAddedToSite	Integer	Description of how many users were added to the site during the import.
CountOfUsersWithInsufficientLicenses	Integer	Description of how many users could not have their site role updated due to server lacking sufficient licenses for them.
CountOfUsersInActiveDirectoryGroup	Integer	Description of the total number of users in the Active Directory group being imported or synchronized
CountOfUsersProcessed	Integer	Description of the total number of users processed during the import or synchronization process.
CountOfUsersSkipped	Integer	Description of the total number of users skipped during the import or synchronization process
CountOfUsersInformationUpdated	Integer	Description of the total number of users whose information was updated during the import or synchronization process.
CountOfUsersSiteRoleUpdated	Integer	Description of the total number of users whose site role was updated during the import or synchronization process.
CountOfUsersRemovedFromGroup	Integer	(Synchronization process only) Description of the number of users removed from the group during the synchronization process.
CountOfUsersUnlicensed	Integer	(Synchronization process only) Description of the number of users who were unlicensed during the synchronization process.
SiteDelete	Integer	Description of the site deletion progress. Can include a general error or `errorCode=9` when a site can't be deleted.

Version

Version 2.0 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	404018	Job not found	The job ID in the URI doesn't correspond to an existing job.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Query Jobs

Returns a list of active jobs on the specified site. To get details on a specific job, pass a job ID returned by this method to the Query Job method. To cancel an active job, pass a job ID returned by this method to the Cancel Job method.

Calls to this method can be filtered, as shown in the URI examples shown below. To learn more about filtering, see Filtering and Sorting in the REST API.

URI

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

GET /api/api-version/sites/site-id/jobs?filter=progress:lte:0

GET /api/api-version/sites/site-id/jobs?filter=jobType:eq:refresh_extracts

GET /api/api-version/sites/site-id/jobs?filter=createdAt:gt:2018-04-18T11:00:56z

GET /api/api-version/sites/site-id/jobs?filter=title:has:Superstore

GET /api/api-version/sites/site-id/jobs?filter=notes:has:nightly

GET /api/api-version/sites/site-id/jobs?filter=jobType:eq:run_flow

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 where the job is running.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="page-number" pageSize="page-size"/>
  <backgroundJobs>
    <backgroundJob id="job-id" status="status-value" createdAt="date-time" startedAt="date-time" endedAt="date-time" priority="priority-value" jobType="type-value"/>
	<!-- . . . more backgroundJobs . . . -->
  </backgroundJobs>
</tsResponse>

Version

Version 3.1 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.
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/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/jobs" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse>
  <pagination pageNumber="1" pageSize="100" totalAvailable="48999"/>
  <backgroundJobs>
	<backgroundJob id="919055e5-25db-4a2b-9611-1408dd06632d" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:15Z" endedAt="2018-04-17T23:00:15Z" priority="50" jobType="increment_extracts"/>
	<backgroundJob id="b5cadda9-2b32-447a-acb6-1c1b8c06caf9" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:15Z" endedAt="2018-04-17T23:00:15Z" priority="50" jobType="increment_extracts"/>
	<backgroundJob id="d281297b-9834-44a1-b71a-a2cab6060df6" status="Failed" createdAt="2018-04-17T23:00:15Z" startedAt="2018-04-17T23:00:24Z" endedAt="2018-04-17T23:00:32Z" priority="50" jobType="refresh_extracts"/>
  </backgroundJobs>
</tsResponse>

List Server Schedules

Returns a list of flows, extract and subscription server schedules on Tableau Server. For each schedule, the API returns the name, frequency, priority, and other information.

For more information about schedules, see Create or Modify a Schedule(Link opens in a new window).

Not available for Tableau Cloud.

URI

GET /api/api-version/schedules

GET /api/api-version/schedules?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.
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.

Request Body

None

Permissions

On Tableau Server, any user able to schedule extract refreshes and any site or server administrator can get schedules.

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="pageNumber" pageSize="page-size"
	totalAvailable="total-available" />
   <schedules>
  	<schedule id="schedule-id"
	   name="schedule-name"
	   state="Active-or-Suspended"
	   priority="schedule-priority"
	   createdAt="datetime-created"
	   updatedAt="datetime-last-updated"
	   type="extract-or-subscription-or-flow"
	   frequency="schedule-frequency"
	   nextRunAt ="datetime-next-run-time"
	   endScheduleAt ="datetime-expiration" />
	... additional schedules ...
   </schedules>
</tsResponse>

The datetime-created, datetime-last-updated, datetime-next-run-time, and datetime-expiration attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Example

curl "http://MY-SERVER/api/3.24/schedules" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings >
   <pagination pageNumber="1" pageSize="100" totalAvailable="3" />
   <schedules>
	<schedule id="ca3ce4f5-666c-4bb8-a763-5df24783881f"
	   name="Hourly"
	   state="Active"
	   priority="50"
	   createdAt="2011-03-30T22:32:35Z"
	   updatedAt="2016-01-13T01:00:02Z"
	   type="Extract"
	   frequency="Hourly"
	   nextRunAt="2016-01-13T23:00:00Z" />
	<schedule id="13abd238-0b22-4789-bcc4-614d31908310"
	   name="Saturday night"
	   state="Active"
	   priority="50"
	   createdAt="2010-10-28T21:11:33Z"
	   updatedAt="2016-01-10T07:00:00Z"
	   type="Extract"
	   frequency="Weekly"
	   nextRunAt="2016-01-17T07:00:00Z" />
	<schedule id="b6a6d11a-9e20-49f1-9b74-693f196b9aca"
	   name="End of the month"
	   state="Suspended"
	   priority="50"
	   createdAt="2010-10-28T21:11:33Z"
	   updatedAt="2016-01-01T07:00:03Z"
	   type="Extract"
	   frequency="Monthly"
	   nextRunAt="2016-02-01T07:00:00Z" />
   </schedules>
</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.
403	403014	Page size limit exceeded	The specified page size is larger than the maximum page size.
405	405000	Invalid request method	Request type was not GET.

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)

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 Server Schedule

Modifies settings for the specified server schedule, including the name, priority, and frequency details on Tableau Server.
For Tableau Cloud, see Update cloud extract refresh task and Update subscription .

URI

PUT /api/api-version/schedules/schedule-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.
schedule-id	The ID of the schedule to update. To determine what schedules are available, call List Server Schedules.

Request Body

<tsRequest>
  <schedule
    name="new-schedule-name"
    priority="new-schedule-priority"
    frequency="new-schedule-frequency"
    state="new-state"
    executionOrder="new-schedule-execution-order">
    <frequencyDetails start="start-time" end="end-time">
     <intervals>
        <interval interval-expression />
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Attribute Values

new-schedule-name	The new name to give to the schedule.
new-schedule-priority	An integer value between 1 and 100 that determines the default priority of the schedule if multiple tasks are pending in the queue. Lower numbers have higher priority.
new-schedule-execution-order	`Parallel` to allow jobs associated with this schedule to run at the same time, or `Serial` to require the jobs to run one after the other.
new-schedule-frequency	The granularity of the schedule. Valid values are: `Hourly`. `Hourly`. Jobs can be scheduled to run one or more times per day at intervals specified in minutes or hours. Valid intervals are 15 and 30 minutes and 2, 4, 6, 8, and 12 hours. `Daily`. Jobs can be scheduled to run once per day. `Weekly`. Jobs can be scheduled to run one or more times per week. `Monthly`. Jobs can be scheduled to run once per month on a specific day. The value you provide for schedule-frequency determines whether you must include an end-time value, and what is required in the contents of the <intervals> element.
new-state	`Active` to enable the schedule, or `Suspended` to disable it.
start-time	The time of day on which scheduled jobs should run (or if the frequency is hourly, on which they should start being run), in the format `HH:MM:SS` (for example, `18:30:00`). This value is required for all schedule frequencies. The entered time will be applied based on the time zone of your server.
end-time	If the schedule frequency is `Hourly`, the time of day on which scheduled jobs should stop being run, in the format `HH:MM:SS` (for example, `23:30:00`). Hourly jobs will occur at the specified intervals between the start time and the end time. For other schedule frequencies, this value is not required; if the attribute is included, it is ignored. The entered time will be applied based on the time zone of your server.
interval-expression	A value that specifies the interval between jobs associated with the schedule. The value you specify here depends on the value of schedule-frequency. `Hourly` The interval expression is only one of the following: `hours="interval"` where interval is `1`, `2`, `4`, `6`, `8`, or `12`, representing how many hours between jobs. `minutes="interval"` where interval is `15` or `30`, representing how many minutes between jobs. You can specify an interval in hours or minutes, but not both. `Daily` If the schedule frequency is `Daily`, no interval is specified. Any information specified in the <intervals> element is ignored. `Weekly` The interval expression is `weekDay="weekday"`, where weekday is `Sunday`, `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, or `Saturday`. You can specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week. Note: Updating a schedule without specifying days of the week will reset any existing weekly interval to include all 7 days. If you need the job you are updating to remain scheduled on selected days, make sure to include that information in your update request. `Monthly` The interval expression is `monthDay="day"`, where day is either the day of the month (`1`, `2`, etc.) or `LastDay`. Note: If you want to specify multiple days in the month, you can do this using the web interface. You cannot create or update such a monthly schedule using REST API.

Any combination of the attributes inside the <schedule> element is valid. Only the attributes and child elements that are included result in updates to the schedule. If no attributes or nested elements are included, no update is made.

Permissions

This method can only be called by server administrators.

Response Code

200

Response Body

<tsResponse>
  <schedule id="schedule-id"
        name="schedule-name"
        state="new-state"
        priority="schedule-priority"
        createdAt="datetime-created"
        updatedAt="datetime-updated"
        type="Extract-or-Subscription"
        frequency="schedule-frequency"
        nextRunAt="datetime-next-run"
        endScheduleAt ="datetime-expiration"
        executionOrder="Parallel-or-Serial">
        <frequencyDetails frequency-expression >
            <intervals>
               <interval interval-expression />
             </intervals>
        </frequencyDetails>
  </schedule>
</tsResponse>

Version

Version 2.3 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.
400	400008	Invalid Parameter	One of the parameters in the request body is invalid.
400	400071	Error updating schedule	The schedule couldn't be updated for an unspecified reason.
404	404023	Schedule not found	The specified schedule doesn't correspond to an existing schedule.
405	405000	Invalid request method	Request type was not PUT.
409	409021	Schedule name conflict	The schedule name in the request already belongs to an existing schedule.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/schedules/4d652179-36bf-47e4-a9dc-e069227c72d0" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-schedule.xml

Content of update-schedule.xml for an hourly schedule

For an hourly schedule, frequencyDetails is set to Hourly. Both start and end values are required. The intervals element is required, and must include 1 interval subelement that contains either an hours or a minutes attribute. Valid values for minutes are 15 or 30. Valid values for hours are 1, 2, 4, 6, 8, or 12.

<tsRequest>
  <schedule name="hourly-schedule-1"
        priority="50"
        type="Extract"
        frequency="Hourly"
        executionOrder="Parallel">
      <frequencyDetails start="18:30:00" end="23:00:00">
        <intervals>
          <interval hours="2" />
        </intervals>
      </frequencyDetails>
   </schedule>
</tsRequest>

Response body

<tsResponse <span class="api-placeholder">version-and-namespace-settings</span>>
  <schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0"
       name="hourly-schedule-1"
       state="Active"
       priority="50"
       createdAt="2016-05-07T01:51:19Z"
       updatedAt="2016-05-07T01:51:19Z"
       type="Extract"
       frequency="Hourly"
       nextRunAt="2016-05-07T03:30:00Z"
       endScheduleTime="2016-06-07T12:00:00Z"
       executionOrder="Parallel">
    <frequencyDetails start="18:30:00" end="23:00:00">
      <intervals>
          <interval hours="2" />
      </intervals>
   </frequencyDetails>
  </schedule>
</tsResponse>

Note: For additional examples of how to construct the payload for updating schedules, see Create Schedule.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help