Flow Methods


Using the flow methods of the Tableau Server REST API you can do the operations listed in the following categories:

Flows (sets of data preparation steps for a site)

  • Get a list of flows for a site or the users and details of a specific flow
  • Get a list of flow runs for a site
  • Run a specific flow with all or a specified set of output steps
  • Run a specific flow with parameter values
  • Cancel a specific flow run
  • Publish, update, delete and download a flow

Flow Tasks (scheduled or manually initiated tasks that perform flows for a site)

  • Get a list of flow tasks for a site and details of a specific flow task
  • Run a flow task
  • Add a flow task to a schedule
  • Add a flow task to a schedule with parameter values
  • Get a list of linked tasks for a site and details of a specific linked task
  • Run a linked task

Flow Connections (connections to data sources of a flow)

  • Get and update the connection information for a flow task

Flow Permissions (user permissions to initiate a flow)

  • List, grant, and remove granular permissions of a user to a flow

This functionality relates to the UI elements and concepts described at: Tableau Prep Conductor(Link opens in a new window).

Add Flow Permissions

Adds permissions to the specified flow for a Tableau Server user or group. You can specify multiple sets of permissions using one call.

URI

PUT /api/api-version/sites/site-id/flows/flow-id/permissions

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 flow.
datasource-id The ID of the flow.

Request Body

<tsRequest>
  <permissions>
    <flow id="flow-id" />
    <granteeCapabilities>
      <user id="user-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-id" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        ... additional capabilities ...
      </capabilities>
    </granteeCapabilities>
    ... additional grantee capability sets ...
  </permissions>
</tsRequest>

Attribute Values

flow-id The flow-id value for the flow you want to add permissions to.
user-id The ID (not name) of the user to add permissions for.
group-id The ID (not name) of the group to add permissions for.
capability-name The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.

For more information, see Permissions.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to set permissions on the flow (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
    <permissions>
        <flow id="8359f0c5-4b98-4ca4-a7e5-38e4261e88a2" name="Flow1">
            <owner id="8f735728-7484-40d1-89d1-41f09824536b"/>
        </flow>
        <granteeCapabilities>
            <group id="9de5cc1a-5bb8-4c8e-b2cd-b54e736a7b9f"/>
            <capabilities>
                <capability name="Read" mode="Allow"/>
                <capability name="Write" mode="Allow"/>
                <capability name="Delete" mode="Deny"/>
            </capabilities>
        </granteeCapabilities>
        <granteeCapabilities>
            <user id="1f2345678-1234-12d1-12d1-11f234567b"/>
            <capabilities>
                <capability name="Delete" mode="Allow"/>
            </capabilities>
        </granteeCapabilities>
    </permissions>
</tsResponse>

Version

Version 3.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 400009 Invalid capability The capability in the URI is invalid for a flow. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the flow.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found A user ID in the request body doesn't correspond to an existing user.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
404 404012 Group not found A group ID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Add Flow Task to Server Schedule

The Add Flow Task to Schedule method is renamed and retired for Tableau Cloud in API 3.22 (Tableau Cloud March 2024). It will remain available for Tableau Server only. For Tableau Cloud in March 2024, this method will be replaced with Create Flow Task with Custom Schedule method.

Adds a task to run a flow to an existing schedule.

Note: This method is unavailable if you do not have a Data Management license or Tableau Prep Conductor is disabled for your site.

URI

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

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 flow.
schedule-id The ID of the schedule that you are associating with the flow. The schedule that you are adding to must have Flow as the schedule type.

Request Body

<tsRequest>
  <task>
    <flowRun>
      <flow id="flow-id"/>
	  <flowRunSpec>
	    <flowParameterSpecs>
	      <flowParameterSpec
	        parameterId="parameter-id"
	        overrideValue= "overrideValue"/>
	    <flowParameterSpecs>
	  <flowRunSpec>
     </flowRun>
   </task>
</tsRequest>

Attribute Values

flow-id

The ID of the flow to add to the schedule. This will include all the output steps in the flow and any output steps created in the future.
parameter-id

The ID of the flow parameter. Use the Flow Methods method to get the flow parameter ID. A parameter is a global placeholder value such as a number, text value, or boolean value that can replace a constant value in a flow.

Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled.

For more information, see Run flows with parameters.
overrideValue

The run-time value for the flow parameter. You must specify this if the parameter is required. Use the Flow Methods method to see if the parameter is required and to get a list of allowed values if the parameter is expecting a value from an enumerated list.

Note: Parameters are options and only relevant for flows that contains parameters and the parameter setting is enabled.

For more information, see Run flows with parameters.

Permissions

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

Response Code

200

Version

Version 3.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 400148 Invalid parameter override value The run-time value provided for the flow parameter is invalid.
400 400149 Missing run-time parameter value. The run-time value for a required flow parameters was not provided.
401 401002 Unauthorized Access The authentication token provided in the request header was invalid or has expired.
403 403098 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 404043 Flow parameter not found The flow parameter information was not provided.
404 404002 User not found A user ID in the request body doesn't correspond to an existing user.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 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/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/flows" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"

Content of add-to-schedule.xml:

The <flowRunSpec> in the request body is optional and only required in the following scenarios:

  • The flow has parameters and the parameter is marked as required to run the flow.
  • The flow has parameters but not marked as required. However, you want to specify a different value than the configured default.
<tsRequest>
   <task>
     <flowRun>
       <flow id="5ab9cd53-e17f-45gh-804i-4914jk39r29z"/>
	  <flowRunSpec>
	    <flowParameterSpecs>
	      <flowParameterSpec>
	        parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89"
	        overrideValue= "2"/>
	    <flowParameterSpecs>
	  <flowRunSpec>
     </flowRun>
   </task>
</tsRequest

Example response:

<tsResponse version-and-namespace-settings>
    <task>
      <flowRun id="8a78c68e-37ad-4b21-80fc-e67e2ab55279" priority="50" consecutiveFailedCount="0" type="RunFlowTask">
        <schedule id="99e8841e-8527-4d09-89b8-71d9872634df" name="demo" state="Active" priority="50" createdAt="2021-12-09T19:21:09Z" updatedAt="2022-01-19T23:06:56Z" type="Flow" frequency="Hourly" nextRunAt="2022-01-20T00:00:00Z"/>
        <flow id="09942c88-99d5-4669-aa62-07560fc4b201" name="CoffeeChain"/>
          <flowParametersRuns>
            <parameterRuns parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89" name="param 2 required" description=testparameter2" overrideValue = "2"/>
	   <flowParametersRuns>
      </flowRun>
    </task>
</tsResponse>

Cancel Flow Run

Cancels a flow run that is in progress.

URI

PUT /api/api-version/sites/site-id/flows/runs/flow-run-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 flow.
flow-run-id The ID of the flow run.

Request Body

None

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403135 Flow run already complete The flow run is already complete so it could not be canceled.
403 403137 User does not have permissions to cancel flow run In addition to server administrators and site administrators, users can cancel a flow run if they initiated the flow run or created the flow run scheduled task and have "Run Flow Now" permissions for the flow.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404036 Flow run not found The flow run ID in the URI doesn't correspond to an existing flow run.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Create Cloud Flow Task

Creates a flow task on Tableau Cloud, and set its schedule.

Note: This method is unavailable if you do not have a Data Management license or Tableau Prep Conductor is disabled for your site.

Version: Available in API 3.22 (Tableau Cloud April 2024) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)

License: Requires Tableau Data Management(Link opens in a new window).

Permissions: A user can create a cloud flow task if you are a site or server administrator, or they own the flow, or are the project leader for the project that contains the workbook.   Permissions Overview(Link opens in a new window)

JWT Access Scope: Not available.     Access Scopes Overview: Cloud(Link opens in a new window) 

URI

POST /api/api-version/sites/site-luid/tasks/flows

URI Parameter Values

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

Request Body

Copy 
<tsRequest>
  <task>
    <flowRun>
      <flow id="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"/>
    </flowRun>
  </task>
  <schedule frequency="Daily">
    <frequencyDetails start="12:30:00" end="23:30:00">
      <intervals>
        <interval hours="4"/>
        <interval weekDay="Monday"/>
        <interval weekDay="Wednesday"/>
      </intervals>
    </frequencyDetails>
  </schedule>
</tsRequest>

Copy 
{
  "task": {
    "flowRun": {
      "flow": {
        "id": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"
      }
    }
  },
  "schedule": {
    "frequency": "Daily",
    "frequencyDetails": {
      "start": "12:30:00",
      "end": "23:30:00",
      "intervals": [
        {
          "hours": "4"
        },
        {
          "weekDay": "Monday"
        },
        {
          "weekDay": "Wednesday"
        }
      ]
    }
  }
}

Request Attributes

flow.id (Required)The LUID of the flow the task is being scheduled for.
schedule frequency (Required to create subscription) enumeration: The scheduled frequency for triggering the task. Valid values include:
  • Hourly
  • Daily
  • Weekly
  • Monthly
frequencyDetails start (Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly, then start is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the time range during which jobs should be started. The valid format is HH:MM:SS.
frequencyDetails end

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

<frequencyDetail start="20:45:00" end="21:45:00">
  . . . 
</frequencyDetail>
interval {interval type} (Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in the start and end values of the frequencyDetails of the schedule. The type and valid values for an interval expression depend on the declared frequency of the schedule as follows:

FrequencyValid interval values
Hourly The value of an interval for an Hourly schedule can be only one of either:
  • hours=“1" The number of hours between jobs. 1 is the only valid value.
  • minutes=“60" The number of minutes between jobs. 60 is the only valid value.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday.

    For example, to schedule to run a job every hour on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="1"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
    <intervals>

Daily The value of Daily can have multiple weekday elements, but only one hours declaration. An hours interval is required.
  • hours=“interval" The interval between execution of jobs on the weekday(s) specified. Valid values are 2, 4, 6, 8, 12, or 24. Note that if the interval value of a daily schedule is less than 24, a frequencyDetail end time must be supplied.
  • weekDay=“weekday" The weekday(s) the job will be run on. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.

    For example, to schedule to run a job every 4 hours on Sunday and Wednesday, during the time range specified in frequencyDetails use an interval like:
    Copy
    <intervals>
      <interval hours="4"/>
      <interval weekDay="Sunday"/>
      <interval weekDay="Wednesday"/>
    <intervals>
WeeklyweekDay=“weekday" The day of the week the schedule should run on. Multiple days can be specified for a Weekly schedule. Valid values are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.
Monthly

The day(s) of the month a job should be scheduled to run on. There are two ways to define a monthly interval:

Specify the day(s) using the number of the day in the month;

  • monthDay=“day" The number of the day of the month. Valid values are the whole numbers 1 to 31 or LastDay. If you specify monthDay by day number then you can use multiple interval instances to choose for the job to run on multiple days in the month. If you use LastDay then only one instance of interval can be used in the schedule to specify the last day of the month.

Specify the day by describing which occurrence of a weekday within the month.

  • monthDay=“occurrence_of_weekday" Weekday=“weekday" The occurrence of the specified weekday within the month when a job should be run. Valid values for occurrencee_of_weekday are First, Second, Third, Fourth, Fifth, or LastDay. Valid values for weekday are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday. If the value is lastDay then the job will run on the last occurrence of the specified weekday in the month.

    For example, to make a schedule that that would run a job on the third Thursday of each month, you would use:
    Copy
    <interval monthDay="Third" weekDay="Thursday"/>

cURL Request Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Code

200

Response Body

Copy 
<tsResponse>
  <task>
    <flowRun id="4d49655a-0f3a-45cc-ba61-b108a763e83a" 
      priority="50" 
      consecutiveFailedCount="0" 
      type="RunFlowTask">
        <schedule id="1060dcb7-fef7-4fb1-8d3b-d0f042932d1a" 
          name="SSS_e95a9d25-c616-4542-87b6-3725975bdfbd" 
          state="Active" 
          priority="50" 
          createdAt="2024-04-09T18:54:12Z" 
          updatedAt="2024-04-09T18:54:12Z" 
          type="Flow" 
          frequency="Daily" 
          nextRunAt="2024-04-10T19:30:00Z"/>
        <flow id="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541" 
          name="olympic 1">
            <parameters>
              <parameter id="4f22c514-5b56-4400-a48a-f69d9be217a9" 
                type="integer" 
                name="output_count" 
                description="This is a parameter of a flow." 
                value="2" 
                isRequired="true">
                  <domain xsi:type="flowParameterAnyDomainType" 
                    domainType="all"/>
              </parameter>
            </parameters>
        </flow>
        <flowRunSpec flowId="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541">
        <flowOutputSteps>
          <flowOutputStep id="485c8b5f-5647-466c-b549-e38410b7c7c8" 
            name="Output"/>
        </flowOutputSteps>
        <flowParameterSpecs/>
      </flowRunSpec>
    </flowRun>
  </task>
</tsResponse>
Copy 
{
  "task": {
    "flowRun": {
      "id": "4d49655a-0f3a-45cc-ba61-b108a763e83a",
      "priority": "50",
      "consecutiveFailedCount": "0",
      "type": "RunFlowTask",
      "schedule": {
        "id": "1060dcb7-fef7-4fb1-8d3b-d0f042932d1a",
        "name": "SSS_e95a9d25-c616-4542-87b6-3725975bdfbd",
        "state": "Active",
        "priority": "50",
        "createdAt": "2024-04-09T18:54:12Z",
        "updatedAt": "2024-04-09T18:54:12Z",
        "type": "Flow",
        "frequency": "Daily",
        "nextRunAt": "2024-04-10T19:30:00Z"
      },
      "flow": {
        "id": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541",
        "name": "olympic 1",
        "parameters": {
          "parameter": {
            "id": "4f22c514-5b56-4400-a48a-f69d9be217a9",
            "type": "integer",
            "name": "output_count",
            "description": "This is a parameter of a flow.",
            "value": "2",
            "isRequired": "true",
            "domain": {
              "xsi_type": "flowParameterAnyDomainType",
              "domainType": "all"
            }
          }
        }
      },
      "flowRunSpec": {
        "flowId": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541",
        "flowOutputSteps": {
          "flowOutputStep": {
            "id": "485c8b5f-5647-466c-b549-e38410b7c7c8",
            "name": "Output"
          }
        },
        "flowParameterSpecs": []
      }
    }
  }
}

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.

For more information, see Handling Errors.

Delete Flow

Deletes a flow. When a flow is deleted, its associated connections, the output and input steps, any associated scheduled tasks, and run history are also deleted.

URI

DELETE /api/api-version/sites/site-id/flows/flow-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 flow.
flow-id The ID of the flow to delete.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a flow for which they have Read (view) and Delete permissions (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user called this method but doesn't have Read (view) and Delete permission for the flow.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Flow Permission

Deletes the specified permission from the specified flow for a group or user.

URI

DELETE /api/api-version/sites/site-id/flows/flow-id/permissions/groups/group-id/capability-name/capability-mode

DELETE /api/api-version/sites/site-id/flows/flow-id/permissions/users/user-id/capability-name/capability-mode

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 flow.
flow-id The ID of the flow to remove the permission for.
group-id The ID of the group to remove the permission for.
user-id The ID of the user to remove the permission for.
capability-name The capability to remove the permission for. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.

For more information, see Permissions.
capability-mode Allow to remove the allow permission, or Deny to remove the deny permission. This value is case sensitive.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete permissions from a flow only if they have ChangePermissions permission for flow (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400009 Invalid capability The capability in the URI is invalid for a flow. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to set permissions on the flow.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
404 404012 Group not found The group ID in the URI doesn't correspond to an existing group.
404 404013 Capability not found The capability in the URI doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allowor Denyat the end of the URI.
404 404013 Capability not assigned The capability in the URI is not assigned to the specified user or group with the specified mode (Allowor Deny).
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Download Flow

Downloads a flow in .tfl or .tflx format.

URI

GET /api/api-version/sites/site-id/flows/flow-id/content

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 flow.
flow-id The ID of the flow to download.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can download a flow only if they have download permission for the flow (either explicitly or implicitly).

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403097 Read forbidden A non-administrator user attempted to download a flow, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404027 Flow 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/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/content" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" >

Response: The response is a file that contains the flow.

Get Flow Run

Gets a flow run.

URI

GET /api/api-version/sites/site-id/flows/runs/flow-run-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 flow.
flow-run-id The ID of the flow run.

Request Body

None

Response Code

200

Response Body

<tsResponse>
   <flowRun id="flowRun_id"
    flow id="flow_id"
    status="status"
    startedAt="DATE_TIME"
    completedAt="DATE_TIME"
    progress="100"
    backgroundJobId="background_job_id"/>
     <flowParameterRuns>
       <parameterRuns parameter Id="parameter_id"
        name="parameter_name"
        description="parameter_description"
        overrideValue="override_value"/>
     </flowParameterRuns>
   </flowRun>
</tsResponse>

The status attribute can be: Pending, InProgress, Success, Cancelled, or Failed.

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Get forbidden User does not have permissions to get the flow run. A user can view a flow run if they have permission to view the flow.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404036 Flow run not found The flow run ID in the URI doesn't correspond to an existing flow run.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Flow Runs

Get flow runs.

URI

GET /api/api-version/sites/site-id/flows/runs

GET /api/api-version/sites/site-id/flows/runs?filter=filter-expression

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.
filter-expression (Optional) An expression that lets you specify a subset to return. You can filter on predefined fields such as the userId of the user who started the flow run, flowId, progress, startedAt, and completedAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.

Request Body

None

Response Code

200

Response Body

<tsResponse>
   <flowRuns>
     <flowRuns id="flowRuns_id"
      flow id="flow_id"
      status="status"
      startedAt="DATE_TIME"
      completedAt="DATE_TIME"
      progress="100"
      backgroundJobId="background_job_id"/>
       <flowParameterRuns>
	  <parameterRuns parameterId="parameter_id"
          name="parameter_name"
          description="parameter_description"
	   overrideValue="override_value"/>
	</flowParameterRuns>
    </flowRuns>
     ... additional flow runs....
</tsResponse>

The status attribute can be: Pending, InProgress, Success, Cancelled, or Failed.

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Get forbidden User does not have permissions to get the flow run.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the filter doesn't correspond to an existing user.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Flow Run Task

Returns information about the specified flow run task. This method shows you information about the scheduled task for the flow.

URI

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

Parameter Values

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

Request Body

None

Permissions

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

Response Code

200

Response Body

<tsResponse>
   <task>
     <flowRun id="flowRun_id"
      priority="nn"
      consecutiveFailedCount="n"
      type="RunFlowTask">
       <schedule id="schedule_id"
        name="schedule_name"
        state="state"
        priority="nn"
        createdAt="DATE_TIME"
        updatedAt="DATE_TIME"
        type="flowRun"
        frequency="frequency"
        nextRunAt="DATE_TIME"/>
         <flow id="flow_id"
          name="flow_name"/>
	    <parameters>
		<parameter id="parameter_id"
                type="data_type"
                name="parameter_name"
                description="parameter_description"
                value="parameter_value"
                isRequired="true-or-false">
		  <domain xsi:type="flowParameterListDomainType-or-flowParameterAnyDomainType"
                  domainType="domain_type">
		  </domain>
	        </parameter>
	    </parameters>
     </flowRun>
   </task>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
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 request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/runFlow/1bff10bb-57ae-43df-8774-a86d14aef432" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response: 

<tsResponse version-and-namespace-settings>
    <task>
        <flowRun id="1bff10bb-57ae-43df-8774-a86d14aef432" priority="50" consecutiveFailedCount="2" type="RunFlowTask">
            <schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T18:12:09Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T18:14:00Z"/>
            <flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/>
	     <parameters>
		<parameter id="ebfad780-c19f-42a2-822a-406468269a02" type="string" name="Region" description="" value="North" isRequired="false">
		<domain xsi:type="flowParameterListDomainType" domainType="any">
		</domain>
		</parameter>
	     </parameters>
        </flowRun>
    </task>
</tsResponse>

Get Flow Run Tasks

Returns a list of scheduled flow tasks for the site.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can only access the list of scheduled flow tasks for the flows that they own.

Response Code

200

Response Body

<tsResponse>
   <tasks>
     <task>
       <flowRun id="flowRun_id"
        priority="nn"
        consecutiveFailedCount="n"
        type="RunFlowTask">
         <schedule id="schedule_id"
          name="schedule_name"
          state="state"
          priority="nn"
          createdAt="DATE_TIME"
          updatedAt="DATE_TIME"
          type="flowRun"
          frequency="frequency"
          nextRunAt="DATE_TIME" />
           <flow id="flow_id"/>
             <parameters>
               <parameter id="parameter_id"
                type="data_type"
                name="parameter_name"
                description="parameter_description"
                value="parameter_value"
                isRequired="true-or-false">
		  <domain xsi:type="flowParameterListDomainType-or-flowParameterAnyDomainType"
                  domainType="domain_type">
		    </domain>
                </parameter>
	      </parameters>
       </flowRun>
      </task>
        ... additional tasks ...
    </tasks>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

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

Example response: 

<tsResponse version-and-namespace-settings>
    <tasks>
        <task>
            <flowRun id="1bff10bb-57ae-43df-8774-a86d14aef432" priority="50" consecutiveFailedCount="2" type="RunFlowTask">
                <schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:32:00Z"/>
                <flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/>
		 <parameters>
			<parameter id="ebfad780-c19f-42a2-822a-406468269a02" type="string" name="Region" description="" value="North" isRequired="false">
			<domain xsi:type="flowParameterListDomainType" domainType="any">
			</domain>
			</parameter>
	     </parameters>
            </flowRun>
        </task>
        <task>
            <flowRun id="f11741cb-9646-4fb8-bbac-6d099c8d56b9" priority="50" consecutiveFailedCount="2" type="RunFlowTask">
                <schedule id="36d6fab2-2a0a-432e-b464-9fe4229a9937" name="Every 2 Minutes - Only use for failing (to be suspended) flows!" state="Active" priority="50" createdAt="2018-11-08T21:57:49Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:32:00Z"/>
                <flow id="8a320dca-9151-41ea-8474-a0bb71961cc0" name="allUseCaseTFLX2"/>
		 <flowParameterSpecs/>
            </flowRun>
        </task>
        <task>
            <flowRun id="357aaf2b-758d-4feb-a447-822528635a67" priority="44" consecutiveFailedCount="2" type="RunFlowTask">
                <schedule id="6d4e61d0-2e2f-4f48-abc8-0695b95a5287" name="Every 15 mins!" state="Active" priority="50" createdAt="2018-11-08T20:45:47Z" updatedAt="2018-11-09T17:30:08Z" type="Flow" frequency="Hourly" nextRunAt="2018-11-09T17:45:00Z"/>
                <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good"/>
		 <flowParameterSpecs/>
            </flowRun>
        </task>
   </tasks>
</tsResponse>

Get Linked Task

Returns information about a specific linked task. This method shows you information about the scheduled linked task

URI

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

Parameter Values

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

Request Body

None

Permissions

All Tableau users can view linked tasks information, but can only see information about the flows in the response body if they have permissions to flows included in the linked task.

Response Code

200

Response Body

<tsResponse>
   <linkedTasks id= "linkedTasks-id"
      numSteps="number-of-steps">
       <schedule id="schedule_id"
        name="schedule-name"
        state="Active-or-Suspended"
        priority="priority"
        createdAt="datetime-created"
        updatedAt="datetime-updated"
        type="schedule-type"
        frequency="frequency"
        nextRunAt="datetime-nextrun"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="linked-tasks-step-id>
          stepNumber="step-number"
          stopDownstreamTasksOnFailure="true-or-false"/>
          ...additional linked tasks steps...
         <task>
           <flowRun id="flow-run-id"
            priority="priority"
            consecutiveFailedCount="consecutive-failed-count"
            type="task-type">
            <flow id = flow-id"
             name="flow-name"
           </flowRun>
         </task>
       </linkedTaskSteps>
       ...additional linked tasks steps...
     </linkedTasksSteps>
   </linkedTasks>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Operation unauthorized The user is not authorized to get the task.
404 404045 Linked task not found The task ID in the URI doesn't correspond to an existing linked task.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tasks/linked/1bff10bd-57ae-37df-8774-a86d14aef432" -X GET -H "X-Tableau-Auth:12ab34cd56ef98ab90ce12ef34ab52cd"

Example response: 

<tsResponse version-and-namespace-settings>
    <linkedTasks id="18d267af-4c40-4dz6-8234-6ag8c3dea67f"
      numSteps="2">
       <schedule id="3ee04ae9-4dbf-45b5-a6d6-18fa19f2jb8a"
        name="Run Flow - Every Sunday - 4:00PM"
        state="Active" priority="50"
        createdAt="2021-01-21T19:15:53Z"
        updatedAt="2022-02-27T16:00:59Z"
        type="Flow" frequency="Weekly"
        nextRunAt="2022-03-06T16:00:00Z"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="738fffc7-6a21-4af5-b49e-2c47f51480d2"
          stepNumber="1"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="690c3b2c-a309-4683-9e6e-166517dc8598"
              priority="50"
              consecutiveFailedCount="0"
              type="RunFlowTask">
               <flow id="56809d67-aca9-4f08-9fdc-4b6473c3ff02" name="r-3"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
</tsResponse>

Get Linked Tasks

Returns a list of scheduled linked tasks for a site.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.

Request Body

None

Permissions

All Tableau users can view linked tasks information, but can only see information about the flows in the response body if they have permissions to flows included in the linked task.

Response Code

200

Response Body

<tsResponse>
   <linkedTasks>
     <linkedTasks id= "linkedTasks-id"
      numSteps="number-of-steps">
       <schedule id="schedule_id"
        name="schedule-name"
        state="Active-or-Suspended"
        priority="priority"
        createdAt="datetime-created"
        updatedAt="datetime-updated"
        type="schedule-type"
        frequency="frequency"
        nextRunAt="datetime-nextrun"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="linked-tasks-step-id>
          stepNumber="step-number"
          stopDownstreamTasksOnFailure="true-or-false"/>
          ...additional linked tasks steps...
         <task>
           <flowRun id="flow-run-id"
            priority="priority"
            consecutiveFailedCount="consecutive-failed-count"
            type="task-type">
            <flow id = flow-id"
             name="flow-name"
           </flowRun>
         </task>
       </linkedTaskSteps>
       ...additional linked tasks steps...
     </linkedTasksSteps>
     ... additional linked tasks ...
    </linkedTasks>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400154 Generic query linked task error Could not get a list of linked tasks for some reason other than the ones specified below.
403 403155 Linked tasks disabled Linked tasks has been disabled for your site or server.
403 403004 Operation unauthorized You do not have permissions to see the list of linked tasks
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/9a6b7c6d-5e4f-4a2b-1c0d-9e8f7s6b5c4d/tasks/linked" -X GET -H "X-Tableau-Auth:12ab34cd56ef98ab90ce12ef34ab52cd"

Example response: 

<tsResponse version-and-namespace-settings>
   <linkedTasks>
     <linkedTasks id="18d267af-4c40-4dz6-8234-6ag8c3dea67f"
      numSteps="2">
       <schedule id="3ee04ae9-4dbf-45b5-a6d6-18fa19f2jb8a"
        name="Run Flow - Every Sunday - 4:00PM"
        state="Active" priority="50"
        createdAt="2021-01-21T19:15:53Z"
        updatedAt="2022-02-27T16:00:59Z"
        type="Flow" frequency="Weekly"
        nextRunAt="2022-03-06T16:00:00Z"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="738fffc7-6a21-4af5-b49e-2c47f51480d2"
          stepNumber="1"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="690c3b2c-a309-4683-9e6e-166517dc8598"
              priority="50"
              consecutiveFailedCount="0"
              type="RunFlowTask">
               <flow id="56809d67-aca9-4f08-9fdc-4b6473c3ff02" name="r-3"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
         <linkedTaskSteps id="b9668563-e2c3-414d-b461-084a3d951cc5"
          stepNumber="2"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="2bb8e959-f5da-4691-903e-be73eed08a4c"
              priority="50"
              consecutiveFailedCount="0"
              type="RunFlowTask">
              <flow id="19ed906f-4752-4f89-a3ca-19b406efd596"
               name="flights"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
     </linkedTasks>
     <linkedTasks id="abf4c0d2-0b5a-4dd1-9667-70b22bd73fe9"
      numSteps="2">
       <schedule id="92811890-d91c-456a-83b6-94db7d7041be"
        name="Run Flow - Weekday 2:00AM"
        state="Active" priority="50"
        createdAt="2021-01-21T19:15:52Z"
        updatedAt="2022-03-01T02:00:59Z"
        type="Flow"
        frequency="Weekly"
        nextRunAt="2022-03-02T02:00:00Z"/>
       <linkedTaskSteps>
         <linkedTaskSteps id="3061807b-e0f4-48ab-bbdd-7e032ff25858"
          stepNumber="1"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="c914cf4c-23e4-437c-b25b-11735bf586nf"
              priority="50"
              consecutiveFailedCount="0"
              type="RunFlowTask">
               <flow id="5a421e12-6dc4-42b5-9723-e8e667c728f3"
                name="Test3"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
         <linkedTaskSteps id="ed515d51-7715-4d3f-zf16-46e6f90cd5cf"
          stepNumber="2"
          stopDownstreamTasksOnFailure="true">
           <task>
             <flowRun id="fb945078-85c3-4f78-8214-f6fb3374d67e"
              priority="50"
              consecutiveFailedCount="2"
              type="RunFlowTask">
               <flow id="1ea76ax2-4ef3-49d3-9892-f1840b6e55da"
                name="Superstore Flow"/>
             </flowRun>
           </task>
         </linkedTaskSteps>
       </linkedTaskSteps>
     </linkedTasks>
   </linkedTasks>
</tsResponse>

Publish Flow

Publishes a flow on the specified site. To make other changes to a published flow, call Update Flow or Update Flow Connection.

You can do publish a flow in a single request or in multiple parts.

To publish a flow in a single request you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB.

To publish a flow in multiple parts, you initiate a file upload by calling Initiate File Upload(Link opens in a new window), send portions of the file to the server using Append to File Upload(Link opens in a new window), and then commit the upload by calling Publish Flow. In this case, Publish Flow doesn't contain the file to publish but the uploadSessionId and the flowType parameters are required.

URI

POST /api/api-version/sites/site-id/flows

POST /api/api-version/sites/site-id/flows?overwrite=overwrite-flag

POST /api/api-version/sites/site-id/flows?overwrite=overwrite-flag&uploadSessionId=upload-session-id&flowType=flow-file-type

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 to publish to.
overwrite-flag (Optional) true to overwrite a flow that has the same name, or false to fail if the specified flow already exists. The default is false. If overwrite-flag is set to true but the flow doesn't already exist, the operation succeeds.
upload-session-id If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
flow-file-type tfl or tflx to indicate whether you have uploaded a flow file (tfl) or a packaged flow file (tflx). This value is only necessary and required if you upload a file in multiple parts. In the Publish Flow call after completing file upload, specify the file type.

Publishing a file in the Request Body 

 --boundary-stringContent-Disposition:
name="request_payload"
Content-Type: text/xml
<tsRequest>
	<flow name="flow-name" >
		<project id="project-id" />
	</flow>
	<connections>
		<connection id="abc"
			password="connection-password"
			username="connection username"
			embed="embed-flag">
		<connectionCredentials
			name="connection-username"
			password="connection-password"
			embed="embed-flag" />
		</connection>
		</connections>
</tsRequest>

--boundary-string
Content-Disposition: name="tableau_flow"; filename="flow-file-name"
Content-Type: application/octet-stream
content-of-flow-file
--boundary-string--

Attribute Values

name The name to assign to the flow when it is saved on the server.
description The description of the flow.
server-address Specify the server address for an input connections.
port-number Specify the port number for input connections.
connection-username (Optional) If the flow input connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection username. If the element is included but is not required, the server ignores the element and its attributes.
connection-password (Optional) If the flow input connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection password. If the element is included but is not required, the server ignores the element and its attributes.
embed-flag (Optional) If the input connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to Trueinstructs the server to save the credentials.
project-id The ID of the project to assign the flow to.
content-of-flow-file The file itself if you are including it in the request body.

Permissions

Users who are not server administrators or site administrators can publish a flow only if the flow belongs to a project that they have permissions to publish to, have a site role that allows publishing and have write permissions on the flow this is an overwrite.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:flows:create

Response Code

201

Response Body

<tsResponse>
      <flow id="770a1cf8-6abe-4bc3-b0b8-59c4b15ce959"
            name="ShortTermRentalNola222"
            description=""
            webpageUrl="http://localhost/#/flows/3"
            fileType="tflx" createdAt="2018-11-20T19:28:58Z"
            updatedAt="2018-11-20T19:28:58Z">
           <project id="9077e04c-ece4-11e8-aa58-df538c72f42f"
            name="Default" />
           <owner id="5a39de9c-4eb0-47a7-88f7-2e78ddd58c6b" />
      </flow>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Malformed request body The XML content in the MIME multipart request is not empty.
400 400089 Missing flow name Flow name is required and was not specified.
403 403007 Invalid permissions The caller does not have the necessary permissions to publish the flow. 
400 400090 Missing flow payload The flow information (the structure containing the flow description, flow project) was not included in the request body.
400 400086 Invalid flow attachment The name of the flow doesn't end in .tfl or .tflx.
400 400087 Generic flow publishing error The flow could not be published for some other reason than those specified earlier.
409 409041 Flow already found in destination The flow name should be unique, or the overwrite flag parameter should be set to true.
403 403008 Insufficient storage quota The flow could not be published because there is not enough storage remaining on the server to accommodate its size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Query Flow

Returns information about the specified flow, including information about the project, owner, and output steps.

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/sites/site-id/flows/flow-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 flow.
flow-id The ID of the flow to return information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a flow only if they have Read(view) permission for the flow (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
   <flowOutputSteps>
     <flowOutputStep id = "flow-output-step id"
      name = "flow-name">
        ...additional output steps...
    </flowOutputSteps>
    <flow id = "flow-id">
      <project id = "project-id">
      <owner id = "owner-id">
      <tags/>
      <parameters>
	 <parameter id="parameter-id" type="data type" name="parameter name" description=" parameter description" value="current value" isRequired="true/false">
	   <domain xsi:type="flowParameterDomainType" domainType="domain type">
	   </domain>
        <parameter>
	 ...additional parameters...
      <parameters>
    </flow>
</tsResponse>

Note: Parameters is only shown in the response if parameters are enabled on the site and the flow contains parameters.

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Read forbidden A non-administrator user attempted to query the flow, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404027 Flow 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.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/ d00700fe-28a0-4ece-a7af-5543ddf38a82" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response: 

<tsResponse version-and-namespace-settings>
    <flowOutputSteps>
        <flowOutputStep id="5e4c9a74-d29a-4f62-baa5-97c443440dfc" name="CoffeeChainOutputCSV"/>
        <flowOutputStep id="baa85bce-6aab-434a-8070-72625ded8cb6" name="CoffeeChainOutputHyper"/>
        <flowOutputStep id="2f5da1ba-4a40-44a4-9201-7db6ce089811" name="CoffeeChainOutputTDE"/>
    </flowOutputSteps>
    <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good" description="" webpageUrl="http://tpqawin01/#/flows/3" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z">
        <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
        <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	 <tags/>
	<parameters>
		<parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String test parameter" value="string 2" isRequired="false">
		  <domain xsi:type="flowParameterListDomainType" domainType="all">
		</parameter>
	</parameters>
    </flow>
</tsResponse>

Query Flows for a Site

Returns the flows on a site. If the user is not an administrator, the method returns just the flows that the user has permissions to view.

URI

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

GET /api/api-version/sites/site-id/flows?filter=filter-expression

GET /api/api-version/sites/site-id/flows?sort=sort-expression

GET /api/api-version/sites/site-id/flows?pageSize=page-size&pageNumber=page-number

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 flows.
filter-expression (Optional) An expression that lets you specify a subset of flows to return. You can filter on predefined fields such as name, tags, and createdAt. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression (Optional) An expression that lets you specify the order in which flow information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
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.

Note: The filter and sort parameters can be combined with each other and with paging parameters using an ampersand (&).

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can get flows that they have Read (view) permissions for (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="page-number"
    pageSize="page-size"
    totalAvailable="total-available"/>
     <flows>
       <flow id="flow-id"
        name="flow-name"
        description="flow-description"
        webpageUrl="web-page-url"
        fileType="file-type"
        createdAt="datetime-created"
        updatedAt="datetime-updated">
         <project id="project-id" name="project-name"/>
         <owner id="owner-id"/>
	  <tags/>
	  <parameters>
           <parameter id="parameter-id" type="data type" name="parameter name" description="parameter description" value="current value" isRequired="false">
	      <domain xsi:type="flowParameterListDomainType" domainType="all">
	      </domain>
	      </parameter>
	    <parameters>
         </flow>
        ... additional flows ...
     </flows>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.3 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 is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403101 Read forbidden A non-administrator user attempted to query flows for the site, but the caller doesn't have Read permission.
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/9954070a-581d-40fa-ae73-e815ce8b0562/flows" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response: 

<tsResponse version-and-namespace-settings>
    <pagination pageNumber="1" pageSize="100" totalAvailable="7"/>
    <flows>
        <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good" description="" webpageUrl="http://tpqawin01/#/flows/3" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	     <tags/>
	     <parameters/>
        </flow>
        <flow id="c1e82fe3-e7cf-4bd5-afd3-799b1e8aac27" name="broken_loom_doc_2" description="" webpageUrl="http://tpqawin01/#/flows/26" fileType="tflx" createdAt="2018-11-06T18:19:54Z" updatedAt="2018-11-06T18:19:54Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	     <tags/>
	     <parameters>
		<parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String parameter test" value="string 2" isRequired="false">
		  <domain xsi:type="flowParameterListDomainType" domainType="all">
		</parameter>
	     </parameters>
        </flow>
        <flow id="d4eccc71-5cbd-4753-a807-d3ea9256aee1" name="Partner Influence" description="configured by ibeekun" webpageUrl="http://tpqawin01/#/flows/34" fileType="tflx" createdAt="2018-11-06T22:46:57Z" updatedAt="2018-11-06T22:46:57Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	     <tags/>
	     <parameters/>
        </flow>
        <flow id="82aefd39-ae37-4ad8-a44c-391563f12e18" name="Omniture logs" description="configured by testuser" webpageUrl="http://mytestServer/#/flows/35" fileType="tflx" createdAt="2018-11-06T22:47:18Z" updatedAt="2018-11-06T22:47:18Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	     <tags>
	     <parameters/>
        </flow>
        <flow id="b527d896-b71e-4953-b085-2afecccea427" name="NY Parking Tickets" description="configured by ibeekun" webpageUrl="http://tpqawin01/#/flows/37" fileType="tflx" createdAt="2018-11-07T00:19:48Z" updatedAt="2018-11-07T00:19:48Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	     <tags/>
	     <parameters/>
        </flow>
        <flow id="ddcd4f53-76b6-4af7-a050-fe3eef702317" name="Flow1" description="" webpageUrl="http://tpqawin01/#/flows/40" fileType="tfl" createdAt="2018-11-07T00:38:48Z" updatedAt="2018-11-07T00:38:48Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
        </flow>
        <flow id="868eab1a-2b60-448a-9913-82e4522ab952" name="local-postgres-bad-pw" description="" webpageUrl="http://tpqawin01/#/flows/78" fileType="tflx" createdAt="2018-11-07T22:18:04Z" updatedAt="2018-11-07T22:18:04Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	     <tags/>
	     <parameters/>
        </flow>
    </flows>
</tsResponse>

Query Flows for User

Returns the flows that the specified user owns in addition to those that the user has Read (view) permissions for.

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/sites/site-id/users/user-id/flows

GET /api/api-version/sites/site-id/users/user-id/flows?ownedBy=isOwner&pageSize=page-size&pageNumber=page-number

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 user.
user-id The ID of the user to get flows for.
isOwner (Optional) trueto return only flows that the specified user owns, or falseto return all flows that the specified user has at least read access to. The default is false.
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

All users can call this method, but the results of the call depend on the user's permissions. Server and site administrators see all flows for the specified user. If the isOwnerparameter is true, users who are not server or site administrators see the flows that they own on the site. If isOwnerparameter is false, users who are not server administrators see the flows that they have Read (view) permissions for.

Response Code

200

Response Body

<tsResponse>
   <pagination pageNumber="page-number"
    pageSize="page-size"
    totalAvailable="total-available"/>
    <flows>
      <flow id="flow-id"
       name="flow-name" description="flow-description"
       webpageUrl="URL"
       fileType="flow-file-type"
       createdAt="Datetime-created"
       updatedAt="Datetime-updated">
        <project id="project-id" name="project-name"/>
        <owner id="owner-id"/>
	 <tags/>
	 <parameters>
          <parameter id="parameter-id" type="data type" name="parameter name" description="parameter description" value="current value" isRequired="false">
            <domain xsi:type="flowParameterListDomainType" domainType="all">
	     </domain>
	   </parameter>
	 <parameters>
      </flow>
        ... additional flows...
    </flows>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.3 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 flows 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 exceeds upper limit The page size parameter exceeds the system-wide upper limit of 1000.
403 403101 Read forbidden A non-administrator user attempted to query flows for the user, but the caller doesn't have Read permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 User not found The user ID in the URI doesn't correspond to an existing user.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d/flows" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response: 

<tsResponse version-and-namespace-settings>
    <pagination pageNumber="1" pageSize="100" totalAvailable="41"/>
    <flows>
        <flow id="00795e57-0c0b-43c9-843f-6635d6577dec" name="several_excel_input_union2" description="" webpageUrl="http://tpqawin01/#/flows/263" fileType="tflx" createdAt="2018-11-09T20:01:04Z" updatedAt="2018-11-09T20:01:04Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="303379e9-3b66-419c-a022-7179bc13892c"/>
        </flow>
        <flow id="467242c7-3d5a-4ba8-b4c3-58b5aecc084d" name="Superstore_Test_ER" description="testing direct connection" webpageUrl="http://tpqawin01/#/flows/124" fileType="tfl" createdAt="2018-11-08T21:30:44Z" updatedAt="2018-11-08T21:30:44Z">
            <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3" name="Default"/>
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
	     <tags/>
	     <parameters>
		<parameter id="d6785a99-e997-4f9c-b0eb-91a02371621b" type="string" name="String Param" description="String parameter test" value="string 2" isRequired="false">
		  <domain xsi:type="flowParameterListDomainType" domainType="all">
		</parameter>
	     </parameters>
        </flow>
   </flows>
</tsResponse>

Query Flow Connections

Returns a list of data connections for the specific flow.

URI

GET /api/api-version/sites/site-id/flows/flow-id/connections

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 flow.
flow-id The ID of the flow to return connection information about.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can query a flow only if they have Read(view) permission for the flow (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse >
    <connections>
        <connection id="connection-id"
           type="connection-type"
           serverAddress="server-address"
           userName="user-name"
           embedPassword="true-or-false"/>
        ... additional connections ...
    </connections>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
403 403092 Read forbidden A user who is not a server administrator user attempted to query the flow connections, but the caller doesn't have Readpermission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404027 Flow 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/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response: 

<tsResponse version-and-namespace-settings>
    <connections>
        <connection id="5fd1c1db-572f-4ebd-94e7-a09e212bc147" type="sqlserver" serverAddress="mySQLServer" userName="test" embedPassword="true"/>
        <connection id="ed358ca5-f25b-43b4-8791-2dbf34631df6" type="tableau-server-site" serverAddress="http://testserver01" userName="" embedPassword="false"/>
       </connections>
</tsResponse>

Query Flow Permissions

Returns a list of permissions for the specific flow.

URI

GET /api/api-version/sites/site-id/flows/flow-id/permissions

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 flow.
flow-id The ID of the flow to get permissions for.

Request Body

None

Permissions

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

Response Code

200

Response Body

<tsResponse >
    <permissions>
        <flow id="flow-id" name="flow-name">
            <owner id="owner-id"/>
        </flow>
        <granteeCapabilities>
            <group id="group-id"/>
            <capabilities>
                <capability name="Read" mode="Allow"/>
                <capability name="Write" mode="Allow"/>
                ... additional capabilities ...
            </capabilities>
        </granteeCapabilities>
    </permissions>
</tsResponse>

Note: The parent element is included in the response only if the workbook's permissions are determined by project-level default permissions and project permissions are locked. Project permissions can be locked for a new project when you call Create Project(Link opens in a new window) or for an existing project by calling Update Project(Link opens in a new window). For more information, see Lock Content Permissions to the Project(Link opens in a new window).

Version

Version 3.3 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 404027 Flow 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/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/flows/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/permissions" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response: 

<tsResponse xmlns= version-and-namespace-settings>
    <permissions>
        <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good">
            <owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
        </flow>
        <granteeCapabilities>
            <group id="6fd1dea0-e173-11e8-ae75-832f6a4756f0"/>
            <capabilities>
                <capability name="Read" mode="Allow"/>
                <capability name="Write" mode="Allow"/>
            </capabilities>
        </granteeCapabilities>
    </permissions>
</tsResponse>

Run Flow Now

Runs the specified flow.

This method runs the specified flow with all the output steps if none are specified. If you want to run only a subset of output steps, you can specify one or more output steps using the output-ids by using the Flow Methods. The Run Flow Now method is the equivalent of selecting a flow using the Tableau Server UI, and then selecting Run Now from the menu.

A flow 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 flow task will often fail if the task has been put in the task queue in any of these ways, or is already in progress. Running the flow for a suspended task using Run Flow Now will resume the task job.

Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

 

URI

POST /api/api-version/sites/site-id/flows/flow-id/run

POST /api/api-version/sites/site-id/flows/flow-id/run?flowOutputStepIds=flow-outputstep-id&flowRunMode=flow-run-mode

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 flow.
flow-id The ID of the flow to update.

Request Body

<tsRequest>
  <flowRunSpec
   flowId="flow id"
   runMode="run mode">
    <flowParameterSpecs>
      <flowParameterSpec
	   parameterId="parameter id"
       overrideValue="override value" />
    </flowParameterSpecs>
    <flowOutputSteps>
      <flowOutputStep
       id="flow output step id" />
    </flowOutputSteps>
  </flowRunSpec>
</tsRequest>

A request body with for running a flow with no parameters:

<tsRequest>
  <flowRunSpec
   flowId="flow id"
   runMode="run mode">
    <flowOutputSteps>
      <flowOutputStep
	   id="flow output step id" />
    </flowOutputSteps>
  </flowRunSpec>
</tsRequest>

A request body for running a flow but not specifying output step (effectively running all output steps):

<tsRequest>
  <flowRunSpec
   flowId="flow id"
   runMode="run mode">
    <flowParameterSpecs>
      <flowParameterSpec
	   parameterId="parameter id"
       overrideValue="override value" />
    </flowParameterSpecs>
  </flowRunSpec>
</tsRequest>

Attribute Values

flow-id

The ID of the flow to add to the schedule. This will include all the output steps in the flow and any output steps created in the future.
flow-outputstep-id

The ID of the output steps you want to run. This parameter is optional. If you don't specify the output steps, all the output steps in the flow will be included. You can specify one or more output steps. Use the Flow Methods method to get the list of flow-outputstep-ids.
flow-run-mode

The mode to use for running this flow, either full or incremental. This parameter is optional. If you don't specify an option the run mode will be full. The flow must be configured with incremental options on the input nodes to refresh incrementally.
parameter-id

The ID of the flow parameter. Use the Flow Methods method to get the flow parameter ID. A parameter is a global placeholder value such as a number, text value, or boolean value that can replace a constant value in a flow.

Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled.

For more information, see Run flows with parameters.
overrideValue

The run-time value for the flow parameter. You must specify this if the parameter is required. Use the Flow Methods method to see if the parameter is required and to get a list of allowed values if the parameter is expecting a value from an enumerated list.

Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled.

For more information, see Run flows with parameters.

Note: You must specify the flow-id value in the URI. If you are using a request body to specify the attributes, you must also include the flow-id in the request body in addition to providing it in the URI.

Permissions

In addition to the owner of a flow, Tableau server administrators, site administrators, and project leaders can run flows within their scope. Users with a creator or explorer license that have been granted permissions by an administrator, leader or owner for a flow may also run it.

Response Code

200

Response Body

<tsResponse>
   <job id="job-id"
    mode="Asynchronous"
    type="RunFlow"
    createdAt="DateTime-CreatedAt">
   <runFlowJobType flowRunId="flow-run-id">
     <flow id="flow-id" name="flow-name"/>

   </runFlowJobType>
   </job>
</tsResponse>

Version

Version 3.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 400132 Invalid flow run mode The specified flow run mode is not valid.
400 400148 Invalid parameter override value The run-time value specified is not valid.
400 400149 Parameter override value missing The run-time value for the parameter was not specified and is required.
403 403149 Flow cannot be run The flow parameter setting is disabled on the site preventing the flow run.
403 403150 Flow cannot be run The flow cannot be run because flow parameters contain parameter domain type "any" but the Allow parameters that can accept any input setting is disabled on the site.
404 404000 Site not found The site ID in the URI is unknown.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
404 404043 Flow parameter not found The parameter ID specified in the request body does not match any of the existing parameters for this flow.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/flows/ d00700fe-28a0-4ece-a7af-5543ddf38a82/run?flowRunMode=incremental" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"

Content of empty-tsrequest.xml:

<tsrequest>
</tsrequest>

Example response: 

<tsResponse version-and-namespace-settings>
    <job id="57a8d2f6-899c-4c0f-9b25-fe0d007c5ad0" mode="Asynchronous" type="RunFlow" createdAt="2018-11-12T19:14:08Z">
        <runFlowJobType flowRunId="34b9f6d3-222a-2f2f-6a22-dd2f228a6ff2">
            <flow id="d00700fe-28a0-4ece-a7af-5543ddf38a82" name="SQLServerUserNamePassword Good"/>
        </runFlowJobType>
    </job>
</tsResponse>

Run Flow Task

Runs the specified flow run task.

Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- 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 flow. You must first schedule the task for the flow. You can do this using the Create Schedule(Link opens in a new window) method to create the task. The Run Flow task requires you to provide a task id. To get the task-id, use the Get Flow Run Tasks method, which returns the flowRun ID. The value of the flowRun ID is what you use as the task-id.

The method adds the flow run 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 flow run task, including a job id that can be used with the Query Job method to query the status of the flow run.

A flow 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 flow task will often fail if the task has been put in the task queue in any of these ways, or is already in progress. If your request results in an error code 403102, it means that there is already a scheduled task for this within a very close time period (seconds). In this case, if the task is currently in a suspended state, it will resume.

URI

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

Parameter Values

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

Request Body

None

Permissions

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

Response Code

200

Response Body

<tsResponse >
    <job id="job-id"
         mode="Asynchronous"
         type="RunFlow"
         createdAt="Datetime-CreatedAt">
        <runFlowJobType flowRunId="flow-run-id">
            <flow id="flow-id" name="flow-name"/>
        </runFlowJobType>
    </job>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400084 Flow run task error The task specified is not a flow run task.

For more information, see Handling Errors.

Example

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

Content of empty-tsrequest.xml:

<tsrequest>
</tsrequest>

Example response: 

<tsResponse version-and-namespace-settings>
    <job id="50afe58f-b719-4858-8b4b-e31700685c12" mode="Asynchronous" type="RunFlow" createdAt="2018-11-12T19:43:00Z">
        <runFlowJobType flowRunId="34b9f6d3-222a-2f2f-6a22-dd2f228a6ff2">
            <flow id="6f4bc5a1-3905-45a7-abbc-cdb735d0b79f" name="allUseCaseTFLX"/>
        </runFlowJobType>
    </job>
</tsResponse>

Run Linked Task Now

Runs the specified linked task.

This method runs the specified linked task with all the steps. Depending on the setting that the task was created with, the linked task will stop at a step on failure or continue to the next step. For more information, see schedule linked tasks.

Note:
- This method is unavailable if you don't have Data Management. For more information, see Tableau Prep Conductor.
- This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).

URI

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

Parameter Values

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

Request Body

none

Permissions

In addition to the owner of a linked task, Tableau server administrators, site administrators, and project leaders can run linked tasks within their scope. Tableau users can run a linked task if they have permissions to run all the flows included in it.

Response Code

200

Response Body

<tsResponse>
   <linkedTaskJob id="linked-task-job-id"
    linkedTaskId="linked-task-id"
    status="status"
    createdAt="DateTime-CreatedAt"/>
  </tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400153 Generic error Unable to run the linked task for some reason other than the ones specified below.
403 403155 Linked task cannot be run The linked task setting is disabled on the site.
404 404045 Linked task not found The linked task ID in the URI doesn't correspond to an existing linked task.
405 405000 Invalid request method Request type was not POST.
409 409082 Run now forbidden Run now setting has been disabled.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/tasks/linked/d00700fe-28a0-4ece-a7af-5543ddf38a82/runNow -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @empty-tsrequest.xml"

Content of empty-tsrequest.xml:

<tsrequest>
</tsrequest>

Example response: 

<tsResponse>
   <linkedTaskJob id="765dfdfc-26ec-47ea-b53b-54419c8f6b61"
    linkedTaskId="cde24429-6217-48e5-8ff5-f5dcd6a7006b"
    status="InProgress"
    createdAt="2022-02-15T00:22:22Z"/>
</tsResponse>

Update Flow

Updates the owner, project, of the specified flow.

URI

PUT /api/api-version/sites/site-id/flows/flow-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 flow.
task-id The ID of the flow to update.

Request Body

<tsRequest>
   <flow>
       <project id="6f8a2966-e173-11e8-ae74-ffd84c19d7f3"/>
	<owner id="711e59cf-d1c0-446e-be48-3673ae067f7b"/>
    </flow>
</tsRequest>

Attribute Values

new-project-id (Optional) The ID of a project to add the flow to.
new-owner-id (Optional) The ID of a user to assign the flow to as owner.

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

If the <project> element is included, the id attribute must be included, and any other attributes of the <project> element are ignored.

If the <owner> element is included, the id attribute must be included, and any other attributes of the owner are ignored.

Permissions

Tableau Server users who are server administrators or site administrators can change the owner for a flow. Users who are not server administrators can move a flow from one project to another if they own the flow or the current (source) project, or are a project leader for the current project, and they have Writepermission for the destination project.

Response Code

200

Response Body

<tsResponse >
    <flow id="flow-id"
      name="flow-name"
      description="flow-description"
      webpageUrl="flow-url"
      fileType="flow-file-type"
      createdAt="Datetime-created"
      updatedAt="Datetime-updated">
        <project id="project-id" name="project-name"/>
        <owner id="owner-id"/>
    </flow>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 3.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.
403 403098 Owner update forbidden A non-administrator user tried to change the owner for the flow.
403 403030 Project update forbidden A non-administrator user tried to change the project for the flow, but the caller doesn't have Write permission for the project. 
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404002 Owner not found The owner ID in the request body doesn't correspond to an existing owner. 
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project. 
409 409041 Flow name conflict The flow name in the request already belongs to the specified site. For the purpose of uniqueness checks, flow names are case-insensitive.

For more information, see Handling Errors.

Example

Example response: 

<tsResponse version-and-namespace-settings>
    <flow id="flow-id" name="flow-name" description="flow-description" webpageUrl="http://my-server01" fileType="tflx" createdAt="2018-11-06T04:57:55Z" updatedAt="2018-11-06T21:31:00Z">
        <project id="6f8a1234-e173-456892f-ffd84c19d7f3" name="testproject"/>
        <owner id="711e45tr-d1c0-554j-be48-3498ae067f7b"/>
    </flow>
</tsResponse>

Update Flow Connection

Updates the server address, port, username, or password for the specified flow connection. The connection can be an input or an output connection.

URI

PUT /api/api-version/sites/site-id/flows/flow-id/connections/connection-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 flow.
flow-id The ID of the flow to update.
connection-id The ID of the connection to update. To determine what connections are available for a flow, call Query Flow Connections.

Request Body

<tsRequest>
  <connection
    serverAddress="server-address" serverPort="port"
    userName="connection-username" password="connection-password"
    embedPassword="embed-password" />
</tsRequest>

Attribute Values

server-address The new server for the connection.
port The new port for the connection.
connection-username The new username for the connection.
connection-password The new password for the connection.
embed-password trueto embed the password; otherwise, false.

Any combination of the attributes inside the <connection> element is valid. You will need to provide at least one attribute. If no attributes are included, this will result in an error.

Permissions

Only Tableau Server users who are server administrators or site administrators can change the connection for a flow. Users who are not server administrators can update a flow only if they have Write(save) permission for the flow and if they have write permission for the project.

Response Code

200

Response Body

<tsResponse>
  <connection id="connection-id"
    serverAddress="serverAddress" serverPort="port"
    userName="connection-user-name" />
</tsResponse>

Version

Version 3.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.
403 403103 Update forbidden A non-administrator user tried to update a flow, but the caller doesn't have Write permission.
403 403098 Owner update forbidden A non-administrator user tried to change connection information for the flow, but the caller doesn't have Write permission.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.


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