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 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.15/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users?filter=siteRole:eq:Viewer

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

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

Filter expressions

The following table lists 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.

  Field Operator
Users lastLogin eq
gt
gte
lt
lte
  name eq
in
siteRole eq
in
Notification Preferences channel eq
  notificationType eq
Datasources name eq
in
  favoritesTotal eq
gt
gte
lt
lte
  type eq
  createdAt eq
gt
gte
lt
lte
  ownerName eq
  updatedAt eq
gt
gte
lt
lte
tags eq
in
Groups name eq
in
  domainName eq
in
domainNickname eq
in
isLocal eq
userCount eq
gt
gte
lt
lte
minimumSiteRole eq
in
Jobs completedAt eq
gt
gte
lt
lte
  createdAt eq
gt
gte
lt
lte
  jobType eq
in
  notes has
  startedAt eq
gt
gte
lt
lte
  status eq
  subtitle eq
has
  title eq
has
Projects name eq
in
  createdAt eq
gt
gte
lt
lte
  ownerDomain eq
in
  ownerEmail eq
in
  ownerName eq
in
  parentProjectId eq
  updatedAt eq
gt
gte
lt
lte
Views name eq

in

  favoritesTotal eq
gt
gte
lt
lte
  createdAt eq
gt
gte
lt
lte
  hitsTotal eq
gt
gte
lt
lte
  ownerName eq
tags eq
in
  updatedAt eq
gt
gte
lt
lte
Workbooks createdAt eq
gt
gte
lt
lte
  favoritesTotal eq
gt
gte
lt
lte
  name eq

in

ownerName eq

in

tags eq
in
updatedAt eq
gt
gte
lt
lte
Flows name

eq
in

  ownerName eq
  projectName eq
in
  createdAt eq
gt
gte
lt
lte
  updated At eq
gt
gte
lt
lte
Metrics name

eq
in

  createdAt eq
gt
gte
lt
lte
  updatedAt eq
gt
gte
lt
lte
  ownerName eq
in
  ownerDomain eq
in
  ownerEmail eq
in
  projectName eq
in
  hitsTotal eq
gt
gte
lt
lte
  favoritesTotal eq
gt
gte
lt
lte
  tags eq
in

Filter expression notes

  • Operators are delimited with colons (:).

  • If any reserved characters following the question mark (?) in the URI are encoded, than 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:

    • eq—equals
    • gt—greater than
    • gte—greater than or equal
    • has—contains the specified string
    • lt—less than
    • lte—less than or equal
    • in—any of [list] (for searching tags)
  • 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: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 will return 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).

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 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.15/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 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 is 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. The field key name and field value(s) 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 querystring 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 is 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 do not impact the original view you are querying. For instance, the data for a workbook could include a dimension called Product Type, with the valid value widget, that is not 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 was not.

For instance, consider a view that originally shows all products because it does not 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 querystring 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!