Tableau REST API Help

URI

DELETE /api/api-version/sites/site-id/metrics/metric-luid

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the metric.
metric-luid	The unique ID of the metric to remove.

Request Body

None

Permissions

Users who are not administrators can delete a metric for which they have explicit or implicit Read (view) and Delete permission.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:metrics:delete

Response Code

204

Response Body

None

Version

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

Errors

HTTP status	error Code	Condition	Details
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404006	Metric not found	The metric ID in the URI doesn't correspond to an existing metric.
405	405000	Invalid request method	Request type was not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics/6561daa3-20e8-407f-ba09-709b178c0b4a" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.

URI

GET /api/api-version/sites/site-id/metrics/metric-luid;

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id	The unique ID of the site that contains the metric.>
metric-luid	The unique ID of the metric.

Request Body

None

Permissions

This method can be called by any user, but those without administrator permissions will only be able to view responses for metrics they own.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:content:read

Response Code

200

Response Body

                <tsResponse>
  <metric id="metric-id"
	name="metric-name"
	description="metric-description"
	webpageUrl="metric-content-url"
	createdAt="datetime-created"
	updatedAt="datetime-updated"
	suspended="suspended-flag">
  	  <project id="project-id"
	    name="project-name"/>
	  <owner id="metric-owner-id"/>
	  <tags>
	    <tag label="tag"/>
	    <!-- ... additional tags ... -->
	  </tags>
	  <underlyingView id="view-id"/>
  </metric>
</tsResponse>
      

Version

Version 3.9 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.
403	403004	Permissions issue	The user does not have permissions to read the specified metric.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404004	Metric not found	The metric ID in the URI doesn't correspond to an existing metric.

Example

curl "http://MY-SERVER/api/3.9/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics/6561daa3-20e8-407f-ba09-709b178c0b4a" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response Body

                    <tsResponse>
  <metric id="6561daa3-20e8-407f-ba09-709b178c0b4a"
    name="my metric name"
    description="Description of my metric."
    webpageUrl="https://MY-SERVER/#/site/site-name/metrics/site-num"
    createdAt="2020-01-02T01:02:03Zd"
    updatedAt="2020-01-02T01:02:03Z"
    suspended="true">
      <project id="32e79edb-6cfd-47dc-ad79-e8ec2fbb1d33"
        name="my project name"/>
      <owner id="32e79edb-6cfd-47dc-ad79-e8ec2fbb1d33"/>
      <tags/>
      <underlyingView id="29dae0cd-1862-4a20-a638-e2c2dfa682d4"/>
  </metric>
</tsResponse>
        

URI

GET /api/api-version/sites/site-luid/metrics/metric-luid/data

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-luid	The LUID of the site that contains the data source to get revisions for.
metric-luid	The LUID of the metric whose data should be returned.

Request Body

None

Permissions

Tableau administrators, and non-administrator and users with Read capability for a metric, will be able to get its data.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:metrics:download

Response Code

200

Response Body

your_timestamp_column_name,your_measure_column_nametimestamp_1,measure_1timestamp_2,measure_1

Version

Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. For more information, see REST API and Resource Versions.

Errors

HTTP status	error Code	Condition	Details
400	40000	Bad request	The LUID of the site or metric was malformed.
401	40100	Not authorized	The authentication token provided in the request header was invalid or has expired.
403	403054	Not authorized	A non-administrator user attempted to get metric data, but does not have sufficient permissions.
404	404000	Site not found	The site LUIID in the URI doesn't correspond to an existing site.
404		Metric not found	The metric LUID in the URI doesn't correspond to an existing data source.
405	405000	Invalid request method	Request type was not GET.
429	405000	Too many requests	The concurrent request limit for the site was exceeded. Retry after a pause.

For more information, see Handling Errors.

Example

Request command line:

curl "http://MY-SERVER/api/3.16/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/metrics/2474164d-8d37-4a4c-abc7-c2070fd25fd5/data" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Response:

Timestamp,Measure
2021-12-31:11:59:57-0800,3
2021-12-31:11:59:58-0800,2
2021-12-31:11:59:59-0800,1

URI

GET /api/api-version/sites/site-id/metrics

GET /api/api-version/sites/site-id/metrics?filter=filter-expression

GET /api/api-version/sites/site-id/metrics?sort=sort-expression

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

GET /api/api-version/sites/site-id/metrics?fields=field-expression

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the metrics.
filter-expression	(Optional) An expression that lets you specify a subset of metrics to return. You can filter on predefined fields such as metric name, or attributes of the associated owner or project. You can include multiple filter expressions. For more information, see Filtering and Sorting.
sort-expression	(Optional) An expression that lets you specify the order in which metric information is returned. If you do not specify a sort expression, the sort order of the information that's returned is undefined. For more information, see Filtering and Sorting.
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.
field-expression	(Optional) An expression that lets you specify the set of available fields to return. You can qualify the return values based upon predefined keywords such as _all_ or _default_, and you can specify individual fields for the metrics or other supported resources. You can include multiple field expressions in a request. For more information, see Using Fields in the REST API.

Note: The filter and sort parameters can be combined with each other and with paging parameters and fields parameters using an ampersand (&).

Request Body

None

Permissions

Users who are not administrators can get only the metrics for which they have implicit or explicit Read (view) permissions.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

                tableau:content:read
            

Response Code

200

Response Body

                    <tsResponse>
  <pagination pageNumber="page-number"
     pageSize="page-size"
     totalAvailable="total-available" />
  <metrics>
    <metric id="metric-id"
		name="name"
		description="metric-description"
		webpageurl="metric-webpageurl"
        createdAt="datetime-created"
	    updatedAt="datetime-updated"
	    suspended="suspended-flag" >
	      <project id="project-id" name="project-name" />
	      <owner id="user-id" />
	      <tags>
	        <tag label="tag"/>
	        ... additional tags ...
	     </tags>
	<underlyingView" id="view-id" />
   </metric>
   ... additional metrics ...
  </metrics>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

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

Errors

HTTP status	error Code	Condition	Details
400	400006	Invalid page number	The page number is not an integer, is less than one, or is greater than the final page number for users at the requested page size.
400	400007	Invalid page size	The page size parameter is not an integer, or is less than one.
403	403014	Page size exceeds upper limit	The page size parameter exceeds the system-wide upper limit of 1000.
403	403018	Read forbidden	A non-administrator user attempted to query metrics for the site, but the caller doesn't have Read permission.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404004	Metrics not found	No metrics are configured for this site.
405	405000	Invalid request method	Request type was not GET.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response body:

                    <tsResponse version-and-namespace-settings>
  <pagination pageNumber="1" pageSize="100" totalAvailable="27"/>
  <metrics>
    <metric id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
		name="my first metric"
        description="Description of my_first_metric."
		webpageUrl="https://MY-SERVER/#/site/site-name/metrics/site-num"
		createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
		suspended="false" >
	      <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
	      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	      <tags/>
		underlyingView="29dae0cd-1862-4a20-a638-e2c2dfa682d4"
    </metric>
    <metric id="29dae0cd-1862-4a20-a638-e2c2dfa682d4a" name="my_second_metric"
		description="Description of my second metric."
		webpageUrl="https://MY-SERVER/#/site/site-name/metrics/site-num"
        createdAt="2014-02-19T10:19:23Z" updatedAt="2015-12-29T013:23:45Z"
		suspended="false" >
		  <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="default"/>
	      <owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
	      <tags>
          <tag label="training" ></tags>
    </metric>
	<!-- ...more metrics ... --:>
  </metrics>
  </tsResponse>
        

URI

PUT /api/api-version/sites/site-id/metrics/metric-luid

Parameter Values

api-version	The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id	The ID of the site that contains the data source.
metric-luid	The unique ID of the data source to update.

Request Body

                    <tsRequest>
  <metric
	description="updated-metric-description"
    name="updated-name"
	suspended="updated-suspended-flag" >
      <project id="updated-project-id"/>
      <owner id="updated-owner-id"/>
  </metric>
</tsRequest>
        

Attribute Values

updated-metric-description	(Optional) The description to use for the updated metric.
updated-metric-name	(Optional) The name to use for the updated metric.
updated-suspended-flag	(Optional) Boolean. If true the metric is suspended. The default is false.
updated-project-id	(Optional) The ID of a project to add the metric to.
updated-owner-id	(Optional) The ID of a user to assign the metric to as owner.

Any combination of the attributes inside the <metric> element is valid. Only the attributes and child elements that are included result in updates to the data source. If no attributes or nested elements are included, no update is made.

If the <project> element is included, the id attribute must be included, and any other attributes of the <project> element are ignored.

If the <owner> element is included, the id attribute must be included, and any other attributes of the owner are ignored.

Permissions

Tableau users who are server or site administrators can change the owner for a metric. Users who are not administrators can move a metric from one project to another if they have permissions to the metric. The user must also have permissions to the current (source) project or are a project leader for the current project, and have Write permission for the destination project.

tableau:metrics:update

Response Code

200

Response Body

                    <tsResponse>
  <metric id="metric-id"
	name="metric-name"
	description="metric-description"
	webpageUrl="webpageUrl-url"
	createdAt="datetime-created"
	updatedAt="datetime-updated"
	suspended="suspended-flag"">
	  <project id="new-project-id" />
	  <owner id="new-owner-id" />
	  <tags>
	    <tag label="tag"/>
	    <!--  ... additional tags ... -->
	  </tags>
	</metric>
</tsResponse>
        

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Version

Version 2.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	400123	Unkown error	The metric could not be updated for an unknown reason.
403	403119	Owner update forbidden	The user does not have administrator permissions to change the owner for the metric.
403	403120	Project update forbidden	The user doesn't have Write permission for the project they are trying to move the metric to.
403	403118	Name update forbidden	The user does not have administrator permissions to change the name for the metric.
404	404000	Site not found	The site ID in the URI doesn't correspond to an existing site.
404	404002	Owner not found	The owner ID in the request body doesn't correspond to an existing owner.
404	404004	Metric not found	The metrice ID in the URI doesn't correspond to an existing metric.
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.
409	409015	Metric name conflict	The metric name in the request already belongs to the specified site. For the purpose of uniqueness checks, metric names are case-insensitive.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.22/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics/6561daa3-20e8-407f-ba09-709b178c0b4a" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-metric.xml

Content of update-metric.xml

                        <tsRequest>
   <metric
    name="New Name"
    description="New Description"
    suspended="true">
	  <project id="49b4cce3-771f-4ee3-a932-5d42fa8c0e9d"/>
	 <owner id="f1539d08-114c-4de9-a830-c9a0674ec026"/>
  </metric>
</tsRequest>
          

Example response body:

                    <tsResponse >
  <metric id="1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d"
    name="my first metric"
    description="Description of my_first_metric."
    webpageUrl="https://MY-SERVER/#/site/site-name/metrics/site-num"
    createdAt="2013-03-30T22:32:35Z" updatedAt="2016-01-13T01:00:02Z"
    suspended="false" >
 	    <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="Tableau Samples"/>
    	<owner id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
   	  <tags/>
      underlyingView="29dae0cd-1862-4a20-a638-e2c2dfa682d4"
  </metric>
</tsResponse>