Metrics Methods

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

  • List all metrics configured for a site
  • Get the details of a specific metricr
  • 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.11. 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

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

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

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>

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

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

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

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.11/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/metrics" -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!