Favorites Methods

Using the favorites methods of the Tableau Server REST API you can:

  • List a user's favorites
  • Add or delete data sources, projects, views, workbooks, and flows to and from a user's favorites
  • Move an item to organize a user's favorites

This functionality relates to the UI elements and concepts described at: Mark Favorites(Link opens in a new window).

Add Data Source to Favorites

Adds the specified data source to the user's favorites.

If the user already has the data source listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <datasource id="datasource-id" />
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
datasource-id The ID of the data source to add as a favorite.

Permissions

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

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite-label">
     <datasource id="datasource-id" />
    </favorite>
    <favorite label="favorite-label">
     <datasource id="datasource-id" />
    </favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>
        

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request 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.

For more information, see Handling Errors.

Add Flow to Favorites

Adds the specified flow to the user's favorites.

If the user already has the flow listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <flow id="flow-id" />
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
flow-id The ID of the flow to add as a favorite.

Permissions

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

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite-label">
     <flow id="flow-id" />
    </favorite>
    <favorite label="favorite-label">
     <flow id="flow-id" />
    </favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>
        

Version

Version 3.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request 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 404027 Flow not found The flow ID in the URI doesn't correspond to an existing flow.
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.

For more information, see Handling Errors.

Add Project to Favorites

Adds the specified project to a user's favorites.

If the user already has the project listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <project id="project-id"/>
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
project-id The ID (not name) of the project to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to add a project to a favorite list (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite1-label">
     <project id="project-id" />
    </favorite>
    <favorite label="favorite2-label">
     <project id="project-id" />
    </favorite>
  </favorites>
</tsResponse>

        

Version

Version 3.1 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request 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.
405 405000 Invalid request method Request type was not PUT.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.13/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/favorites/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -d @add-project-to-favorites.xml -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Content of add-project-to-favorites.xml:

<tsRequest>
  <favorite label="Economic Indicators">
    <project id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" />
  </favorite>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="Economic Indicators">
      <project id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
    </favorite>
  </favorites>
</tsResponse>

Add View to Favorites

Adds the specified view to a user's favorites.

If the user already has the view listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <view id="view-id" />
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server.
view-id The ID (not name) of the view to add as a favorite.

Permissions

Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to add a view to a favorite list (either explicitly or implicitly).

Response Code

200

Response Body

<tsResponse>
  <favorites>
    <favorite label="favorite-labe1">
	  <view id="view-id"
	    name="view-name"
    	contentUrl="content-url"
	    createdAt="created-at"
		updatedAt="updated-at"
  		viewUrlName="view-url-name">
		  <workbook id="workbook-luid"/>
		  <project id"project-luid"/>
		  <tags />
	  </view>
	</favorite>
    ... additional favorites ...
  </favorites>
</tsResponse>
        

The value of view-url-name is the name of the view in its URL. For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1 in your browser address bar, then the view-url-name would be VIEW_1. Modifying the name (display name) of a view will not impact the view-url-name (path element of the view's URL).

Version

Version 1.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request 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.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.13/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/favorites/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X PUT -d @add-view-to-favorites.xml -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Content of add-view-to-favorite.xml:

<tsRequest>
  <favorite label="Economic Indicators">
    <view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" />
  </favorite>
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="DC Crimespotting">
	  <view id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="Crimes_DC"
		contentUrl="content-url"
		createdAt="created-at"
		updatedAt="updated-at"
		viewUrlName="view-url-name">
		  <workbook id="abb3e4c1-e650-4704-870a-03fb7615136f"/>
		  <project id"3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"/>
		  <tags />
	  </view>
    </favorite>
    <favorite label="Economic Indicators">
      <view id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
    </favorite>
  </favorites>
</tsResponse>

Add Workbook to Favorites

Adds the specified workbook to a user's favorites.

If the user already has the workbook listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.

URI

PUT /api/api-version/sites/site-id/favorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
user-id The ID of the user to add the favorite for.

Request Body

<tsRequest>
  <favorite label="favorite-label">
    <workbook id="workbook-id" />
  </favorite>
</tsRequest>
        

Attribute Values

favorite-label A label to assign to the favorite. This value is displayed when you search for favorites on the server. If the label is already in use for another workbook, an error is returned.
workbook-id The ID (not name) of the workbook to add as a favorite.

Permissions

Tableau Server users who are not administrators or site administrators can call this method only if they have permission to add a workbook to a favorites list.

Response Code

200

Response Body

<tsResponse>
  <favorites>
      <favorite label="favorite-label">
        <workbook id="workbook-id" />
      </favorite>
      <favorite label="favorite">
        <view id="view-id" />
      </favorite>
      ... additional favorites ...
  </favorites>
</tsResponse>
        

Version

Version 1.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400000 Bad request 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.

For more information, see Handling Errors.

Delete Data Source from Favorites

Deletes the specified data source from the user's favorites. If the specified data source is not a favorite, the operation has no effect.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to remove the favorite from.
datasource-id The ID of the data source to remove from the user's favorites.

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) permissions on the data source (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403004 Forbidden favorites access A non-administrator user attempted to delete a data source from a different user's favorites.
404 404000 Site not found The site ID or URL namespace 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 404010 Data source not a favorite The data source ID in the URI exists but is not a favorite of the specified user.
404 404011 Data source not found The data source ID in the URI doesn't correspond to an existing data source
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Flow from Favorites

Deletes the specified flow from the user's favorites. If the specified flow is not a favorite, the operation has no effect.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
user-id The ID of the user to remove the favorite from.
datasource-id The ID of the data source to remove from the user's favorites.

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) permissions on the data source (either explicitly or implicitly).

Response Code

204

Response Body

None

Version

Version 3.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403004 Forbidden favorites access A non-administrator user attempted to delete a data source from a different user's favorites.
404 404000 Site not found The site ID or URL namespace 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 404010 Flow not a favorite The flow ID in the URI exists but is not a favorite of the specified user.
404 404027 Data source not found The flow ID in the URI doesn't correspond to an existing flow.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Project from Favorites

Deletes the specified project from the user's favorites. If the specified project is not a favorite, the operation has no effect.

URI

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

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the project.
user-id The ID of the user to remove the favorite from.
project-id The ID of the project to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a project only from their own favorites.

Response Code

204

Response Body

None

Version

Version 3.1 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403004 Forbidden favorites access A non-administrator user attempted to delete a project from a different user's favorites.
404 404000 Site not found The site ID or URL namespace 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 URI doesn't correspond to an existing project.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.13/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/favorites/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/projects/89a82d78-664f-45a1-8256-d4d2961a070b" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Delete View from Favorites

Deletes the specified view from user's favorites. If the specified view is not a favorite, the operation has no effect.

URI

DELETE /api/api-version/sites/site-id/favorites/user-id/views/view-id

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the view.
user-id The ID of the user to remove the favorite from.
view-id The ID of the view to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can delete a view only from their own favorites.

Response Code

204

Response Body

None

Version

Version 2.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403004 Forbidden Favorites access A non-administrator user attempted to delete a view from a different user's favorites.
404 404000 Site not found The site ID or URL namespace 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 404010 View not a favorite The view ID in the URI exists but is not a favorite of the specified user.
404 404011 View not found The view ID in the URI doesn't correspond to an existing view
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Delete Workbook from Favorites

Deletes a workbook from a user's favorites. If the specified workbook is not a favorite of the specified user, this call has no effect.

URI

DELETE /api/api-version/sites/site-id/favorites/user-id/workbooks/workbook-id

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the user.
user-id The ID of the user to remove the favorite from.
workbook-id The ID of the workbook to remove from the user's favorites.

Request Body

None

Permissions

Tableau Server users who are not server administrators or site administrators can remove a workbook only from their own favorites.

Response Code

204

Response Body

None

Version

Version 2.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403004 Access to Favorites forbidden A non-administrator user attempted to delete a workbook from a different user's favorites.
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 URI doesn't correspond to an existing workbook.
404 404010 Workbook not a favorite The workbook ID in the URI exists but belongs to a different user.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Get Favorites for User

Returns a list of favorite projects, data sources, views, workbooks, and flows for a user.

URI

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

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

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
user-id The ID of the user for which you want to get a list favorites.
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 not server administrators or site administrators can call this method only if they are the user for which they want to get a list of favorites.

Response Code

200

Response Body

<tsResponse version-and-namespace-settings>
  <favorites>
	<favorite label="favorite-label">
	  <view id="view-luid"
		name="view-name"
		contentUrl="content-url"
		createdAt="created-at"
		updatedAt="updated-at"
		viewUrlName="view-url-name">
	      <workbook id="workbook-luid"/>
		  <project id"project-luid"/>
		  <tags />
	  </view>
	</favorite>
	<!--      . . .more favorites. . .      -->
  </favorites>
</tsResponse>

The value of view-url-name is the name of the view in its URL. For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1 in your browser address bar, then the view-url-name would be VIEW_1. Modifying the name (display name) of a view will not impact the view-url-name (path element of the view's URL).

Response when favorite items have been deleted

In the case where an item selected as a favorite has been deleted the reponse body will contain only the label of the favorite.

<tsResponse>
  <favorites>
	<favorite label="favorite-label">
  </favorites>
</tsResponse>
        

Version

Version 2.5 and later. Support for favorite projects added in version 3.1. For more information, see REST API and Resource Versions.

Errors

403 403004 Forbidden Favorites access A non-administrator user called this method but doesn't have permission to view the specified user's favorites.
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.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.13/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/favorites/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
  <favorites>
    <favorite label="Global Economic Indicators">
	  <view id="796c9371-a180-46b7-9970-feffe8573d47"
		name="Overview"
		contentUrl="Superstore/sheets/Overview"
		createdAt="2015-11-09T21:39:59Z"
		updatedAt="2019-08-30T21:05:37Z"
		viewUrlName="Overview" >
		  <workbook id="65e18031-b2f0-4ab6-994b-2c5520b830bb"/>
		  <owner id="abb3e4c1-e650-4704-870a-03fb7615136f"/>
		  <project id="3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"/>
		  <tags/>
	  </view>
	</favorite>
  </favorites>
</tsResponse>

Organize Favorites

Move an item to organize a user's favorites.

URI

PUT /api/api-version/sites/site-id/orderFavorites/user-id

Parameter Values

api-version The version of the API to use, such as 3.13. For more information, see REST API and Resource Versions.
site-id The ID of the site that the user is a member of.
user-id The ID of the user for which you want to get a list favorites.

Request Body

<tsRequest>
   <favoriteOrderings>
	<favoriteOrdering favoriteId="favorite-id" favoriteType="content-type" favoriteIdMoveAfter="favorite-id-after" favoriteTypeMoveAfter="content-type" />
   </favoriteOrderings>
</tsRequest>
          

Attribute Values

favorite-id The ID of the favorite you want to move.
content-type The content type of a favorite. To specify the type, use one of the following values:
  • datasource
  • workbook
  • view
  • project
  • flow
These values are not case sensitive.
favorite-id-after The ID of the favorite that should follow, or come after, the favorite you want to move.

Permissions

Users who are not server administrators or site administrators can call this method only if they are the user for which they want to move favorites.

Response Code

200

Response Body

None

Version

Version 3.8 and later. For more information, see REST API and Resource Versions.

Errors

403 403004 Forbidden Favorites access A non-administrator user called this method but doesn't have permission to view the specified user's favorites.
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 404010 Favorite not found The favorite ID specified doesn't correspond to a user's favorite.

For more information, see Handling Errors.


Thanks for your feedback!