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]

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

Datasources

Field	Operator
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	Operator
createdAt	eq gt gte lt lte
name	eq in
ownerName	eq
projectId	eq
projectName	eq in
updated At	eq gt gte lt lte

Flow Runs

Field	Operator
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	Operator
domainName	eq in
domainNickname	eq in
id (added in API 3.22, Tableau Cloud only)	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	Operator
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	Operator
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	Operator
channel	eq
notificationType	eq

Sites

Field	Operator
id	eq

Projects

Field	Operator
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

Users

Field	Operator
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	Operator
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	Operator
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.

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.22/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 Download View Crosstab Excel, Query View Data(Link opens in a new window), Query View Image(Link opens in a new window), and Query View PDF(Link opens in a new window) 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.

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.