Tableau REST API Help

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

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

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

URI

POST /api/api-version/schedules

Parameter Values

api-version

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

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.22. 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.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/dataAcceleration/7a2a7c6d-5e4f-3a2b-1c0d-9e8f7a6b3r4q" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

URI

DELETE /api/api-version/schedules/schedule-id

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
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.

URI

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

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id	The ID of the site that 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

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

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

URI

GET /api/api-version/schedules/schedule-id

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
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.22/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>
        

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

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

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

URI

PUT /api/api-version/schedules/schedule-id

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
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.22/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.