Tableau REST API Help

You can filter and sort the data that gets returned from requests to the following REST API endpoints:

• Get Users on Site [filter list]
• Get User Notification Preferences [filter list]
• List Custom Views [filter list]
• List Group Sets [filter list]
• List Recycle Bin Content by Type [filter list]
• Query Datasources [filter list]
• Query Groups [filter list]
• Query Group Sets [filter list]
• Query Jobs [filter list]
• Query Projects [filter list]
• Query Views for Site [filter list]
• Query Workbooks for Site [filter list]
• Query Flows for a Site [filter list]
• Get Flow Runs [filter list]
• Query Metrics for a Site [filter list]

You can also filter query views using fields in underlying workbook data when using the Download View Crosstab Excel, Query View Data, Query View Image, and Query View PDF methods. To learn more, see View query filters.

Tip: Although you can't filter using the Query Site endpoint, you can look up a specific site by site-id or site-name?key=name.

Filtering

By default, methods like Get Users on Site return information about all the users or workbooks on a Tableau Server site. If there are many entities, the method returns them in chunks (pages). If you want information about a specific user or workbook, one option is to loop through the information returned by the call and look for the user or workbook that you're interested in.

As an alternative, starting in the REST API version 2.3 (Tableau Server 10.0), you can include a filter expression in the query string of the URI, using the following syntax:

filter=field:operator:value

The following example shows how to include a filter in a call to get users on a site:

http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=siteRole:eq:Viewer

In the preceding example, the method returns only the users whose site role is Viewer.

Note: Filter expressions can’t contain ampersand (&) or comma (,) characters because these characters are used as field expression separators. This is true even if those characters are encoded.

Filter expressions

The following tables list the field names and operators you can use in a filter expression. Notice that the user-related calls support slightly different fields than the workbook-related calls.

Custom views

Field	Supported Operators
createdAt	eq, gt, gte, lt, lte
id	eq, in
name	eq, in
ownerId	eq
shared	eq
updatedAt	eq, gt, gte, lt, lte
viewId	eq
workbookId	eq

Data sources

Field	Supported Operators
authenticationType	eq, in
connectedWorkbookType	eq, gt, gte, lt, lte
connectionTo	eq, in
connectionType	eq, in
contentUrl	eq, in
createdAt	eq, gt, gte, lt, lte
databaseName	eq, in
databaseUserName	eq, in
description	eq, in
favoritesTotal	eq, gt, gte, lt, lte
hasAlert	eq
hasEmbeddedPassword	eq
hasExtracts	eq
isCertified	eq
isConnectable	eq
isDefaultPort	eq
isHierarchical	eq
isPublished	eq
name	eq, in
ownerDomain	eq, in
ownerEmail	eq
ownerName	eq, in
projectName (Not available in API 3.13 to 3.17)	eq, in
serverName	eq, in
serverPort	eq
size	eq, gt, gte, lt, lte
tableName	eq, in
tags	eq, in
type	eq
updatedAt	eq, gt, gte, lt, lte

Flows

Field	Supported Operators
createdAt	eq, gt, gte, lt, lte
name	eq, in
ownerName	eq
projectId	eq
projectName	eq, in
updatedAt	eq, gt, gte, lt, lte

Flow Runs

Field	Supported Operators
completeAt	eq, gt, gte, lt, lte
flowId	eq, in
progress	eq, gt, gte, lt, lte
startedAt	eq, gt, gte, lt, lte
userId	eq, in

Groups

Field	Supported Operators
domainName	eq, in
domainNickname	eq, in
isExternalUserEnabled (added in API 3.21, Tableau Cloud only)	eq
isLocal	eq
luid (added in API 3.22, Tableau Cloud only)	eq, in
minimumSiteRole	eq, in
name	cieq, eq, in, like
userCount	eq, gt, gte, lt, lte

Group Sets

Field	Supported Operators
domainName	eq, in
domainNickname	eq, in
isExternalUserEnabled (added in API 3.21, Tableau Cloud only)	eq
isLocal	eq
luid (added in API 3.22, Tableau Cloud only)	eq, in
minimumSiteRole	eq, in
name	cieq, eq, in, like
userCount	eq, gt, gte, lt, lte

Jobs

Field	Supported Operators
args	has
completedAt	eq, gt, gte, lt, lte
createdAt	eq, gt, gte, lt, lte
jobType	eq, in
notes	has
priority	eq, gt, gte, lt, lte
progress	eq, gt, gte, lt, lte
startedAt	eq, gt, gte, lt, lte
status	eq
subtitle	eq, has
title	eq, has

Metrics

Field	Supported Operators
createdAt	eq, gt, gte, lt, lte
favoritesTotal	eq, gt, gte, lt, lte
hitsTotal	eq, gt, gte, lt, lte
name	eq, in
ownerDomain	eq, in
ownerEmail	eq, in
ownerName	eq, in
projectName	eq, in
tags	eq, in
updatedAt	eq, gt, gte, lt, lte

Notification Preferences

Field	Supported Operators
channel	eq
notificationType	eq

Projects

Field	Supported Operators
createdAt	eq, gt, gte, lt, lte
name	eq, in
ownerDomain	eq, in
ownerEmail	eq, in
ownerName	eq, in
parentProjectId	eq, in
topLevelProject	eq
updatedAt	eq, gt, gte, lt, lte

Recycle Bin Content

Field	Supported Operators
createdAt	eq, gt, gte, lt, lte
deleterId	eq, in
id	eq, in
name	eq, in
ownerId	eq, in
path	eq, in
updatedAt	eq, gt, gte, lt, lte

Sites

Field	Supported Operators
id	eq

Users

Field	Supported Operators
domainName	eq, in
friendlyName	eq, in
isLocal	eq
lastLogin	eq, gt, gte, lt, lte
luid	eq, in
name	cieq, eq, in
siteRole	eq, in

Views

Field	Supported Operators
caption	eq, in
contentUrl	eq, in
createdAt	eq, gt, gte, lt, lte
favoritesTotal	eq, gt, gte, lt, lte
fields	eq, in
hitsTotal	eq, gt, gte, lt, lte
name	eq, in
ownerDomain	eq, in
ownerEmail	eq, in
ownerName	eq
projectName	eq, in
sheetNumber	eq, gt, gte, lt, lte
sheetType	eq, in
tags	eq, in
title	eq, in
updatedAt	eq, gt, gte, lt, lte
viewUrlName	eq, in
workbookDescription	eq, in
workbookName	eq, in

Workbooks

Field	Supported Operators
createdAt	eq, gt, gte, lt, lte
contentUrl	eq, in
displayTabs	eq
favoritesTotal	eq, gt, gte, lt, lte
hasAlerts	eq
hasExtracts	eq
name	eq, in
ownerDomain	eq, in
ownerEmail	eq, in
ownerName	eq, in
projectName	eq, in
sheetCount	eq, gt, gte, lt, lte
size	eq, gt, gte, lt, lte
subscriptionsTotal	eq, gt, gte, lt, lte
tags	eq, in
updatedAt	eq, gt, gte, lt, lte

Filter expression notes

• Operators are delimited with colons (:).

• If any reserved characters following the question mark (?) in the URI are encoded, then all reserved characters must be encoded. For example, the colon character (:) would be encoded as %3A and the equals character (=) would be encoded as %3D.

• The operators are:

  • cieq: case-insensitive equals
  • eq: equals
  • gt: greater than
  • gte: greater than or equal
  • has: includes the specified string
  • in: any of [list] (for searching tags)
  • lt: less than
  • lte: less than or equal

• Field names, operator names, and values are case-sensitive.

• Values should be URL-encoded. For example, to search for the workbook named Project Views, include a filter like filter=name:eq:Project+Views.

• Substring search (the has operator) is only supported for the Query Jobs method.

• To filter on multiple fields, combine expressions using a comma, as in this example:

  filter=lastLogin:gte:2016-01-01T00:00:00Z,siteRole:eq:Publisher

  Multiple expressions are combined using a logical AND. (However, see next point.)

• If you include the same field multiple times in a filter expression, only the last reference to the field is used. For example, in the following filter for a Get Users on Site call, the siteRole field appears twice. Tableau Server returns only the users whose site role is Viewer, because that's the value in the last reference.

  filter=siteRole:eq:Publisher,siteRole:eq:Viewer

• For date-time values, use ISO 8601(Link opens in a new window) format (for example, 2016-05-04T21:24:49Z).

• Wildcard searches for characters using starts with, ends with, and contains-based searches are supported starting in Tableau Cloud May 2023 and Tableau Server 2022.1.14.

  For example, if searching for a string such as "marketing-example", wildcard search can like the following:

  • Starts with: ?filter=name:eq:mark*

  • Ends with: ?filter=name:eq:*-ample

  • Contains: ?filter=name:eq:mark*ex*

Searching workbooks using tags

To search for a workbook that has one specific tag, use the tag field and the eq operator, as in the following example:

http://MY-SERVER/api/2.3/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks?filter=tags:eq:stocks

This filter finds workbooks in which at least one of the tags is stocks. (The workbooks returned by this filter might have other tags as well.)

You can also search for workbooks if they have any one of a list of tags—that is, you can create an OR search. To do this, use the in operator and provide a list of tags to search for, as in the following example:

http://MY-SERVER/api/2.3/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks?filter=tags:in:[stocks,market]

This filter finds workbooks that either have a tag stocks or a tag market (no matter what other tags the workbooks might have).

Sorting

To sort the results, include the sort parameter. The syntax is this:

sort=field:direction

You can sort on the same fields that you use to filter. The direction value is asc (ascending) or desc (descending), and is required.

You can specify multiple levels of sorting by including multiple sort expressions, as in this example:

sort=siteRole:asc,name:desc

This example causes the results to be sorted first by site role in ascending order, and within site role, by name in descending order.

Combining parameters

You can combine filter, sort, and paging operators in the same call, separating them with &. The following example shows how you can combine a filter parameter, a sort parameter, and a paging parameter.

http://MY-SERVER/api/3.29/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=lastLogin:gte:2016-02-01T00:00:00Z&sort=siteRole:desc,name:desc&pageNumber=2

View filter queries

When using the following methods, you can use a filter expression in your request query parameters to modify the view data returned. The expression uses fields in the underlying workbook data to define the filter.

• Download View Crosstab Excel
• Get Custom View PDF(Link opens in a new window)
• Get Custom View Data(Link opens in a new window)
• Download Workbook PDF(Link opens in a new window)
• Query View Data(Link opens in a new window)
• Query View Image(Link opens in a new window)
• Query View PDF(Link opens in a new window)

View filtering basics

Fields in a view filter expression can be measures or dimensions of your view data. To filter a view using a field, add one or more query parameters to your method call, structured as key=value pairs, prefaced by the constant vf_. The basic pattern of a view filter expression looks like:

?vf_{field-key-name}={field-value}

Wild cards, value ranges, and non-equivalencies, like contains, less than, or greater than, aren’t supported. A field key name and field value must exactly match the measure or dimension names and values they express. For example, you could filter a view from a workbook with a year field that only displays data from the year 2017 using the following filter:

?vf_year=2017

Field key names and values that contain spaces or other special characters should be URL encoded. For instance, the key name Product type used in a view filter query would be:

?vf_Product%20type=widget.

Filtering for multiple fields and values

When you want to filter for more than one key, or for more than one value of a key, keep these things in mind:

• A view filter expression can contain more than one key by appending keys to the query string with an ampersand (&).

  The expression ?vf_year=2017&vf_region=west would return data for the year 2017 in the west region, for a workbook that used a region field for which west was a valid value.

• A key in a view filter expression can have more than one value by adding values as a comma-separated list.

  The expression ?vf_year=2017,2018 would return data for the years 2017 and 2018.

• If there’s more than one key, then the values of each key are linked positionally.

  The expression ?vf_year=2017,2018&vf_region=west,east filters the response to data for the year 2017 in the west region, and the year 2018 in the east region. The first value of the first key impacts the meaning of the first value of the second key. The second value of the first key impacts the second value of the second key. The same relationship would be true of any further keys/values added to the query.

• All keys in the query must have the same number of values.

  The expression ?vf_year=2017,2018&vf_region=west,west would return 2017 and 2018 values for the west region.

  The expression ?vf_year=2017,2017,2018,2018&vf_region=east,west,east,west would return data for the years 2017 and 2018 for both east and west regions.

Date and time in view filter queries

Dates and times in a view filter query are formatted using the pattern:

yyyy-mm-dd hh:mm:ss

Time can be omitted but, if included, the format has a built-in space character that must be URL encoded, as in the following example:

?vf_datetime=2022-03-31%20022:08:58

Filtering on fields not in the original view

Your view filter expression can include fields that don’t impact the original view you’re querying. For instance, the data for a workbook could include a dimension called Product Type, with the valid value widget, that isn’t used to form the year and region view specified in your request. If you include that dimension as a field in your filter expression, then the results would be filtered in a way that the original view wasn’t.

For instance, consider a view that originally shows all products because it doesn’t use Product type to filter its content in any way. A request for that view that used the expression ?vf_Product%20type=widget in its query string would return data only for widgets, not all product types.

Note: Use care when filtering on fields not in the original view as the result could be misleading. For instance, if the original view has the label: “All products, all years”, then a downloaded image of the view using this example query would show data that didn’t match that label.