Tableau REST API Help

API Reference—All Methods

Version: 2019.2

Using the Tableau Server REST API, you can manage and change Tableau Server resources programmatically, via HTTP. The API gives you simple access to the functionality behind the data sources, projects, workbooks, site users, and sites on a Tableau server. You can use this access to create your own custom applications or to script interactions with Tableau Server resources.

Note: Tableau does not provide support for programs that customers create that use the Tableau REST API. For help with your code, submit questions and ask for help on the Tableau developer community forums. Tableau does provide support for potential bugs in the Tableau REST API code itself, and for unmodified sample code that isn't working.

About the REST API Request and Response Examples

The REST API supports requests and responses in either JSON or XML. Set application/json or application/xml as the value of the Content-Type header
to set the form of the request, and as the value of the Accept header to set the form of the response. For
more information, see Fundamentals of the Tableau Server REST API and
REST API Example Requests.

Note: The structure of the response body returned from the server is the same whether you specify application/json or application/xml. That is, the hierarchy or nesting of the objects and elements within the response body is the same. The principal difference is that the XML response has a root element called <tsResponse>, while the JSON response does not. The JSON response body is contained in opening and closing braces { }. If you plan to make programmatic use of the response body, it is a good idea to test the endpoint using available utilities and examine the response payload. See Testing and Troubleshooting REST API Calls.

API Listing

The following table lists the Tableau Server REST API methods by category. The table also indicates which methods can be used with Tableau Online.

Attribute Values

datasource-id

The <datasource> element is not required, but can be included for compatibility with earlier versions of
the REST API. If the <datasource> element is included, the datasource-id
value must match the data source ID in the URI. Any other attributes in the <datasource> element are ignored.

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. For valid capabilities for a data source project are
ChangePermissions,
Connect,
Delete,
ExportXml,
Read (view), and
Write.

Allow to allow the capability,
or Deny to deny it. This value is case sensitive.

Permissions

Tableau Server users who are not server administrators or site administrators can add permissions only to
a data source for which they have ChangePermissions permission (either explicitly or implicitly).

The group specified in the request body doesn't correspond to an existing group.

404

404013

Capability not found

A capability specified in the request body doesn't correspond to a defined capability. This can apply to either
an invalid capability name or to a capability other than Allow or Deny for any mode value.

Version

Errors

The content of the request body is missing or incomplete, or contains malformed XML.

400

400005

Invalid label

The favorite label is empty or consists of only white space characters.

403

403004

Forbidden favorites access

A non-administrator user called this method but doesn't have permission to add a data source to the specified user's favorites.
This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.

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

404011

Data source not found

The data source ID in the request body doesn't correspond to an existing data source.

405

405000

Invalid request method

Request type was not PUT.

409

409007

Label conflict

There is already a favorite with the same label for a different data source in the specified user's favorites.

Request Body

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.

Add Default Permissions

Adds permissions to the specified project that will be applied by default to new flows, workbooks, and data sources as they are added to the project. You make separate requests to set default permissions for flows, workbooks, and data sources. Flows require Tableau Prep Conductor to be enabled on your Tableau Server. For more information, see Enable Tableau Prep Conductor.

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, ExportXml (Download), Read (view), and Write.

Request Body

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.

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.

Allow to allow the capability,
or Deny to deny it. This value is case sensitive.

Permissions

Tableau Server users who are not server administrators or site administrators can add permissions for a project only if they have ChangePermissions (version 2.0) or
ProjectLeader (version 2.1) permission for that project (either explicitly or implicitly).

Version

Errors

The content of the request body is missing or incomplete, or contains malformed XML.

400

400005

Invalid label

The favorite label is empty or consists of only white space characters.

403

403004

Access to favorites denied

A non-administrator user called this method but doesn't have permission to add a project to the specified user's favorites.
This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.

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

404005

Project not found

The project ID in the request body doesn't correspond to an existing project.

Request Body

Attribute Values

datasource-id

The data source to add the tag to. If the data source is already tagged with a tag that's included in the request body,
those tags are ignored and the data source retains them. If the <tags> element is empty, no new
tags are added to the data source.

tag

The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they
have Read permissions for the data source (either explicitly or implicitly).

Request Body

Attribute Values

view-id

The view to add the tag to. If the view is already tagged with a tag that's included in the request body,
those tags are ignored and the view retains them. If the <tags> element is empty, no new
tags are added to the view.

tag

The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they
have Read permissions for the view (either explicitly or implicitly).

Request Body

Attribute Values

workbook-id

The workbook to add the tag to. If the workbook is already tagged with a tag that's included in the request body,
those tags are ignored and the workbook retains them. If the <tags> element is empty, no new
tags are added to the workbook.

tag

The text of the tag.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they
have Read permissions for the workbook (either explicitly or implicitly).

Add User to Site

Adds a user to Tableau Server and assigns the user to the specified site.

If Tableau Server is configured to use local authentication, the information you specify is used to create a new user in Tableau Server.

Note: After creating the user, you must set a full name, password, and email address for the user with the call to Update User. If you are using SAML with local authentication, the user information that you add is not synchronized with the SAML IdP, as it would be if you were using Active Directory. Even if it is not used by SAML, the user information must be present.

If Tableau Server is configured to use Active Directory for authentication, the user you specify is imported from Active Directory into Tableau Server.

When you add user to Tableau Online, the name of the user must be the email address that is used to sign in to Tableau Online. After you add a user, Tableau Online sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password.

If you try to add a user using a specific site role but you have already reached the limit on the number of licenses for your users, the user is added as an
unlicensed user. In that case, the response code is 201 (which indicates success), but the siteRole value in the response body is set to Unlicensed.

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

URI

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

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site to add users to.

Request Body

Attribute Values

user-name

The name of the user. If the server uses local authentication, this can be any name.
If you are using Active Directory authentication, or if you are using Tableau Online, there are specific requirements for the name.

Tableau Server If Tableau Server uses Active Directory authentication, this must be the name of an existing user in Active Directory. If the user name is not unique across domains, you must include the
domain as part of the user name (for example, example\Adam or adam@example.com).

Note: Active Directory specifies a user name using two attributes: sAMAccountName
and userPrincipalName (UPN) prefix. For most Active Directory users, these attributes are the same. By default,
if you are adding a user from Active Directory, the
name that you provide in the user-name is matched against the Active Directory
sAMAccountName attribute, which becomes the name that the user signs in to Tableau Server with.
There are two exceptions: if the name that you provide is longer than 20 characters,
or if the name that you provides includes an @ character, Tableau imports the user using the Active Directory UPN. For more information, see User Naming Attributes on the MSDN site.

Tableau Online The user-name is the email address that the user will use to sign in to Tableau Online. When you add a user to the site, Tableau Online sends an email invitation. The user can click the link in the invitation to sign in and update their full name and password.

site-role

The site role to assign to the user. You can assign the following roles:
Creator,
Explorer,
ExplorerCanPublish,
SiteAdministratorExplorer,
SiteAdministratorCreator,
Unlicensed,
or
Viewer.

Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role).

auth-setting

(Optional) The new authentication type for the user.
You can assign the following values for this attribute:
SAML (the user signs in using SAML) or ServerDefault (the user signs in using the authentication method that's set for the server).
These values appear in the Authentication tab on the Settings page in Tableau Online the SAML attribute value corresponds to Single sign-on, and the ServerDefault value corresponds to TableauID.

Note: The authSetting attribute is only available if you are using Tableau Online or Tableau Server with site-specific SAML enabled.

Permissions

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

Attribute Values

view-id

The view-id value must match the view ID in the URI.

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. For valid capabilities for a view are
AddComment, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.

Allow to allow the capability, or Deny to deny it. This value is case sensitive.

Permissions

This method can only be called by server and site administrators, and user who have permission to set permissions on the workbook (either explicitly or implicitly). To use this method, the parent workbook that contains the specified view must have its showTabs attribute set to Hide. You can configure this setting by using the Update Workbook method.

Version

Errors

The content of the request body is missing or incomplete, or contains malformed XML.

400

400005

Invalid label

The favorite label is empty or consists of only white space characters.

403

403004

Forbidden Favorites access

A non-administrator user called this method but doesn't have permission to add a view to the specified user's favorites.
This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method.

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

404011

View not found

The view ID in the request body doesn't correspond to an existing view.

405

405000

Invalid request method

Request type was not PUT.

409

409007

Label conflict

There is already a favorite with the same label for a different view of the same workbook in the specified user's favorites.

Attribute Values

workbook-id

The <workbook> element is not required, but can be included for compatibility with earlier versions of
the REST API. If the <workbook> element is included, the workbook-id
value must match the workbook ID in the URI. Any other attributes in the <workbook> element are ignored.

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 workbook are
AddComment,
ChangeHierarchy,
ChangePermissions,
Delete,
ExportData,
ExportImage,
ExportXml,
Filter,
Read (view),
ShareView,
ViewComments,
ViewUnderlyingData,
WebAuthoring, and
Write.

Version

Errors

The content of the request body is missing or incomplete, or contains malformed XML.

400

400005

Invalid label

The favorite label is empty or consists of only white space characters.

403

403004

Access to Favorites forbidden

A non-administrator user called this method but
doesn't have permission to add a workbook to the specified user's favorites.
This will always be the case when the user references in the URI identifies a user other
than the user who is calling the method.

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

404006

Workbook not found

The workbook ID in the request body doesn't correspond to an existing workbook.

405

405000

Invalid request method

Request type was not PUT.

409

409007

Label conflict

There is already a favorite with the same label for a different workbook in the specified user's favorites.

Request Body

Attribute Values

workbook-id

The ID of the workbook to add to the schedule.

Permissions

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

Append to File Upload

Uploads a block of data and appends it to the data that is already uploaded. This method is called after an upload has been initiated
using Initiate File Upload.

You call Append to File Upload as many times as needed in order to upload the complete contents
of a file. When the final block of data has been uploaded, you call Publish Data Source, Publish Flow, or
Publish Workbook to commit the file.

Example

Create Group

Creates a group in Tableau Server. If the server is configured to use Active Directory for authentication, this method can create a group in Tableau Server and then import users from an Active Directory group.

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.

If you use the method to import users from an Active Directory, the import process can be performed immediately (synchronously) or as a background job (asynchronously).

Note: If Active Directory contains a large number of users, you should import them asynchronously; otherwise, the process can time out.

The Create Group response returns information in two ways: in the response header and in the response body. The ID of the new group is always
returned as the value of the Location header. If you create a local group or import an Active Directory group immediately, the
response body contains the name and ID of the new group. If you import an Active Directory group using a background process, the
response body contains a <job> element that includes a job ID. You can use the job ID to check the status of the operation by
calling Query Job.

URI

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

POST /api/api-version/sites/site-id/groups?asJob=asJob-value

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site to create the group in.

asJob-value

A Boolean value that is used if you are importing from Active Directory. If you set this to false (the default), the import process runs as a synchronous process.
If the Active Directory group contains many
users, the process might time out before it finishes.

If you set this to true, the process runs asynchronously. In that case,
Tableau Server starts a job to perform the import and returns the job ID in the Location header.
You can check the status of the import job by calling Query Job.

Note: This parameter has no effect if the server is configured to use local authentication.

When the request body contains an <import> element, a Tableau Server configured to authenticate via Active Directory will create the group in Tableau Server and modify the set
of users in the group to be the same as those in Active Directory. The source attribute of the <import> element must be set to ActiveDirectory.

Note: When a group is created by importing from Active Directory, Tableau Server
uses the value of the Active Directory sAMAccountName attribute as the user name.

Attribute Values

new-tableau-server-group-name

The name for the new group.

active-directory-group-name

The name of the Active Directory group to import.

active-directory-domain-name

The domain of the Active Directory group to import.

default-site-role

The site role to assign to users who are imported from Active Directory. You can assign the following roles:
Creator,
Explorer,
ExplorerCanPublish,
SiteAdministratorExplorer,
SiteAdministratorCreator,
Unlicensed,
or
Viewer.

Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role).

If you import a user from Active Directory whose name matches an existing user, the existing user might have a different site role than the one specified
in the <import> element in the request body. The site role that you pass with Update Group can modify the existing user's site role, either by directly upgrading the user's site role or by combining the site role you pass with the user's exiting site role. The ordering of site roles for purposes of upgrading a role is as follows, from the role with the least capabilities to the role with the most capabilities:

Unlicensed

Viewer

Explorer

ExplorerCanPublish

SiteAdministratorExplorer

SiteAdministratorCreator

Permissions

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

Response Code

201, for creating a local group and for importing immediately.

202, for importing using a background process.

Response Headers

Location: /api/3.4/sites/site-id/groups/new-group-id

Response Body

Creating a group in Tableau Server (no Active Directory) and importing from Active Directory immediately:

Version

Errors

The content of the request body is missing or incomplete, or contains malformed XML.

400

400013

Invalid site role

The value of the siteRole attribute must be
Explorer,
ExplorerCanPublish,
SiteAdministratorCreator,
SiteAdministratorExplorer,
Unlicensed,
or Viewer.

400

400019

Malformed import element

When the <import> element is present in the request body, there must be a
source, domainName, and siteRole attribute present. If
any of these is missing, the element is malformed. The source attribute must also have a value of
ActiveDirectory; otherwise the element is likewise malformed.

403

403011

ActiveDirectory is not configured

The <import> element is present, but Tableau Server is configured for local authentication.

404

404000

Site not found

The site ID in the URI doesn't correspond to an existing site.

404

404016

Domain not found

The request body includes an <import> element, but the specified domain name doesn't exist
in Active Directory.

404

404017

Active Directory group not found

The request body includes an <import> element, but no group exists in
Active Directory that matches the specified group name.

405

405000

Invalid request method

Request type was not POST.

409

409009

Group name conflict

The group name in the request already belongs to the specified site. For the purpose of uniqueness checks, group names are case-insensitive.

Create Project

Creates a project on the specified site. You can also create project hierarchies by creating a project under the specified parent project on the site.
To make changes to an existing project, call Update Project.

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

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site to create the project in.

publish-value

(Optional) A Boolean value that specifies whether to publish the sample workbooks provided by Tableau to the project. When the publish-value is not specified in the request, or the publishSamples parameter is missing, no samples will be published. To publish the sample workbooks, set publishSamples parameter to true. This option is equivalent to the tabcmd command-line utility option, publishsamples. For more information, see tabcmd.

Request Body

Attribute Values

parent-project-id

(Optional) The identifier of the parent project. Use this option to create project hierarchies. For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults.

project-name

The name to assign to the project.

project-description

(Optional) A description for the project.

content-permissions

(Optional) Specify LockedToProject to lock permissions so that users cannot overwrite the default permissions set for the project, or
specify ManagedByOwner to allow users to manage permissions for content that they own. For more information, see Lock Content Permissions to the Project.
The default is ManagedByOwner.

Permissions

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

Attribute Values

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. Higher numbers have higher priority.

schedule-type

Flow to create a flow schedule,Extract to create an extract refresh schedule, or Subscription to create a subscription schedule.

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

The granularity of the schedule. Valid values are:

Hourly. Jobs can be scheduled to run one or more times per day at intervals specified in minutes or hours.

Daily. Jobs can be scheduled to run once per day at a specific time.

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.

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.

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.

Version

Errors

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.

Example

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.

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.

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.

Attribute Values

site-name

The name of the site.

content-url

The site URL. This value can contain only characters that are valid in a URL.

admin-mode

(Optional) Specify ContentAndUsers to allow site administrators to use the server interface and tabcmd commands to add and remove users. (Specifying this option does not give site administrators permissions to manage users using the REST API.) Specify ContentOnly to prevent site administrators from adding or removing users. (Server administrators can always add or remove users.)

Note: You cannot set adminMode to ContentOnly and also set userQuota.

num-users

(Optional) The maximum number of users for the site in each of the user-based license types (Creator, Explorer and Viewer). If you do not specify this value, the limit depends on the type of licensing configured for the server. For user-based license types, the maximum number of users is set by the licenses activated on that server. For core-based licensing, there is no limit to the number of users; if you specify a maximum value, only licensed users are counted, and server administrators are excluded.

storage-quota

(Optional) The maximum amount of space for the new site, in megabytes. If you set a quota and the site exceeds it, publishers will be prevented from uploading new content until the site is under the limit again.

disable-subscriptions

(Optional) Specify true to prevent users from being able to subscribe to workbooks on the specified site. The default is false.

Create Subscription

Creates a new subscription to a view or workbook for a specific user. When a user is subscribed to the content, Tableau Server sends the content
to the user in email on the schedule that's defined in Tableau Server and specified in this call.

Delete Data Source

Deletes the specified data source from a site. When a data source is deleted, its associated data connection is also deleted. Workbooks that use the data source are not deleted, but they will no longer work properly.

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the data source.

datasource-id

The ID of the data source to delete.

Request Body

None

Permissions

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

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 call this method only if they have permission to delete permissions from the data source (either explicitly or implicitly).

Delete Default Permission

Removes default permissions from a project. After the default permission has been removed, flows, workbooks, or data sources that are added to the project do not get the specified permission by default. You make separate requests to remove default permissions for flows, workbooks, and data sources, and you make separate requests to remove default permissions for a specific group or user.

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

Delete Group

Deletes the group on a specific site. Deleting a group does not delete the users in group, but users are no longer members of the group. Any permissions that were previously assigned to the group
no longer apply.

Note: You cannot delete the All Users group.

URI

DELETE /api/api-version/sites/site-id/groups/group-id

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

Example

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

Delete Project

Deletes the specified project on a specific site. When a project is deleted, all of its assets are also deleted: associated workbooks, data sources, project view options, and rights. Use this method with caution.

URI

DELETE /api/api-version/sites/site-id/projects/project-id

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the project.

project-id

The ID of the project to delete.

Request Body

None

Permissions

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

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 remove permissions for a project only if they have ChangePermissions (version 2.0) or
ProjectLeader (version 2.1) permissions for that project (either explicitly or implicitly).

Delete Site

You can specify the site to delete by using the site ID, the site name, or the content URL. You use the key query string parameter to indicate how you are specifying the site, as shown in the URIs.

Note: You must have previously called Sign In and signed in to a site in order to delete the site. (When you call this method, you must include the authentication token
that you got back when you signed into the site.)

URI

DELETE /api/api-version/sites/site-id

DELETE /api/api-version/sites/site-name?key=name

DELETE /api/api-version/sites/content-url?key=contentUrl

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site to delete.

site-name

The name of the site to delete. If you specify a site name, you must also include the parameter key=name.

content-url

The URL of the site to delete. If you specify a content URL, you must also include the parameter key=contentUrl.

Delete Tag from Data Source

URI

Parameter Values

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the data source.

datasource-id

The ID of the data source to remove the tag from.

tag-name

The name of the tag to remove from the data source.

Request Body

None

Permissions

Tableau Server users who are not server administrators, site administrators, or workbook owners can delete a tag from a data source only if
they are project leaders or if they originally added the tag.

Allow to remove the allow permission, or Deny to
remove the deny permission.

Request Body

None

Permissions

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

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
workbook only if they have ChangePermissions permission for workbook (either explicitly or implicitly).

Download Data Source

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/content?includeExtract=extract-value

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the data source.

datasource-id

The ID of the data source to download.

extract-value

(Optional) The extract-value is a Boolean value (False or True). When the data source specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the data source. You can use this parameter to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

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

Download Data Source Revision

Note: This method is available only if version history is enabled for the specified site.
For more information, see
Maintain a History of Revisions
in the Tableau Server Help.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number/content

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number/content?includeExtract=extract-value

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the data source.

datasource-id

The ID of the data source to download.

revision-number

The revision number of the data source to download. To determine what versions are available, call
Get Data Source Revisions.

extract-value

(Optional) The extract-value is a Boolean value (False or True). When the data source specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the data source. You can use this parameter to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Tableau Server users who are site administrators can download data source revisions on the site that they are administrators for.
Users who are not server administrators or site administrators can get data source revisions
if they have all of the following:

Download Workbook

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/content?includeExtract=extract-value

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the workbook.

workbook-id

The ID of the workbook to download.

extract-value

(Optional) The extract-value is a Boolean value (False or True). When the workbook specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

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

Download Workbook PDF

Downloads a .pdf containing images of the sheets that the user has permission to view in a workbook. Download Images/PDF permissions must be enabled for the workbook (true by default).
If Show sheets in tabs is not selected for the workbook, only the default tab will appear in the .pdf file.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/pdf?type=page-type&orientation=page-orientation

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the workbook.

workbook-id

The ID of the workbook to use as the source of the .pdf file to be downloaded.

page-orientation

(Optional) The orientation of the pages in the .pdf file produced. The value can be
Portrait
or Landscape. If this parameter is not present the page orientation will default to Portrait.

Request Body

None

Permissions

To download a .pdf of a workbook, Tableau Server users who are not server administrators or site administrators need
Read and ExportImage permissions for the workbook.
The user needs Read and ExportImage permissions for a view in a workbook in order
for that view to appear in the .pdf.

Response Code

200

Response Body

This method has no response body.
The response is in the form of a downloaded .pdf file. The response header content will have Content-Type:application/pdf.

Download Workbook Revision

Note: This method is available only if version history is enabled for the specified site.
For more information, see
Maintain a History of Revisions
in the Tableau Server Help.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content?includeExtract=extract-value

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the workbook.

workbook-id

The ID of the workbook to download.

revision-number

The revision number of the workbook to download. To determine what versions are available, call
Get Workbook Revisions. Note that the current revision of a workbook cannot be accessed by this call; use Download Workbook instead.

extract-value

(Optional) The extract-value is a Boolean value (False or True). When the workbook specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Tableau Server users who are site administrators can download workbook revisions on the site that they are administrators for.
Users who are not server administrators or site administrators can download workbook revisions if they have all of the following:

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions

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

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the data source to get revisions for.

datasource-id

The ID of the data source to get revisions for.

page-size

(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.

page-number

(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get data source revisions on the site that they are administrators for.
Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

The siteRole value is returned as one of the following
values:
Creator,
Explorer,
ExplorerCanPublish,
ServerAdministrator,
SiteAdministratorExplorer,
SiteAdministratorCreator,
Unlicensed,
or
Viewer.

The externalAuthUserId value is returned for Tableau Online; it represents ID stored in Tableau's single sign-on (SSO) system.
For other server configurations, this field contains null, and the value of lastLogin is an empty string.

URI

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

GET /api/api-version/sites/site-id/users?fields=field-expression

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the users.

filter-expression

(Optional) An expression that lets you specify a subset of users to return. You can filter on predefined fields such as name and lastLogin. 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 user 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.

field-expression

(Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as
_all_ or _default_, and you can specify individual fields for the views or other supported resources. You can
include multiple field expressions in a request. For more information, see Using Fields in the REST API.

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

Request Body

None

Permissions

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

The siteRole value is returned as one of the following
values:
Creator,
Explorer,
ExplorerCanPublish,
ServerAdministrator,
SiteAdministratorExplorer,
SiteAdministratorCreator,
Unlicensed,
or
Viewer.

The externalAuthUserId value is returned for Tableau Online; it represents ID stored in Tableau's single sign-on (SSO) system.
For other server configurations, this field contains null, and the value of lastLogin is an empty string.

The authSetting attribute is returned only if you are using Tableau Online or Tableau Server with site-specific SAML enabled.

The value of path-to-view is the name of the view in the sheets collection of the view's workbook.
For example, a view named Sheet1 in a workbook named workbook the value of contentURL would be workbook/sheets/Sheet1.

URI

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

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the workbook to get revisions for.

workbook-id

The ID of the workbook to get revisions for.

page-size

(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.

page-number

(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get workbook revisions on the site that they are administrators for.
Users who are not server administrators or site administrators can get workbook revisions if they have all of the following:

Initiate File Upload returns an upload session ID that you pass to
Append to File Upload or one of the publishing methods in order to identify the upload session.

The file size that is returned in the response is initialized to zero (0) megabytes, because no data has yet been
loaded. Subsequent calls to Append to File Upload or the publishing APIs update this value.

Publish Data Source

This method is used in two ways. You can call it to publish a data source in a single request. To do that, 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. If you want to avoid having the publishing process time out, you can use the asJob parameter to make workbook publication asynchronous.

Alternatively, you can publish a data source in multiple parts. To do that,
you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using
Append to File Upload, and then commit the upload by calling Publish Data Source.
In this case, Publish Data Source doesn't contain the file to publish.

Extracts with multiple table optionsIf an extract was stored using the multiple tables option, you can't append data to it.

Data Sources stored locallyWhen you publish a data source from your local computer to the server, you must make sure that the server has all the components that are required in order
for other users to see and interact with the data source. For example, if the data source is based on an Excel spreadsheet, you
typically publish a packaged data source (.tdsx file) that contains all the components for that data source.

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site to publish to.

overwrite-flag

(Optional) true to overwrite a data source that has the same name, or false
to fail if the specified data source already exists. The default is false. If overwrite-flag
is set to true but the data source doesn't already exist, the operation succeeds.

You can include both the overwrite and append parameters in a request, but they cannot both be true.

asJob-value

(Optional) A Boolean value that is used to publish data sources asynchronously. If you set this value to false (the default), the publishing process runs as a synchronous process. If a workbook is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job.

append-flag

(Optional) true to append the data being published to an existing data source that has the same name. The default
is false. If append-flag
is set to true but the data source doesn't already exist, the operation fails.

In order to append data to an existing data source, both the data source on the server and the data source you are publishing must be extracts (.tde and .hyper files). The schemas
of the two extracts must match.

If an extract was stored using the multiple tables option, you can't append data to it.

You can include both the overwrite and append parameters in a request, but they cannot both be true.

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.

datasource-file-type

hyper, tds, tdsx, or tde the kind of file
that you are uploading. This value is required if you are calling Publish Data Source in order to
commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the
body of the request.

Request Body

The content type in the header of requests to publish a data source must use the mixed multipart content type with a boundary string definition,
in the form of:
Content-Type: multipart/mixed; boundary=boundary-string.

Attribute Values

boundary-string

A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value
must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string

datasource-name

The name to assign to the data source when it is saved on the server.

connection-username

(Optional) If the data source connection requires credentials, the <connectionCredentials> element is 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.

(Optional) If the data source connection requires credentials, the <connectionCredentials> element is 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 data source connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to true instructs the server to save the credentials for when the data source is used.

oauth-flag

(Optional) If the data source connection is configured to use OAuth, set this to true to specify that the value of the name attribute
in the <connectionCredentials> element is an
OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the data source.
For more information, see
OAuth Connections in the Tableau Server documentation.

project-id

The ID of the project to assign the data source to. If the project is not specified, the workbook will be published to the default project.

datasource-file-name

The file name (including extension) of the data source file to upload. This attribute is used in the request body only if the
request also includes the content of the data source file; it is not used if you are committing a file uploaded using
previous requests.

content-of-datasource-file

The content of the data source file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.

Permissions

Tableau Server users who are not server administrators or site administrators can
view data sources only if they have Connect permission
for the data source (either explicitly or implicitly).

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, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Flow. In this case, Publish Flow doesn't contain the file to publish but the upload-session-id and the flow-file-type parameters are required.

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

URI

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

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

Parameter Values

api-version

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

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

(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

Tableau Server 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.

Publish Workbook

This method is used in two ways. You can call it to publish a workbook in a single request. To do that, 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. If you want to avoid having the publishing process time out, you can use the asJob parameter to make workbook publication asynchronous.

Alternatively, you can publish a workbook in multiple parts. To do that,
you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using
Append to File Upload, and then commit the upload by calling Publish Workbook.
In this case, Publish Workbook doesn't contain the file to publish.

Hiding views in a published workbookTo exclude certain sheets (also known as views) when you publish a workbook, configure them in the request as hidden. You cannot publish a workbook if all sheets are hidden.

Extracts with multiple table optionsIf an extract was stored using the multiple tables option, you can't append data to it.

Workbooks that rely on external local resourcesWhen you publish a workbook from your local computer to the server, the publish process will fail if the workbook relies on resources (such as an Excel file or other
data file) that are on your local computer but are not available on the server. (Unlike the publish process that is used in Tableau Desktop, the REST API publish process cannot
automatically include extracts or other resources that the workbook uses.) If you are publishing a workbook that gets its data from a source on your
computer, save the workbook as a packaged workbook (.twbx file) and publish the package so that workbook has all the resources it needs on the server.

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site to publish to.

overwrite-flag

(Optional) true to overwrite a workbook that has the same name, or false
to fail if the specified workbook already exists. The default is false. If overwrite-flag
is set to true but the workbook doesn't already exist, the operation succeeds.

asJob-value

(Optional) A Boolean value that is used to publish workbooks asynchronously. If you set this value to false (the default), the workbook publishing process runs as a synchronous process. If a workbook is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job.

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.

workbook-file-type

twb or twbx to indicate whether you have uploaded a
workbook file (twb) or a packaged workbook file (twbx). This value is required if you are calling Publish Workbook in order to
commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the
body of the request.

Request Body

The content type in the header of requests to publish a workbook must use the mixed multipart content type with a boundary string definition,
in the form of:
Content-Type: multipart/mixed; boundary=boundary-string.

Attribute Values

boundary-string

A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value
must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string

workbook-name

The name to assign to the workbook when it is saved on the server.

show-tabs-flag

(Optional) Specify true to have the published workbook show views in tabs; otherwise, false. The default is false.

user-id

(Optional) The ID (not name) of the user to to generate thumbnails as. You can get the user ID by calling Get Users on Site.

server-address

(Optional) Specify the server address for a data source connection if that data source does not use OAuth.

port-number

(Optional) Specify the port number for a data source connection if that data source does not use OAuth.

connection-username

(Optional) If the workbook's data source connections require credentials, the
<connectionCredentials> elements are included and this attribute specifies
the connection username. If the element is included but is not required (for example, if the data source uses OAuth),
the server ignores the element and its attributes.

Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to
a data source that requires credentials, unless that data source uses OAuth.

connection-password

(Optional) If the workbook's data source connections require credentials, the
<connectionCredentials> elements are included and this attribute specifies
the connection password. If the element is included but is not required (for example, if the data source uses OAuth),
the server ignores the element and its attributes.

Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to
a data source that requires credentials, unless that data source uses OAuth.

embed-flag

(Optional) If the workbook's data source connection requires credentials, the <connectionCredentials> element is included.
Setting this attribute to true instructs the server to save the credentials for when the data source is used.

oauth-flag

(Optional) If the workbook's data source connection is configured to use OAuth, set this to true to specify that the value of the name attribute
in the <connectionCredentials> element is an
OAuth username. In that case, no password is required and the value of the embed attribute specifies
whether to embed the OAuth credential with the workbook, and the server address and port number are not required. For more information, see
OAuth Connections in the Tableau Server documentation.

hide-view-flag

Setting this flag to true will cause the named view to be hidden in the published workbook. The default value is false.
You can specify any number of views to hide. If all views in a workbook are hidden the server will not perform a publish.

project-id

The ID of the project to assign the workbook to. If the project is not specified, the workbook will be published to the default project.

workbook-file-name

The file name (including extension) of the workbook file to upload. This attribute is used in the request body only if the
request also includes the content of the workbook file; it is not used if you are committing a file uploaded using
previous requests.

content-of-workbook-file

The content of the workbook file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.

Permissions

Tableau Server users who are not server administrators or site administrators can publish a workbook only if the workbook belongs to a project that they have
permissions to publish to.

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 or for an existing project by calling Update Project.
For more information, see Lock Content Permissions to the Project.

Query Data Sources

Returns a list of data sources on the specified site, with optional parameters for specifying the paging of large results.

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/datasources

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

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

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

GET /api/api-version/sites/site-id/users?fields=field-expression

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the data sources.

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.

filter-expression

(Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name and updatedAt. 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 user 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.

field-expression

(Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as
_all_ or _default_, and you can specify individual fields for the workbooks or other supported resources. You can
include multiple field expressions in a request. For more information, see Using Fields in the Rest API.

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

Request Body

None

Permissions

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

Query Default Permissions

Returns information about the default permissions for a project that is, the permissions that will be set by default for flows, workbooks, and data sources that are added to the project. You make separate requests to query the default permissions for flows, workbooks, and data sources.

Get Extract Refresh Tasks in a Schedule

Returns a list of the extract refresh tasks for a specified schedule on the specified site.

To get the ID of a schedule, call the Query Schedules method. Note that the Query Schedules
method is global to the server; schedules are not specific to a site. Therefore, the URI for the Query Schedules method
does not include /sites/ or a site ID. However, individual scheduled tasks are specific to a site, and the URI for
Query Extract Refresh Tasks
must include the site information.

URI

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

Parameter Values

api-version

The version of the API to use, such as 2.2. For more information, see REST API Versions.

site-id

The ID of the site that contains the refresh tasks.

schedule-id

The ID of the schedule to get extract information for.

page-size

(Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.

page-number

(Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

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

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 or for an existing project by calling Update Project.
For more information, see Lock Content Permissions to the Project.

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.4. For more information, see REST API 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).

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.4. For more information, see REST API 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.

Query Groups

Returns a list of groups on the specified site, with optional parameters for specifying the paging of large results.

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/groups

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

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

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

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the groups.

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.

filter-expression

(Optional) An expression that lets you specify a subset of groups to return. You can filter on predefined fields such as name. 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 user 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.

Request Body

None

Permissions

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

If the group was imported from Active Directory,
the name attribute of the <domain> element contains the group's Active Directory domain. If
the server is configured to use local authentication, the name attribute of the <domain>
contains local.

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

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 who's 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.

Query Jobs

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

Query Projects

Returns a list of projects on the specified site, with optional parameters for specifying the paging of large results.

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/projects

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

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

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

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site that contains the projects.

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.

filter-expression

(Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name, ownerName, and parentProjectId. 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 user 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.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permission for the project (either implicitly or explicitly).

Query Site

Returns information about the specified site, with the option to return information about the storage space and user count for the site.

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.

You can specify the site to delete by using the site ID, the site name, or the content URL. You use the key query string parameter to indicate how you are specifying the site, as shown in the URIs.

Note: You can only get site information for the site that you have signed in to.

URI

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

GET /api/api-version/sites/site-name?key=name

GET /api/api-version/sites/content-url?key=contentUrl

GET /api/api-version/sites/site-id?includeUsage=include-usage-flag

Parameter Values

api-version

The version of the API to use, such as 3.4. For more information, see REST API Versions.

site-id

The ID of the site to get information for.

site-name

The name of the site to get information for. If you specify a site name, you must also include the parameter key=name.

content-url

The URL of the site to get information for. If you specify a content URL, you must also include the parameter key=contentUrl.

include-usage-flag

The boolean flag to include site usage metrics in the response body. If true, then the site element of the response will contain a usage node with the attributes numUsers (number of users) and storage (storage in megabytes).

To set the flag to include usage in the response, append includeUsage=true as a querystring element any valid query site URI.

Request Body

None

Permissions

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