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

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.

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.18/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
isLocal eq
minimumSiteRole eq
in
name cieq
eq
in
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 in the middle of a string are supported in Tableau Cloud Mar 2022/Server 2022.1.4.

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.18/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, are not 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. Note that 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.


Thanks for your feedback!