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) Tableau's View Acceleration feature and Data Acceleration-related APIs were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.

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

Use Postman

Our Postman collection of requests enables you to construct, send, and examine HTTP requests to the Tableau Server or Tableau Cloud API without writing initial code. Postman is a free online app used by many developers for prototyping API calls, investigating issues, and generating request code in a variety of languages.

Postman: Jobs, Tasks, and Schedules(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.29`. 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.

Access Scope

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

tableau:schedules:update

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

Response Code

200

Response Body

<tsResponse>
  <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.29/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 Virtual Connection to Server Schedule

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

This method identifies and refreshes only the tables in the virtual connection that are configured as extracts; live tables are ignored.

Version: Available in API 3.30 and later.

License: Data Management, Enterprise, Server+, Cloud+, or Tableau+ Bundle.

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

Access Scope: tableau:schedules:update

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

URI

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

URI Parameter Values

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The LUID for the site.
schedule-id	The LUID for the schedule that you are associating with the virtual connection.

Request Body

<tsRequest>
  <task>
    <extractRefresh transactionLevel="transaction-level" incremental="incremental-flag">
      <virtualConnection id="virtualconnection-id" />
      <startingItemIds>
        <startingItemId>starting-item-id</startingItemId>
        <!-- . . . more <startingItemId> elements . . . -->
      </startingItemIds>
    </extractRefresh>
  </task>
</tsRequest>

Attribute Values

transaction-level	Optional. DATABASE or TABLE. Default is DATABASE. If set to DATABASE: If any table extract refresh fails, none of the extracts are updated. If set to TABLE: If a table extract fails, only that table's extract isn't updated.
incremental-flag	Optional, boolean. Default is false. If set to false, do a full refresh. Fully refresh all extracts including those configured for incremental extract. If set to true, do an incremental refresh. Add new rows to incremental extracts. Full refresh other extracts.
virtualconnection-id	The LUID of the virtual connection to add to the schedule.
starting-item-id	The LUID of an extract table in the virtual connection. You may have more than one `<startingItemId>` element inside of a `<startingItemIds>` element.

cURL Request Example

curl --request PUT 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/virtualconnections' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest><task><extractRefresh><virtualConnection id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" /></extractRefresh></task></tsRequest>'

Response Code

200

Response Body

<tsResponse>
  <task>
    <extractRefresh id="9dd16fd7-8bbc-4c0d-9f75-9c7330a29396"
      priority="50"
      consecutiveFailedCount="0"
      type="ExtractServiceFullRefreshExtractTask"
      transactionLevel="DATABASE">
      <schedule id="c09d0586-80b3-4bb4-a1fa-508436243792"
        name="Weekday early mornings"
        state="Active"
        priority="50"
        createdAt="2026-07-15T12:28:01Z"
        updatedAt="2026-07-17T07:11:19Z"
        type="Extract"
        frequency="Weekly"
        nextRunAt="2026-07-20T04:00:00Z"/>
      <virtualConnection id="e3ebe049-8f94-4501-8fb0-faba6ccbbc85"/>
      <startingItemIds>
        <startingItemId>3577de68-2779-4962-b13d-3265ec98a4cb</startingItemId>
      </startingItemIds>
    </extractRefresh>
  </task>
</tsResponse>

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	400223	Virtual connection table not found.	A LUID in `startingItemIds` is not an extract-eligible table on the virtual connection.
400	400225	Duplicate virtual connection table.	`startingItemIds` contains the same table LUID more than once.
400	404049	No virtual connection specified.	The request body must include a virtual connection in the `extractRefresh` element.
400	409004	Invalid parameter.	`startingItemIds` contains a value that is not a valid LUID.
400	409090	No extract-eligible tables.	The virtual connection has no active revision, or none of its tables are configured for extract refresh.
403	403078	Unable to create the task.	One of the following applies: The user is not a system or site administrator and does not own the virtual connection. The virtual connection already has a refresh scheduled on this schedule. The virtual connection is in a personal space. The extract refresh operation is not allowed for the virtual connection.
404	404023	Schedule not found.	Check the schedule LUID.
404	404049	Virtual connection not found.	Check the virtual connection LUID.
405	405000	Method not allowed.	Request type must be PUT.

For more information, see Handling Errors.

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.

Note: This method is not available for Tableau Cloud.

Important changes for Tableau View Acceleration and Data Acceleration

Tableau's View Acceleration feature and Data Acceleration APIs are retired. These features were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.

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.29`. 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.

Access Scope

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

tableau:schedules:update

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.

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

Batch Update Schedule State

Updates the state of one or more schedules.

Use the updateAll URI parameter to update the state of all schedules in a single call.

Version: Available in API 3.27 (Tableau Server 2025.3 and later. Not available for Tableau Cloud.)

License: No additional license required.

Permissions: Only server administrators.

Access Scope: tableau:schedules:update

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

URI

PUT /api/api-version/schedules?state=state-enum

PUT /api/api-version/schedules?state=state-enum&updateAll=update-all-flag

URI Parameter Values

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
state-enum	Required, enum. Either `active` or `suspended`. The state for the schedule(s).
update-all-flag	Optional, boolean. If `true`, then the list of schedule IDs in the request body is ignored, and the operation affects all schedules on the Tableau Server.

Note: A common use case for this method is suspending all schedules before a maintenance window using the updateAll URI parameter. If, after the maintenance window, you use the same tactic and activate all schedules using the updateAll URI parameter, you risk activating schedules that may have been intentionally suspended in the past, before you used updateAll to suspended all schedules.

Instead, when suspending all schedules using the updateAll URI parameter, note which schedule LUIDs appear in the response body. This tells you which schedules were changed from active to suspended. Then, after the maintenance window, re-activatate only those schedules, not all schedules.

Request Body

<tsRequest>
  <scheduleLuids>
    <scheduleLuid>schedule-id</scheduleLuid>
    <!-- ... additional scheduleLuid elements ... -->
  </scheduleLuids>
</tsRequest>

{
  "scheduleLuids": {
    "scheduleLuid": [
      "schedule-id"
    ]
  }
}

Request Attributes

schedule-id

The LUID of the schedule. You can include multiple schedule-ids using additional <scheduleLuid> elements (in XML) or by comma-separating multiple schedule-ids (in JSON).

Note: If the updateAll URI parameter is included, schedule-ids in the request body are ignored.

cURL Request Example

curl "https://MY-SERVER/api/3.27/schedules?state=active&updateAll=true" -X PUT -H "X-Tableau-Auth: a1B2c3D4e5F6g7H8i9J0kL|a1B2c3D4e5F6g7H8i9J0kL1m2N3o4P5q|12345678-90ab-4cde-8f01-234567890abc" -d @data.xml

Content of data.xml:

<tsRequest>
    <scheduleLuids>
        <scheduleLuid>12ab34cd-56ef-78ab-90cd-12ef34ab56cd</scheduleLuid>
        <scheduleLuid>08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6</scheduleLuid>
    </scheduleLuids>
</tsRequest>

Response Code

200

Response Body

The response body is a list of schedules that were updated with the call.

<tsResponse>
  <scheduleLuids>
    <scheduleLuid>schedule-id</scheduleLuid>
    <!-- ... additional scheduleLuid elements ... -->
  </scheduleLuids>
</tsResponse>

{
  "scheduleLuids": {
    "scheduleLuid": [
      "schedule-id"
    ]
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	400000	Generic error	An unknown error occurred. The content of the request body may be missing or incomplete, or may contain malformed XML.
403	403188	Permissions error	User calling the method isn't a server administrator.
403	403189	Invalid LUID	One or more of the schedule LUIDs isn't a valid LUID.
404	404023	LUID not found	One or more of the schedule LUIDs isn't found.
405	405000	Availability error	This method only exists on Tableau Server. Tableau Cloud isn't supported.
409	409004	Parameter error	The state parameter is absent or not recognized; or the updateAll parameter was absent or false and no schedule LUIDs were provided.

For more information, see Handling Errors.

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 Tableau's View Acceleration feature and Data Acceleration-related APIs were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.
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.29`. 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.

Access Scope

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

tableau:jobs:update

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.29/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/jobs/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Create Cloud Extract Refresh Task

Creates a custom schedule for an extract refresh on Tableau Cloud. The target of the schedule can be a data source, a workbook, or a virtual connection.
For Tableau Server, see Add data source to server schedule, Add workbook to server schedule, and Add virtual connection to server schedule.

Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Virtual connection support added in API 3.30. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: No additional license required for a data source or workbook target. A virtual connection target requires Data Management, Enterprise, Server+, Cloud+, or Tableau+ Bundle.

Permissions: Administrators and any user with the creator role can create a custom schedule for an extract refresh. Permissions Overview(Link opens in a new window)

JWT Access Scope: tableau:tasks:create

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

URI

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

URI Parameter Values

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

Request Body

<tsRequest>
  <extractRefresh type="FullRefresh">
    <workbook id="54321fd-6365-44d5-925b-644e5281b605" />
  </extractRefresh>
  <schedule frequency="Daily">
    <frequencyDetails start="18:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Sunday"/>
        <interval weekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

{
  "extractRefresh": {
    "type": "FullRefresh",
    "workbook": {
      "id": "54321fd-6365-44d5-925b-644e5281b605"
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }

Request Attributes

All request attributes are required to create a custom schedule for an extract refresh, except where noted below.

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

schedule frequency

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

Hourly
Daily
Weekly
Monthly

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

frequencyDetails end

(Required to create subscription) time: If the schedule frequency is Hourly, or Daily with an interval of hours less than 24, then end is the time of day on which scheduled jobs should stop being run. The valid format is HH:MM:SS. Time should be specified in 5 minute increments and the difference between start and end times should be increments of 60 minutes. For example, a valid frequencyDetail would be:

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

interval {interval type}

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

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

Virtual Connection Example

When the target is a virtual connection, use virtualConnection id instead of workbook id or datasource id. The following example includes only the <extractRefresh> and child elements for brevity; see the primary example above for the a full request without the elements that apply only to virtual connections.

Incremental refresh of specific tables, with a table-level transaction:

<extractRefresh type="IncrementalRefresh" transactionLevel="TABLE">
  <virtualConnection id="33a16da9-e96b-4190-83ed-c85192683052" />
  <tableLuids>
    <tableLuid>b4e39d59-19c3-4380-8ea4-9bfa4ed8fb84</tableLuid>
    <!-- . . . more <tableLuid> elements . . . -->
  </tableLuids>
</extractRefresh>

cURL Request Example

curl --location --request POST "https://10ax.online.tableau.com/api/3.29/sites/a946d998-2ead-4894-bb50-1054a91dcab3/tasks/extractRefreshes" --header "Content-Type: application/xml" --data "<tsRequest> <extractRefresh type='FullRefresh'> <workbook id='0057ccac-872a-11e5-bb51-f763326b1350' /> </extractRefresh> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> </intervals> <intervals> <interval weekDay='Sunday'/> </intervals> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"

200

Response Body

When the target is a virtual connection, the response's extractRefresh element includes a transactionLevel attribute and a virtualConnection element (with a sibling startingItemIds, if starting items were specified) in place of datasource or workbook.

<tsResponse>
  <extractRefresh
    id="13237fd-6365-44d5-925b-644e5281b605"
    consecutiveFailedCount="0"
    type="IncrementalRefresh" >
      <datasource id="0057ccac-872a-11e5-bb51-f763326b1350" />
  </extractRefresh>
  <schedule id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
    createdAt="2023-04-06T23:43:12-0700"
    updatedAt="2023-04-06T23:43:12-0700"
    frequency="Daily"
    nextRunAt="2023-04-06T23:43:12-0700">
        <frequencyDetails start="18:30:00" end="23:30:00">
        <intervals>
          <interval hours="4"/>
          <interval weekDay="Sunday"/>
          <interval weekDay="Wednesday"/>
        </intervals>
      </frequencyDetails>
  </schedule>
</tsResponse>

{
  "extractRefresh": {
    "id": "13237fd-6365-44d5-925b-644e5281b605",
    "consecutiveFailedCount": "0",
    "type": "IncrementalRefresh",
    "datasource": {
      "id": "0057ccac-872a-11e5-bb51-f763326b1350"
    }
  },
  "schedule": {
    "id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
    "createdAt": "2023-04-06T23:43:12-0700",
    "updatedAt": "2023-04-06T23:43:12-0700",
    "frequency": "Daily",
    "nextRunAt": "2023-04-06T23:43:12-0700",
    "frequencyDetails": {
      "start": "18:30:00",
      "end": "23:30:00",
      "intervals": {
        "interval": [
          { "hours": "4" },
          { "weekDay": "Sunday" },
          { "weekDay": "Wednesday" }
        ]
      }
    }
  }
}

Errors

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

For more information, see Handling Errors.

Create 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.29. 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. Tableau's View Acceleration feature and Data Acceleration-related APIs were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.
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.

Access Scope

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

tableau:schedules:create

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

This method is not available for Tableau Cloud.

Important changes for Tableau View Acceleration and Data Acceleration

Tableau's View Acceleration feature and Data Acceleration APIs are retired. These features were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.

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.29`. 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.

Access Scope

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

tableau:data_acceleration_tasks:delete

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.

Important changes for Tableau View Acceleration and Data Acceleration

Tableau's View Acceleration feature and Data Acceleration APIs are retired. These features were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.

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.29/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.29`. 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.

Access Scope

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

tableau:schedules:delete

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.

This method is not available for Tableau Cloud.

Important changes for Tableau View Acceleration and Data Acceleration

Tableau's View Acceleration feature and Data Acceleration APIs are retired. These features were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.

URI

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

Parameter Values

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

Request Body

None

Permissions

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

Access Scope

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

tableau:data_acceleration_tasks:read

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

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

Important changes for Tableau View Acceleration and Data Acceleration

Tableau's View Acceleration feature and Data Acceleration APIs are retired. These features were retired in Tableau Cloud in June 2026 and in Tableau Server version 2026.2.

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.29/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 a site's scheduled extract refresh task for a data source, workbook, or virtual connection.

URI

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

Parameter Values

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

JWT Access Scope

Available in API 3.20 (Tableau Cloud June 2023).

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

Request Body

None

Permissions

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

Response Code

200

Response Body

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

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

Tableau Server Response

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

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

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

Tableau Cloud Response

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

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

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

Version

Version 2.6 and later. Virtual connection support added in 3.30. For more information, see REST API and Resource Versions.

Errors

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

For more information, see Handling Errors.

List Extract Refresh Tasks in Site

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

URI

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

Parameter Values

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

JWT Access Scope

Available in API 3.20 (Tableau Cloud June 2023).

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

cURL Example

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

Request Body

None

Permissions

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

Response Code

200

Response Body

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

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

Tableau Server Response

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

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

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

Tableau Cloud Response

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

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

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

Version

Version 2.6 and later. Virtual connection support added in 3.30. For more information, see REST API and Resource Versions.

Errors

405

405000

Invalid requests method

Request type was not GET

For more information, see Handling Errors.

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.29`. 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.

Access Scope

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

tableau:schedules:read

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

Request Body

None

Permissions

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

Response Code

200

Response Body

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

Version

Version 2.2 and later. Virtual connection support added in 3.30. For more information, see REST API and Resource Versions.

Errors

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

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/schedules/59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba/extracts" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

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

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

Version: Available in API 2.0 and later.

License: No additional license required.

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

Access Scope: tableau:jobs:read

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

URI

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

Parameter Values

api-version	The version of the API to use, such as `3.29`. For more information, see REST API and Resource Versions.
site-id	The ID of the site where the job is running.
job-id	The ID of the job to get status information for.

Request Body

None

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

The finishCode indicates the status of the job.

For most jobs, the finishCode indicates the status of the job: 0 for success, 1 for error, or 2 for canceled.
For bridge extract refresh jobs, a finishCode of 0 indicates that the bridge client is assigned to execute the job, while a 3 indicates that the job completed.
For asynchronous workbook publishing jobs, 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 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.

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.

Version: Available in API 3.1 and later.

License: No additional license required.

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

Access Scope: tableau:jobs:read

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

URI

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.29`. For more information, see REST API and Resource Versions.
site-id	The ID of the site where the job is running.

Request Body

None

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>

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

Access Scope

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

tableau:schedules:read

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.29/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, the published workbook that connects to the data extract, or the virtual connection extract. You must first schedule the task for the extract refresh. You can do this using the Create Schedule method to create the task. To get information about the extract refresh task, use the Get Extract Refresh Tasks method, which returns the extractRefresh ID that you use as the task-id.

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

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

URI

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

Parameter Values

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

JWT Access Scope

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

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

Request Body

The request body is an empty tsRequest element.

<tsRequest/>

Permissions

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

Response Code

200

Response Body

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

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

Version

Version 2.6 and later. Virtual connection support added in 3.30. For more information, see REST API and Resource Versions.

Errors

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

For more information, see Handling Errors.

Example

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

Update 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.29`. 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.

Access Scope

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

tableau:schedules:update

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

Update Virtual Connection Now

Runs an extract refresh on the specified virtual connection.

This method identifies and refreshes only the tables in the virtual connection that are configured as extracts; live tables are ignored. No additional input is required from the caller.

Version: Available in API 3.30 and later.

License: Data Management, Enterprise, Server+, Cloud+, or Tableau+ Bundle.

Permissions: Users who are not server administrators or site administrators can only refresh extracts for virtual connections if they own the virtual connection, or if they are the project leader for the project.

Access Scope: tableau:tasks:run

URI

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

URI Parameter Values

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

Request Body

The request body is an empty tsRequest element.

<tsRequest/>

{}

cURL Request Example

(Use the icon in the top right corner to copy the text.)

curl --request POST 'http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/refresh' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest/>'

Response Code

202

Response Body

<tsResponse>
  <job id="job-id" mode="Asynchronous" type="RefreshExtract" createdAt="date-time">
    <extractRefreshJob>
      <virtualConnection id="virtualconnection-id" name="virtualconnection-name" />
    </extractRefreshJob>
  </job>
</tsResponse>

{
  "job": {
    "id": "job-id",
    "mode": "Asynchronous",
    "type": "RefreshExtract",
    "createdAt": "date-time",
    "extractRefreshJob": {
      "virtualConnection": {
        "id": "virtualconnection-id",
        "name": "virtualconnection-name"
      }
    }
  }
}

Errors

HTTP status	`error` Code	Condition	Details
400	403180	Full refresh not allowed.	A full refresh extract operation is not allowed for the virtual connection.
400	403181	Incremental refresh not allowed.	The request specified an incremental refresh, but an incremental refresh extract operation is not allowed for the virtual connection.
400	409090	No extract-eligible tables.	The virtual connection has no active revision or no extract-eligible tables. Live tables are not refreshed.
403	403199	User not authorized to refresh the virtual connection.	The user must have either the Manage Extract or the Allow Extract Refresh permission on the virtual connection.
403	409082	Run Now is disabled for the site.	Enable Run Now for the site, then try the request again.
404	404049	Virtual connection not found.	Check the virtual connection LUID.
405	405000	Method not allowed.	Direct virtual connection extract refresh is not enabled for this site.
409	409093	Operation already in queue.	An extract refresh job for the virtual connection is already in the queue.

For more information, see Handling Errors.

Thanks for your feedback!

Your feedback has been successfully submitted. Thank you!

Tableau REST API Help

Jobs, Tasks, and Schedules Methods

Use Postman

Add Data Source to Server Schedule

URI

Parameter Values

Request Body

Attribute Values

Permissions

Access Scope

Response Code

Response Body

Version

Errors

Example

Add Virtual Connection to Server Schedule

URI

URI Parameter Values

Request Body

Attribute Values

cURL Request Example

Response Code

Response Body

Errors

Add Workbook to Server Schedule

URI

Parameter Values

Request Body

Attribute Values

Permissions

Access Scope

Response Code

Response Body

Version

Errors

Example

Batch Update Schedule State

URI

URI Parameter Values

Request Body

Request Attributes

cURL Request Example

Response Code

Response Body

Errors

Cancel Job

URI

Parameter Values

Request Body

Permissions

Access Scope

Response Code

Response Body

Version

Errors

Example

Create Cloud Extract Refresh Task

URI

URI Parameter Values

Request Body

Request Attributes

Virtual Connection Example

cURL Request Example

Response Body

Errors

Create Server Schedule

URI

Parameter Values

Request Body

Attribute Values

Permissions

Access Scope

Response Code

Response Body

Version

Errors

Example

Delete Data Acceleration Task

URI

Parameter Values