Metrics Methods - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)
In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
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 - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
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.24 . 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.
Get Metric - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
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.24 . 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>
Get Metric Data - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
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.24 . 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
List Metrics for Site - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
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.24 . 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.24/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 - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
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.24 . 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.24/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>