Using the metrics methods of the Tableau REST API you can:

  • List all metrics configured for a site
  • Get the details of a specific metric
  • Get the data of a specific metric as CSV
  • Update the name, containing project, suspended status, and owner of a specific metric
  • Delete a specific metric

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

Delete Metric

Deletes a specified metric from a site.

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.16. 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

Added in Tableau Online June 2022. Currently not available for Tableau Server.

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 Online 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.

Get Metric

Returns the details of the specified metric.

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.16. 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

Added in Tableau Online June 2022. Currently not available for Tableau Server.

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 Online 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>
        

Get Metric Data

Returns the data for the specified metric as comma separated (CSV) format. The maximum number of rows returned is 10,000.

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.16. 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

Added in Tableau Online June 2022. Currently not available for Tableau Server.

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 Online 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 Online 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

List Metrics for Site

Returns the metrics configured for a site.

If the user is not an administrator, the method returns just the metrics for which the user has permissions.

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.16. 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

Added in Tableau Online June 2022. Currently not available for Tableau Server.

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 Online 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.16/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>
        

Update Metric

Updates the owner, project, suspended status, or name of the specified metric.

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.16. 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.16/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>
        


Thanks for your feedback!