Tableau REST API OpenAPI Endpoints (latest)

Versions: Tableau Server 2021.1 / Tableau Cloud March 2022 and later

This documentation describes the growing number OpenAPI endpoints being released alongside more than 150 classic REST endpoints that are currently in wide usage in the Tableau community.

There are some differences users of the classic endpoints will recognize when viewing these new endpoints.

Request bodies for these new REST endpoints must be formatted using JSON.
Endpoint URIs may contain a hyphen ('-') instead of an API version number, indicating that the resource is versioned separately from the numbered API release. For more information, see REST API and Resource Versions.

Starting in Tableau Server 2022.1 / Tableau Cloud March 2022, differences between releases will be noted in this reference.To view the previous version of this reference, see Tableau REST API OpenAPI Endpoints (v2021.4).

Analytics Extensions Settings Methods

Enable and configure analytics extensions on sites and, for on premise installations, on servers. With these extensions you can extend Tableau dynamic calculations with languages like R and python, and with other tools and platforms. For more information, see Analytics Extensions API.

When upgrading from a server version less than 2020.2, analytics extensions must be enabled on each site even if external services were enabled on the server being upgraded. Connections for sites must be ported manually.

Using the analytics extensions settings methods you can:

Enable and disable analytics extensions for a Tableau server (on-premise only) or for a site.
Create and manage an extension's connections to the service hosting your custom calculations.

Enable or disable analytics extensions on server

Enables or disables analytics extensions on a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.analyticsextensions.v1.ServerSettings+json

enabled

boolean

Responses

Request samples

Payload

Content type

application/vnd.tableau.analyticsextensions.v1.ServerSettings+json

{"enabled": true
}

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ServerSettings+json

{"enabled": true
}

Get enabled state of analytics extensions on server

Gets the enabled/disabled state of analytics extensions on a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ServerSettings+json

{"enabled": true
}

Get enabled state of analytics extensions on site

Gets the enabled/disabled state of analytics extensions on a site.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.SiteSettings+json

{"enabled": true
}

Update enabled state of analytics extensions on site

Enables or disables analytics extensions on a site.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.analyticsextensions.v1.SiteSettings+json

enabled

boolean

Responses

Request samples

Payload

Content type

application/vnd.tableau.analyticsextensions.v1.SiteSettings+json

{"enabled": true
}

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.SiteSettings+json

{"enabled": true
}

Add analytics extension connection to site

site.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.analyticsextensions.v1.ConnectionItem+json

connection_luid	string
host	string Required. The location of an external service (TabPy, Rserve, EINSTEIN_DISCOVERY, Generic API, or other) that responds to your analytics extension requests. The case sensitive value must be a URI, IPv4 or IPv6 address that is a maximum of 255 Unicode characters. Starting in Tableau Server 2022.1 / Tableau Cloud April 2022, a host address can include path information ('www.example.com/path'), where previous versions supported only the root domain name ('www.example.com').
port	integer <int32> Required. Integer between 1 and 65535.
is_auth_enabled	boolean For Tableau Cloud: The value is always true. For on premise Tableau servers: Optional. Set to true if authentication is enabled on the external service. If true, username and password are required. Default is false.
username	string For Tableau Cloud: A username is always required.
password	string For Tableau Cloud: A password is always required.
is_ssl_enabled	boolean For Tableau Cloud: The value is always true. For on premise Tableau servers: Optional. Set to true if authentication is enabled on the external service. If true, username and password are required. Default is false.
	object (tableau.analyticsextensions.v1.ConnectionBrief)

Responses

Request samples

Payload

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionItem+json

{"connection_luid": "string",
"host": "string",
"port": 0,
"is_auth_enabled": true,
"username": "string",
"password": "string",
"is_ssl_enabled": true,
"connection_brief": {"connection_name": "string",
"connection_type": "UNDEFINED"
}
}

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionMetadataList+json

{"connectionMetadataList": [{"connection_luid": "string",
"connection_brief": {"connection_name": "string",
"connection_type": "UNDEFINED"
}
}
]
}

List analytics extension connections on site

Lists a site's analytics extension connections for external services.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionMetadataList+json

{"connectionMetadataList": [{"connection_luid": "string",
"connection_brief": {"connection_name": "string",
"connection_type": "UNDEFINED"
}
}
]
}

Delete analytics extension connection from site

Deletes a specific analytics extension connection for an external service from a site.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: Can only be called by users with site or server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

connection_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Get analytics extension details

Get the details of a specified analytics extension connection to an external service.

Version: Available in API 3.11 (Tableau Cloud March 2021/ Server 2021.1) and later. Version Overview

Permissions: Can only be called by users with site or server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

connection_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionItem+json

{"connection_luid": "string",
"host": "string",
"port": 0,
"is_auth_enabled": true,
"username": "string",
"password": "string",
"is_ssl_enabled": true,
"connection_brief": {"connection_name": "string",
"connection_type": "UNDEFINED"
}
}

Update analytics extension connection of site

Updates the details of specified analytics extension connection for an external service to a site.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: Can only be called by users with site or server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

connection_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.analyticsextensions.v1.ConnectionItem+json

connection_luid	string
host	string Required. The location of an external service (TabPy, Rserve, EINSTEIN_DISCOVERY, Generic API, or other) that responds to your analytics extension requests. The case sensitive value must be a URI, IPv4 or IPv6 address that is a maximum of 255 Unicode characters. Starting in Tableau Server 2022.1 / Tableau Cloud April 2022, a host address can include path information ('www.example.com/path'), where previous versions supported only the root domain name ('www.example.com').
port	integer <int32> Required. Integer between 1 and 65535.
is_auth_enabled	boolean For Tableau Cloud: The value is always true. For on premise Tableau servers: Optional. Set to true if authentication is enabled on the external service. If true, username and password are required. Default is false.
username	string For Tableau Cloud: A username is always required.
password	string For Tableau Cloud: A password is always required.
is_ssl_enabled	boolean For Tableau Cloud: The value is always true. For on premise Tableau servers: Optional. Set to true if authentication is enabled on the external service. If true, username and password are required. Default is false.
	object (tableau.analyticsextensions.v1.ConnectionBrief)

Responses

Request samples

Payload

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionItem+json

{"connection_luid": "string",
"host": "string",
"port": 0,
"is_auth_enabled": true,
"username": "string",
"password": "string",
"is_ssl_enabled": true,
"connection_brief": {"connection_name": "string",
"connection_type": "UNDEFINED"
}
}

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionItem+json

{"connection_luid": "string",
"host": "string",
"port": 0,
"is_auth_enabled": true,
"username": "string",
"password": "string",
"is_ssl_enabled": true,
"connection_brief": {"connection_name": "string",
"connection_type": "UNDEFINED"
}
}

List analytics extension connections of workbook

Lists basic details of each analytics extension connection available for a specified workbook, including connection type and name.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can be called by users that have permissions to the specified workbook. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

workbook_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionMetadataList+json

{"connectionMetadataList": [{"connection_luid": "string",
"connection_brief": {"connection_name": "string",
"connection_type": "UNDEFINED"
}
}
]
}

Get current analytics extension for workbook

Gets basic details, including connection type and name, of the analytics extension connection to an external service that the specified workbook is currently using.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can be called by users that have permissions to the specified workbook. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

workbook_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionMetadataList+json

{"connectionMetadataList": [{"connection_luid": "string",
"connection_brief": {"connection_name": "string",
"connection_type": "UNDEFINED"
}
}
]
}

Remove current analytics extension connection for workbook

Remove the currently used analytics extension connection to an external service from the specified workbook. The connection remains configured, and is available for further usage by the workbook.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can be called by users that have permissions to the specified workbook. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

workbook_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Update analytics extension for workbook

Updates the analytics extension connection to external service currently used by a workbook.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can be called by users that have permissions to the specified workbook. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

workbook_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.analyticsextensions.v1.ConnectionMapping+json

workbook_luid	string
connection_luid	string

Responses

Request samples

Payload

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionMapping+json

{"workbook_luid": "string",
"connection_luid": "string"
}

Response samples

Content type

application/vnd.tableau.analyticsextensions.v1.ConnectionMetadataList+json

{"workbook_luid": "string",
"connection_luid": "string"
}

Ask Data Lens 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.1. 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 How Tableau GPT and Tableau Pulse are reimagining the data experience.

Ask data lenses enable you to refine the way a user's natural language query is interpreted, based on the specific audience they belong to.

For instance, you might make one lens for medical staff at a hospital, and another for administrative staff. A lens allows you to define synonyms to associate key words with common terms used for them. For instance, "SF" for "San Francisco", or "Rx" for "prescription". You can also configure recommended visualizations for each lens.

Introduced: Tableau Cloud June 2022. Not currently available for Tableau Server.

Using the Tableau REST API, you can:
Create a lens and configure its properties

Delete a lens

Import an existing lens

Get a list of lenses on a site or the details of a specified lens

Create ask data lens - 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.1. 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 How Tableau GPT and Tableau Pulse are reimagining the data experience.

Create an ask data lens.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can be called by users who have Create permissions for lenses on the site. Permissions Overview

License: No additional license required.

Access Scope: 'tableau:lenses:create'
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.nlp.lens.publicrest.v1.CreateLensRequest+json

name	string Required. Name of the lens . Up to 300 characters
datasource_id	string Required. Luid of the datasource to which the lens is associated to
project_id	string Required. Luid of the project in which lens should be created.
description	string Optional. Description of the lens. 4000 characters maximum
is_feedback_enabled	boolean Required. Indicates if feedback to lens author setting is enabled.
	Array of objects (tableau.nlp.lens.publicrest.v1.FieldDetail) Optional. The fields of the lens. If not specified, a lens with all the qualifying fields from the data source will be created. A lens field contains synonyms used for natural language query, to map words that might be used to mean the same thing as the name of fields or the values fields might have.

Responses

Request samples

Payload

Content type

application/vnd.tableau.nlp.lens.publicrest.v1.CreateLensRequest+json

{"name": "string",
"datasource_id": "string",
"project_id": "string",
"description": "string",
"is_feedback_enabled": true,
"fields": [{"graph_id": "string",
"custom_label": "string",
"custom_description": "string",
"field_synonyms": ["string"
],
"value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
]
}
]
}

Response samples

201
400
401
500
503

Content type

application/vnd.tableau.nlp.lens.publicrest.v1.CreateLensResponse+json

{"lens": {"id": "string",
"name": "string",
"site_id": "string",
"datasource_id": "string",
"project_id": "string",
"owner_id": "string",
"description": "string",
"repository_url": "string",
"is_feedback_enabled": true,
"fields": [{"graph_id": "string",
"custom_label": "string",
"custom_description": "string",
"field_synonyms": ["string"
],
"inherited_field_synonyms": ["string"
],
"value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
],
"inherited_value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
]
}
],
"recommended_visualization_groups": [{"name": "string",
"description": "string",
"recommended_visualizations": [{"expression": "string",
"interpretation": "string",
"colloquial_alias": "string"
}
]
}
]
}
}

List ask data lenses in 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.1. 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 How Tableau GPT and Tableau Pulse are reimagining the data experience.

Returns a list of ask data lenses in a site.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can be called by any user. Responses will include only the lenses to the user has access to. Permissions Overview

License: No additional license required.

Access Scope: 'tableau:lenses:read'
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.nlp.lens.publicrest.v1.ListLensesResponse+json

{"lenses": [{"id": "string",
"name": "string",
"site_id": "string",
"datasource_id": "string",
"project_id": "string",
"owner_id": "string",
"description": "string",
"repository_url": "string"
}
]
}

Import ask data lens - 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.1. 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 How Tableau GPT and Tableau Pulse are reimagining the data experience.

Import an existing ask data lens on a server to a site, and optionally transform the metadata of the lens in the process.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can only be called by server administrators or site administrators. Permissions Overview

License: No additional license required.

Access Scope: 'tableau:lenses:create'
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

The request and response bodies for a lens import each have two parts: the first describes the attributes of the lens being imported, and the second describes transformations, which are changes to the lens metadata, to apply during import.

Use the entire response object from a request to the Get ask data lens method in your import request body.

Lens attributes that can optionally be transformed include name, data source, project, and owner. The original metadata of a lens is replaced by the transformation metadata in the new project the lens is imported to. While 'lens_transformation' is optional in an import request, a transformation definition will be needed in most cases.

Example transformation use cases

To publish a lens to a new site with modified metadata, sign in to the new site and include the following in your request: '' "lens_transformations": { "datasource_id": "", "project_id": "", "owner_id": "" "name": "", "description": "", } ''
To publish a lens to a different project in the same site, while signed in to the site, use: '' "lens_transformations": { "project_id": "new project id", } ''

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.nlp.lens.publicrest.v1.ImportLensRequest+json

	object (tableau.nlp.lens.publicrest.v1.Lens) Details of the lens to be imported.
	object (tableau.nlp.lens.publicrest.v1.LensTransformation) Optional. The details of transformation to perform on the lens during import.

Responses

Request samples

Payload

Content type

application/vnd.tableau.nlp.lens.publicrest.v1.ImportLensRequest+json

{"lens": {"id": "string",
"name": "string",
"site_id": "string",
"datasource_id": "string",
"project_id": "string",
"owner_id": "string",
"description": "string",
"repository_url": "string",
"is_feedback_enabled": true,
"fields": [{"graph_id": "string",
"custom_label": "string",
"custom_description": "string",
"field_synonyms": ["string"
],
"inherited_field_synonyms": ["string"
],
"value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
],
"inherited_value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
]
}
],
"recommended_visualization_groups": [{"name": "string",
"description": "string",
"recommended_visualizations": [{"expression": "string",
"interpretation": "string",
"colloquial_alias": "string"
}
]
}
]
},
"lens_transformations": {"name": "string",
"description": "string",
"datasource_id": "string",
"project_id": "string",
"owner_id": "string"
}
}

Response samples

Content type

application/vnd.tableau.nlp.lens.publicrest.v1.ImportLensResponse+json

{"lens": {"id": "string",
"name": "string",
"site_id": "string",
"datasource_id": "string",
"project_id": "string",
"owner_id": "string",
"description": "string",
"repository_url": "string",
"is_feedback_enabled": true,
"fields": [{"graph_id": "string",
"custom_label": "string",
"custom_description": "string",
"field_synonyms": ["string"
],
"inherited_field_synonyms": ["string"
],
"value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
],
"inherited_value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
]
}
],
"recommended_visualization_groups": [{"name": "string",
"description": "string",
"recommended_visualizations": [{"expression": "string",
"interpretation": "string",
"colloquial_alias": "string"
}
]
}
]
}
}

Delete ask data lens - 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.1. 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 How Tableau GPT and Tableau Pulse are reimagining the data experience.

Delete an ask data lens.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can be called by users with administrator and lens owner permissions. Permissions Overview

License: No additional license required.

Access Scope: 'tableau:lenses:delete'
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

lens_id

required

string

The LUID of the lens to be deleted.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.nlp.lens.publicrest.v1.GetLensResponse+json

{"lens": {"id": "string",
"name": "string",
"site_id": "string",
"datasource_id": "string",
"project_id": "string",
"owner_id": "string",
"description": "string",
"repository_url": "string",
"is_feedback_enabled": true,
"fields": [{"graph_id": "string",
"custom_label": "string",
"custom_description": "string",
"field_synonyms": ["string"
],
"inherited_field_synonyms": ["string"
],
"value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
],
"inherited_value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
]
}
],
"recommended_visualization_groups": [{"name": "string",
"description": "string",
"recommended_visualizations": [{"expression": "string",
"interpretation": "string",
"colloquial_alias": "string"
}
]
}
]
}
}

Get ask data lens - 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.1. 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 How Tableau GPT and Tableau Pulse are reimagining the data experience.

Get the details of the specified ask data lens.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: This method can be called by users who have Read access to the lens. Permissions Overview

License: No additional license required.

Access Scope: 'tableau:lenses:read'
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

lens_id

required

string

The LUID of the lens.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.nlp.lens.publicrest.v1.GetLensResponse+json

{"lens": {"id": "string",
"name": "string",
"site_id": "string",
"datasource_id": "string",
"project_id": "string",
"owner_id": "string",
"description": "string",
"repository_url": "string",
"is_feedback_enabled": true,
"fields": [{"graph_id": "string",
"custom_label": "string",
"custom_description": "string",
"field_synonyms": ["string"
],
"inherited_field_synonyms": ["string"
],
"value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
],
"inherited_value_synonyms": [{"value": "string",
"synonyms": ["string"
]
}
]
}
],
"recommended_visualization_groups": [{"name": "string",
"description": "string",
"recommended_visualizations": [{"expression": "string",
"interpretation": "string",
"colloquial_alias": "string"
}
]
}
]
}
}

Content Exploration Methods

Content exploration methods enable you to view:

Search Results: Explore your Tableau content based on relevance to an provided term and filter expression.

Usage Statistics: Get the count of the number of times a user has directly or indirectly accessed a specified content item, or a batch of content items. Statistics are available for workbooks, views, data sources, flows and other Tableau resources. The response contains counts for a variety of time periods, ranging from two weeks up to the resource's lifetime.

Suggestions: Get suggestions for autocompletion as a user types, based on matches of their input. Searches across all supported content types for objects relevant to the specified term.

Get batch content usage statistics

Gets usage statistics for multiple content items. The batch of can include multiple content types.

Version: Available in API 3.17 ( Tableau Cloud December 2022) and later. Not available for Tableau Server. Version Overview

Permissions: Tableau administrators can get statistics for all content they administer. Other users can get statistics for any content they own or have at least Read permissions for. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.usagestats.v1.BatchGetUsageRequest+json

Array of objects (tableau.usagestats.v1.ContentItemId)

Responses

Request samples

Payload

Content type

application/vnd.tableau.usagestats.v1.BatchGetUsageRequest+json

{"content_items": [{"luid": "string",
"type": "string"
}
]
}

Response samples

Content type

application/vnd.tableau.usagestats.v1.ContentItemUsageStatsList+json

{"content_items": [{"content": {"luid": "string",
"type": "string"
},
"usage": {"hitsTotal": 0,
"hitsLastTwoWeeksTotal": 0,
"hitsLastOneMonthTotal": 0,
"hitsLastThreeMonthsTotal": 0,
"hitsLastTwelveMonthsTotal": 0
}
}
],
"errors": [{"httpErrorCode": 0,
"message": "string"
}
]
}

Get usage statistics for content item

Gets the usage statistics for a Tableau content item, specified by LUID and content type, such as workbook, datasource, or flow.

Version: Available in API 3.17 ( Tableau Cloud December 2022) and later. Not available for Tableau Server. Version Overview

Permissions: Tableau administrators can get statistics for all content they administer. Other users can get statistics for any content they own or have at least Read permissions for. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

type required	string The content type of the kind of resource being specified, for instance: 'workbooks', 'flows', and 'datasources'.
luid required	string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.usagestats.v1.UsageStats+json

{"hitsTotal": 0,
"hitsLastTwoWeeksTotal": 0,
"hitsLastOneMonthTotal": 0,
"hitsLastThreeMonthsTotal": 0,
"hitsLastTwelveMonthsTotal": 0
}

Get content search results

Searches across all supported content types for objects relevant to the search expression specified in the querystring of the request URI.

Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview

Permissions: Search results will be limited to those objects that the user has permissions to access. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

For example, 'MY_SERVER/api/-/search?terms=productID' could return the Sales workbook that contains a data field named 'productID' as well as Superstore database containing a table with a column named 'productID'.

Query parameters can be combined to refine your search. For instance, the request for a search on the term "sales", for workbooks created in 2021 or later, sorted by the number of times the content has been viewed since its creation, with smallest number of views first, would look like:

'/search?terms=sales&filter=type:eq:workbook&modifiedTime:gte:2021&sort=hitsTotal:asc'

Content types returned can include:

'lens'
'datasource'
'virtualconnection'
'collection'
'project'
'flow'
'datarole'

'table'
'database'
'metric'
'view'
'workbook'
'simulation'

query Parameters

terms	string (Optional) One or more terms the search uses as the basis for which items are relevant to return. The items may be of any supported content type. The relevance may be assessed based on any element of a given item. If no terms are supplied, then results will be based filtering and page size limits.
page	integer <int64> (Optional) The number of the page in the list response pages to return. Maximum number of items returned is 10,000
limit	integer <int32> (Optional) The number of items to return on each response page. The default is 10.
order_by	string Enum: "hitsTotal" "hitsSmallSpanTotal" "hitsMediumSpanTotal" "hitsLargeSpanTotal" "downstreamWorkbookCount" (Optional) The sorting method for items returned, based on the popularity of the item. You can sort based on: 'hitsTotal' - The number of times a content item has been viewed since it was created. 'hitsSmallSpanTotal' The number of times viewed in the last month. 'hitsMediumSpanTotal' The number of times viewed in the last three months. 'hitsLargeSpanTotal' The number of times viewed in the last twelve months. 'downstreamWorkbookCount' The number workbooks in a given project. This value is only returned when the request 'filter' expression is '=type:eq:table' or '=type:eq:database'. Append ':asc' or ':desc' to determine sort direction. The default is 'asc'. Your search expression can have more than one comma separated 'order_by' element. If there is a tie between two items for the first 'order_by' expression, then sort order between the two items will be determined by the second 'order_by' expression. The following expression sorts items from the fewest views since creation and, in case of a tie, by the one that has the most recent views. '?order_by=hitsTotal:asc,hitsSmallSpanTotal:desc'
filter	string (Optional) An expression to filter the response using one of the following parameters, or a combination of expressions separated by a comma. 'type' The content type, using the 'eq' or 'in' operator in expressions like: '?filter=type:eq:workbook' '?filter=type:in:[workbook,datasource]' Note: The 'in' operator is available in API 3.17 (Tableau Cloud October 2022 / Server 2022.3) and later. or: 'ownerId' Resource owner ID or last modified time, using 'eq', 'lte', 'gte', 'gt', or 'in' operator in an expression like: 'filter=modifiedTime:gte:2022-01-11T08:00:00.000Z' or: 'modifiedTime' Resource owner ID or last modified time, using 'eq', 'lte', 'gte', 'gt', or 'in' operator in an expression like: `'filter=ownerId:in:[akhil,fred,alice]'` For more information about filter expressions, see Filtering and Sorting in the Tableau REST API.

Responses

Response samples

Content type

application/vnd.tableau.search-results.v2+json

{"next": "string",
"prev": "string",
"pageIndex": 0,
"startIndex": 0,
"total": 0,
"limit": 0,
"items": [{"uri": "string",
"content": {"property1": { },
"property2": { }
}
}
]
}

Get Content Suggestions

Returns a specified number of suggestions for auto-completion of user input as they type. You can specify content types of suggestions and prioritize recently viewed content.

Version: Available in API 3.19 ( Tableau Cloud March 2023 / Server 2023.1) and later. Version Overview

Permissions: Suggestions will be limited to those objects that the user has permissions to access. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

query Parameters

terms required	string The term that is matched to find suggestions.
limit	integer <int32> The number of suggestions to return. The default is 10.
recentsLuids	string A comma separated list of luids that will be prioritized in scoring of content items matched to suggest.
filter	string A filter to restrict suggestions to specified content types. The supported operators are: 'in' and 'eq'. For instance, the parameter: 'filter:in:workbooks,datasources' would limit suggestions returned to only those for workbooks and data sources.

Responses

Response samples

Content type

application/vnd.tableau.search-results.v2+json

{"terms": "string",
"filter": "string",
"sort": "string",
"hits": {"next": "string",
"prev": "string",
"pageIndex": 0,
"startIndex": 0,
"total": 0,
"limit": 0,
"items": [{"uri": "string",
"content": {"property1": { },
"property2": { }
}
}
]
}
}

Dashboard Extensions Settings Methods - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Enable and configure security for dashboard extensions on sites and, for on premise installations, on servers. With these extensions you can add custom features to a dashboard using JavaScript.

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

List the settings for extensions of a server or site
Enable or disable extensions or sandboxed extensions for a server or site
List, get, create, and delete entries in server blocked extensions list
List, get, create, update, and delete entries in server allowed (safe) extensions list

This functionality relates to the UI elements and concepts described at Manage Dashboard Settings.

List settings for dashboard extensions on server - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Lists the dashboard extension settings of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.ServerSettings+json

{"block_list_items": [{"url": "string",
"block_list_item_luid": "string"
}
],
"extensions_enabled": true
}

Update dashboard extensions settings of server - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Updates the settings for dashboard extensions of a server

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.extensions.dashboard.v1.ServerSettings+json

	Array of objects (tableau.extensions.dashboard.v1.BlockListItem)
extensions_enabled	boolean Specifies whether sandboxed extensions are allowed to run on the site.

Responses

Request samples

Payload

Content type

application/vnd.tableau.extensions.dashboard.v1.ServerSettings+json

{"block_list_items": [{"url": "string",
"block_list_item_luid": "string"
}
],
"extensions_enabled": true
}

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.ServerSettings+json

{"block_list_items": [{"url": "string",
"block_list_item_luid": "string"
}
],
"extensions_enabled": true
}

Block dashboard extension on server - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Adds a dashboard extension to the block list of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.extensions.dashboard.v1.BlockListItem+json

url	string Location of the dashboard extension to be blocked from a site.
block_list_item_luid	string

Responses

Request samples

Payload

Content type

application/vnd.tableau.extensions.dashboard.v1.BlockListItem+json

{"url": "string",
"block_list_item_luid": "string"
}

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.BlockListItem+json

{"url": "string",
"block_list_item_luid": "string"
}

List blocked dashboard extensions on server - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Lists the dashboard extensions on the blocked list of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.BlockListItems+json

{"block_list_items": [{"url": "string",
"block_list_item_luid": "string"
}
]
}

Get blocked dashboard extension on server - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Gets the details of a specific dashboard extension on the blocked list of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

block_list_item_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.BlockListItem+json

{"url": "string",
"block_list_item_luid": "string"
}

Unblock dashboard extension on server - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Deletes a specific extension from the block list of a server.

Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

block_list_item_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

List dashboard extension settings of site - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Lists the dashboard extension settings of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.SiteSettings+json

{"extensions_enabled": true,
"allow_sandboxed": true,
"safe_list_items": [{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}
]
}

Update dashboard extension settings of site - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Updates the settings for dashboard extensions for the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.extensions.dashboard.v1.SiteSettings+json

extensions_enabled	boolean Specifies whether extensions are allowed to run on the site.
allow_sandboxed	boolean Specifies whether sandboxed extensions are allowed to run on the site.
	Array of objects (tableau.extensions.dashboard.v1.SafeListItem)

Responses

Request samples

Payload

Content type

application/vnd.tableau.extensions.dashboard.v1.SiteSettings+json

{"extensions_enabled": true,
"allow_sandboxed": true,
"safe_list_items": [{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}
]
}

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.SiteSettings+json

{"extensions_enabled": true,
"allow_sandboxed": true,
"safe_list_items": [{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}
]
}

Allow dashboard extension on site - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Adds a dashboard extension to the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.extensions.dashboard.v1.SafeListItem+json

safe_list_item_luid	string
url	string Location (URL) of the dashboard extension to be allowed on a site.
allow_full_data	boolean When true, the extension has access to underlying data of a workbook. This setting is only effective when the extension is on the site safe list. Default is false.
prompt_needed	boolean When true, the user will be prompted to grant an extension access to the underlying data of a workbook. This setting is only effective when the extension is on the site safe list. Default is false.

Responses

Request samples

Payload

Content type

application/vnd.tableau.extensions.dashboard.v1.SafeListItem+json

{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.SafeListItem+json

{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}

List allowed dashboard extensions on site - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Lists the dashboard extensions on the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.SafeListItems+json

{"safe_list_items": [{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}
]
}

Disallow dashboard extension on site - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Deletes a specific dashboard extension from the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: Can only be called by users with site or server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

safe_list_item_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Get allowed dashboard extension on site - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Gets the details of a specific dashboard extension on the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: Can only be called by users with site or server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

safe_list_item_luid

required

string

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.SafeListItem+json

{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}

Update settings for allowed dashboard extension on site - Retired in API 3.21

Retired in API 3.21 (Cloud October 2023 / Server 2023.3)

In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.

Updates the settings of a specific dashboard extension in the safe list of the site you are signed into.

Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview

Permissions: Can only be called by users with site or server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Cloud | Server-Windows | Server-Linux

path Parameters

safe_list_item_luid

required

any

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.extensions.dashboard.v1.SafeListItem+json

safe_list_item_luid	string
url	string Location (URL) of the dashboard extension to be allowed on a site.
allow_full_data	boolean When true, the extension has access to underlying data of a workbook. This setting is only effective when the extension is on the site safe list. Default is false.
prompt_needed	boolean When true, the user will be prompted to grant an extension access to the underlying data of a workbook. This setting is only effective when the extension is on the site safe list. Default is false.

Responses

Request samples

Payload

Content type

application/vnd.tableau.extensions.dashboard.v1.SafeListItem+json

{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}

Response samples

Content type

application/vnd.tableau.extensions.dashboard.v1.SafeListItem+json

{"safe_list_item_luid": "string",
"url": "string",
"allow_full_data": true,
"prompt_needed": true
}

Identity Pools Methods

Identity pools are an identity management tool that uses provisioning and authentication information to enable user access to Tableau Server. Identity pools enable a more centralized and flexible identity management workflow. For more information, see Provision and Authenticate Users Using Identity Pools in the Tableau Server Help.

The identity pools methods allow you to:

Provision users by creating a new local identity store instance. Note: Skip this step to use an existing local identity store or the external identity store you configured in TSM during Tableau Server setup.
Set up an authentication method to authenticate your users to Tableau Server using OpenID Connect (OIDC).
Create an identity pool that uses the identity store and authentication method you configured.
Add users to an identity pool using the Add User to Identity Pool endpoint using the Tableau REST API.

Refer to the Tableau Server Help for testing, managing, and troubleshooting identity pools.

Note: Identity pools do not replace the user provisioning and authentication configurations you made during Tableau Server setup. The purpose of identity pools is to complement and support additional user provisioning and authentication options you might need in your organization.

Prerequisites

Before getting started with identity pools, the following requirements must be met:

Integration with an OIDC identity provider (IdP), such as Okta, is already configured
You are running Tableau Server 2023.1 or later
You have performed the identity migration if you are running Tableau Server after upgrading from version 2021.4 or earlier
You have performed the steps described at Step 1: Configure Tableau Server and establish a session in the Tableau Server Help

You can use the Identity Pools Postman collection in the Salesforce Developer's Postman workspace to learn about, develop, and test the methods described.

This functionality relates to the concepts and procedures described in the Set Up and Manage Identity Pools topic in the Tableau Server Help.

Create Authentication Configuration

Create an instance of OpenID Connect (OIDC) authentication.

For more information, see Step 3: Set up authentication in the Tableau Server Help.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.authn.v1.RegisterAuthConfigurationRequest+json

auth_type	string Value: "OIDC" Required. Authentication type.
iframed_idp_enabled	boolean Allows the identity provider (IdP) to authenticate inside of an iFrame. The IdP must disable clickjack protection to allow iFrame presentation. Default value is 'false'.
	object (tableau.authn.v1.OidcConfig)

Responses

Request samples

Payload

Content type

application/vnd.tableau.authn.v1.RegisterAuthConfigurationRequest+json

{"auth_type": "OIDC",
"iframed_idp_enabled": true,
"oidc": {"client_id": "string",
"client_secret": "string",
"config_url": "string",
"custom_scope": "string",
"id_claim": "string",
"username_claim": "string",
"client_authentication": "string",
"essential_acr_values": "string",
"voluntary_acr_values": "string",
"prompt": "string",
"connection_timeout": 0,
"read_timeout": 0,
"ignore_domain": true,
"ignore_jwk": true
}
}

Response samples

Content type

application/vnd.tableau.authn.v1.RegisterAuthConfigurationResponse+json

{"auth_configuration": {"id": 0,
"created_at": "string",
"updated_at": "string",
"auth_type": "OIDC",
"iframed_idp_enabled": true,
"oidc": {"client_id": "string",
"client_secret": "string",
"config_url": "string",
"custom_scope": "string",
"id_claim": "string",
"username_claim": "string",
"client_authentication": "string",
"essential_acr_values": "string",
"voluntary_acr_values": "string",
"prompt": "string",
"connection_timeout": 0,
"read_timeout": 0,
"ignore_domain": true,
"ignore_jwk": true
}
}
}

List Authentication Configurations

List information about all authentication instances.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.authn.v1.ListAuthConfigurationsResponse+json

{"instances": [{"id": 0,
"created_at": "string",
"updated_at": "string",
"auth_type": "OIDC",
"iframed_idp_enabled": true,
"oidc": {"client_id": "string",
"client_secret": "string",
"config_url": "string",
"custom_scope": "string",
"id_claim": "string",
"username_claim": "string",
"client_authentication": "string",
"essential_acr_values": "string",
"voluntary_acr_values": "string",
"prompt": "string",
"connection_timeout": 0,
"read_timeout": 0,
"ignore_domain": true,
"ignore_jwk": true
}
}
]
}

Delete Authentication Configuration

Delete an authentication instance.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

path Parameters

id

required

integer <int32>

Required. Authentication instance ID.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Update Authentication Configuration

Update an authentication instance.

Note: The request body must specify all the required and desired parameters, not jus the parameters you want to update.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

path Parameters

id

required

integer <int32>

Required. Authentication instance ID.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.authn.v1.UpdateAuthConfigurationRequest+json

id	integer <int32> Required. Authentication instance ID.
auth_type	string Value: "OIDC" Required. Authentication type.
iframed_idp_enabled	boolean Allows the identity provider (IdP) to authenticate inside of an iFrame. The IdP must disable clickjack protection to allow iFrame presentation. Default value is 'false'.
	object (tableau.authn.v1.OidcConfig)

Responses

Request samples

Payload

Content type

application/vnd.tableau.authn.v1.UpdateAuthConfigurationRequest+json

{"id": 0,
"auth_type": "OIDC",
"iframed_idp_enabled": true,
"oidc": {"client_id": "string",
"client_secret": "string",
"config_url": "string",
"custom_scope": "string",
"id_claim": "string",
"username_claim": "string",
"client_authentication": "string",
"essential_acr_values": "string",
"voluntary_acr_values": "string",
"prompt": "string",
"connection_timeout": 0,
"read_timeout": 0,
"ignore_domain": true,
"ignore_jwk": true
}
}

Response samples

Content type

application/vnd.tableau.authn.v1.UpdateAuthConfigurationResponse+json

{"auth_configuration": {"id": 0,
"created_at": "string",
"updated_at": "string",
"auth_type": "OIDC",
"iframed_idp_enabled": true,
"oidc": {"client_id": "string",
"client_secret": "string",
"config_url": "string",
"custom_scope": "string",
"id_claim": "string",
"username_claim": "string",
"client_authentication": "string",
"essential_acr_values": "string",
"voluntary_acr_values": "string",
"prompt": "string",
"connection_timeout": 0,
"read_timeout": 0,
"ignore_domain": true,
"ignore_jwk": true
}
}
}

Create Identity Pool

Create an identity pool.

For more information, see Step 4: Create an identity pool in the Tableau Server Help.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.authn.v1.RegisterIdentityPoolRequest+json

name	string Required. Identity pool name. Must be unique. This name is visible on the Tableau Server landing page when users sign in.
identity_store_instance	integer <int32> Required. ID of the identity store instance to configure with this identity pool.
auth_type_instance	integer <int32> Required. ID of the authentication instance to configure with this identity pool.
is_enabled	boolean Identity pool is enabled by default.
description	string Identity pool description displayed to users when they sign in.

Responses

Request samples

Payload

Content type

application/vnd.tableau.authn.v1.RegisterIdentityPoolRequest+json

{"name": "string",
"identity_store_instance": 0,
"auth_type_instance": 0,
"is_enabled": true,
"description": "string"
}

Response samples

Content type

application/vnd.tableau.authn.v1.RegisterIdentityPoolResponse+json

{"pool": {"identity_pool_id": {"value": "string"
},
"identity_pool_name": "string",
"identity_store_instance_id": 0,
"auth_type_instance_id": 0,
"is_enabled": true,
"created_at": "string",
"updated_at": "string",
"description": "string",
"identity_store_type": "LOCAL",
"auth_type": "OIDC"
}
}

List Identity Pools

List all identity pools.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

Responses

Response samples

Content type

application/vnd.tableau.authn.v1.ListIdentityPoolsResponse+json

{"pools": [{"identity_pool_id": {"value": "string"
},
"identity_pool_name": "string",
"identity_store_instance_id": 0,
"auth_type_instance_id": 0,
"is_enabled": true,
"created_at": "string",
"updated_at": "string",
"description": "string",
"identity_store_type": "LOCAL",
"auth_type": "OIDC"
}
]
}

Delete Identity Pool

Delete an identity pool.

Important: In Tableau Server, move users to another identity pool before deleting an identity pool. Users will no longer be able to sign in to Tableau Server unless they are a member of an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

path Parameters

uuid

required

string

Required. Identity pool ID.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Get Identity Pool

Get information about an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

path Parameters

uuid

required

string

Required. Identity pool ID.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.authn.v1.FindIdentityPoolByUuidResponse+json

{"pool": {"identity_pool_id": {"value": "string"
},
"identity_pool_name": "string",
"identity_store_instance_id": 0,
"auth_type_instance_id": 0,
"is_enabled": true,
"created_at": "string",
"updated_at": "string",
"description": "string",
"identity_store_type": "LOCAL",
"auth_type": "OIDC"
}
}

Update Identity Pool

Update information about an identity pool.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

path Parameters

uuid

required

string

Required. Identity pool ID.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.authn.v1.UpdateIdentityPoolRequest+json

uuid	string Required. Identity pool ID.
name	string Identity pool name. Must be unique. This name is visible on the Tableau Server landing page when users sign in.
is_enabled	boolean Identity pool is enabled by default.
description	string Identity pool description displayed to users when they sign in.

Responses

Request samples

Payload

Content type

application/vnd.tableau.authn.v1.UpdateIdentityPoolRequest+json

{"uuid": "string",
"name": "string",
"is_enabled": true,
"description": "string"
}

Response samples

Content type

application/vnd.tableau.authn.v1.UpdateIdentityPoolResponse+json

{"pool": {"identity_pool_id": {"value": "string"
},
"identity_pool_name": "string",
"identity_store_instance_id": 0,
"auth_type_instance_id": 0,
"is_enabled": true,
"created_at": "string",
"updated_at": "string",
"description": "string",
"identity_store_type": "LOCAL",
"auth_type": "OIDC"
}
}

Configure Identity Store

Configure a new local identity store to provision users.

For more information, see Step 2: Set up an identity store in the Tableau Server Help.

Note: This identity store is in addition to the identity store you configured during Tableau Server setup.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.authn.v1.RegisterIdentityStoreRequest+json

type	string Value: "0" Required. Identity store type used to provision users. Use 0 to configure a new local identity store. Note: Configuring a new identity store of type Active Directory or LDAP is not supported.
name	string Required. Identity store name. Must be unique.
display_name	string Identity store display name.

Responses

Request samples

Payload

Content type

application/vnd.tableau.authn.v1.RegisterIdentityStoreRequest+json

{"type": "0",
"name": "string",
"display_name": "string"
}

Response samples

Content type

application/vnd.tableau.authn.v1.RegisterIdentityStoreResponse+json

{"store_instance": {"id": 0,
"type": "LOCAL",
"name": "string",
"display_name": "string",
"created_at": "string",
"updated_at": "string"
}
}

List Identity Stores

List information about all identity store instances used to provision users.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.authn.v1.ListIdentityStoresResponse+json

{"instances": [{"id": 0,
"type": "LOCAL",
"name": "string",
"display_name": "string",
"created_at": "string",
"updated_at": "string"
}
]
}

Delete Identity Store

Delete an identity store.

Important: You cannot delete the identity store you configured during Tableau Server setup.

Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview

Permissions: This method can only be called by users with server administrator permissions. Permissions Overview

License: No additional license required.

Access Scope: Not available.
Access Scopes Overview: Server-Windows | Server-Linux

path Parameters

id

required

integer <int32>

Required. Identity store ID.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Pulse Methods

With Tableau Pulse, Tableau Cloud users can follow metrics and use guided exploration to understand more about their data. In addition to viewing metrics from the Tableau Pulse home page, users can receive digests via Slack or email that include insights into important changes in their data so users can stay up to date.

Tableau Pulse Overview

A metric definition specifies the metadata for all related metrics created using the definition. This includes the data source, measure, time dimension, and which data source dimensions can be filtered by users or programmatically to create related metrics.
- Example: A metric definition might specify that the data source is the Superstore sales database, and that the measure to focus on is the aggregation "sum of sales". It could define the filterable dimensions as region and product line, that the time dimension for analysis is order date, and that the favorable direction is for the metric to increase.
A metric is the interactive object that users follow and receive updates on. It specifies the values to give the filterable dimensions of the metric's definition and the measurement time period of the metric.
- Example: A user or REST request could filter the metric, and its automatically generated insights, based on the West region and product line sold. The insight provided might call out that discounted sales have risen sharply in a region between last quarter and the current one.
A user who follows (has a subscription to) a metric can receive digests via email or Slack. Digests can also be viewed in the Metrics home page in the Tableau UI.
A digest provides summary visualizations and text describing the top insights for a metric. It also displays links to further metric details and to suggested follow up questions based on the metric's data and insights.
An insight is a data-driven observation about a metric. Tableau automatically generates and ranks insights by usefulness.
An insight bundle is a collection of insights for a metric That can be configured to include various elements.

For more information and to learn about the UI features related to these methods, see Create Pulse Metrics.

Configuring Pulse insights for a metric

You can use Pulse REST API methods to generate an insight bundle for a metric. An insight bundle request specifies the metric being analyzed, the output format (text or HTML), time frame, and additional filters for the insights in the bundle.

In the request, you configure the type of insight bundle that should be provided for a metric. Types include:

ban - Shows the current aggregated value for a metric, period over period change, and the highest ranked insight for each filterable dimension of the metric.
springboard - Shows the current value, period over period change, and the highest ranked insight for the metric.
basic - Similar to a springboard insight, but data is focused on the dimensions of a metric that are low bandwidth because they have small value sets. It shows the current value, period over period change, and the highest ranked insight for the metric for that data.
detail - Shows insights on performance over time of the metric, a summary visualization of metric highs and lows and trends, breakdowns of top contributors for each filterable dimension of the metric, and followup insights based on the top ranked insights not already presented.

Process suggestion: Bundles are rich and complex objects that can be challenging to build manually. One approach to efficiently create the JSON for a bundle is to use the Tableau user interface to create the form of metric definition and metrics you want to produce programmatically. Then you can navigate to a metric and use your browsers' inspector to view and copy the JSON response for the insight bundle. You can use the JSON directly or as a template in your code.

Insight types

Depending on the type of insight bundle you request and the shape of your data source, some or all of the following types of insights will be returned.

Name	Description
Period over Period Change	`INSIGHT_TYPE_CURRENT_TREND` Shows how a metric has changed between two periods. Highlights the change between a metric value for a recent time range compared to an equivalent time range in a prior period or the past.
Risky Monopoly	`INSIGHT_TYPE_RISKY_MONOPOLY` Shows when a small number of dimension members make up a majority (50% or more) of the contribution to a metric. Shows dimensions with a concentration of very high values. A risky monopoly is a situation when a small number of dimension members make up a majority (50% or more) of the contribution to a metric.
Top Contributors	`INSIGHT_TYPE_TOP_DIMENSION_MEMBER_MOVERS` Shows the highest values in a dimension for a metric within a given time range. A top contributor is a dimension member that ranks in the top N in contribution to the scoped metric’s value, aggregated on a specified time range.
Bottom Contributors	`INSIGHT_TYPE_BOTTOM_CONTRIBUTORS` Shows the lowest values in a dimension for a metric within a given time range. A bottom contributor is a dimension member that ranks in the bottom N in contribution to the scoped metric’s value, aggregated on a specified time range.
Top Drivers	`INSIGHT_TYPE_TOP_DRIVERS` Shows values for dimension members that changed the most in the same direction as the observed change in the metric. Shows the values for a metric that increased the most across a specified time offset. A top driver is a dimension member that ranks in the top N in driving a change in a metric value between two separate but equivalent time ranges. Top drivers are analyzed using metric values from two separate but equivalent time ranges (such as Sales for day of October 2 versus Sales for day of October 3) to look for changes to the contributions in the same direction of the change made by dimension members.
Top Detractors	`INSIGHT_TYPE_TOP_DETRACTORS` Shows values for dimension members that changed the most in the opposite direction to the observed change in the metric. Shows values for a metric that are most opposed to top drivers decreased the most across a specified time offset. A top detractor is a dimension member that ranks in the bottom N in driving a change in a metric value between two separate but equivalent time ranges. This insight's values oppose the observed change the most. Top detractors are analyzed using metric values from two separate but equivalent time ranges (such as Sales for day of October 2 versus Sales for day of October 3) to look for changes to the contributions in the same direction of the change made by dimension members.
Unusually High/Low Metric value	`INSIGHT_TYPE_UNUSUAL_CHANGE` Shows unexpected changes in a metric value. Shows when the value of a metric for a given time range is higher or lower than the expected range based on historic observations of the metric. This insight highlights when the value of a metric for a given time range is higher or lower than the expected range based on historic observations of the metric.
New Trend Detected	`INSIGHT_TYPE_NEW_TREND` Shows new trends that vary significantly from the current trend. This insight communicates the rate of change, direction, and fluctuations for the metric value.
Outliers	`INSIGHT_TYPE_RECORD_LEVEL_OUTLIERS` Shows values that fell outside of the range of most of the rest of the values for a metric.

For more detailed information on the types of insights, see The Insights Platform and Insight Types in Tableau Pulse.

What do Pulse REST API methods enable?

Metric definitions

Create, update, and delete metric definitions

Get a list of metric definitions for a site

Get a list of metrics for a metric definition

Get a specified batch of metric definitions

Metrics

Get the details of a metric

Get a metric if it exists or create it if it doesn't

Create, update, and delete a metric

Get a specified batch of metrics

Metric Insights

Generate a basic insight bundle for a metric

Generate a springboard insight bundle for a metric

Generate a detail insight bundle for a metric

Metric Subscriptions

Get the details of a subscription to a metric

Get a list of subscriptions to a metric for a user

Create or delete a subscription to a metric

Update the followers of a metric

Get a specified batch of subscriptions to a metric

Create subscriptions for a batch of users or groups to a metric

Get a count of followers for a specified batch of subscriptions to a metric

List metric definition measurement periods

Gets the measurement periods for the specified metric definition.

Version: Available in API 3.25 (Tableau Cloud March 2025 / Server 2025.1) and later. Not available for Tableau Server. Versioning Overview

Permissions: Can only be called by users with site or server administrator permissions.Permissions Overview

License: No additional license required.

Access Scope: tableau:content:read
Access Scopes Overview: Cloud

Note that examples of request bodies using both basic_specification.time_measure and viz_state_string are provided in the right panel.

Required fields include:

definition.datasource.id (string): The ID of the datasource to use for the metric definition.
Either:
- definition.basic_specification.time_measure (object): The time measure to use for the metric definition. OR
- A valid viz_state_string (string): The viz state string to use for the metric definition.

Optional fields include:

extension_options.allowed_granularities (array): The allowed granularities for the metric definition.
extension_options.custom_calendar (object): The custom calendar defined in your data source to use for the metric definition.
options.offset_from_today (integer): The offset from today for the metric definition.
options.now (string): The current date and time in ISO 8601 format.
options.time_zone (string): The time zone to use for the metric definition.
options.language (string): The language to use for the metric definition.
options.locale (string): The locale to use for the metric definition.

NOTE: Time measure settings can interact with each other, for instance, configuring a custom calendar will override settings that use fiscal time measures. Make sure to carefully check that the results of your configurations are what you expect.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.pulse.insightsservice.v1.GetMeasurementPeriodsRequest+json

	object (tableau.pulse.insightsservice.v1.GetMeasurementPeriodsRequest.MeasurementPeriodsInput)
	object (tableau.pulse.insightsservice.v1.GetMeasurementPeriodsRequest.MeasurementPeriodsOptions)

Responses

Request samples

Payload

Content type

application/vnd.tableau.pulse.insightsservice.v1.GetMeasurementPeriodsRequest+json

Example

Using basic specification time dimension

{"definition": {"datasource": {"id": "43c9facf-dd5c-4d14-a64b-dc0d8b1f096c"
},
"basic_specification": {"time_dimension": {"field": "Time Dimension"
}
}
},
"extension_options": {"allowed_granularities": ["GRANULARITY_BY_DAY",
"GRANULARITY_BY_WEEK",
"GRANULARITY_BY_MONTH",
"GRANULARITY_BY_QUARTER",
"GRANULARITY_BY_YEAR"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "Day of Year",
"month_of_year_field": "Month of Year",
"quarter_field": "Quarter",
"week_of_year_field": "Week of Year",
"year_field": "Year",
"reference_date_field": "Reference Date",
"month_name_field": "Month Name"
}
},
"now": "2025-02-09",
"time_zone": "UTC",
"language": "LANGUAGE_DE_DE",
"locale": "LOCALE_DE_DE"
}

Response samples

Content type

application/vnd.tableau.pulse.insightsservice.v1.GetMeasurementPeriodsResponse+json

{"measurement_periods": [{"info": {"range": "string"
},
"error": {"code": "string",
"message": "string"
},
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
}
}
]
}

List site alerts

List the alerts for the authorized user user on a specified site.

Version: Available in API 3.25 (Tableau Cloud March 2025 / Server 2025.1) and later. Not available for Tableau Server. Versioning Overview

Permissions: Any users can list the alerts for sites that they administer. Permissions Overview

License: No additional license required.

Access Scope: tableau:content:read
Access Scopes Overview: Cloud

query Parameters

page_token	string Specifies the page of items to be returned from a requested list. The value of `page_token` for the next page of returns is found in the `next_page_token` of the current response. If there are no further items to return, the value of `next_page_token` will be empty. Example: `GET ...//alerts?pageToken={next_page_value}` Combining Path Parameters: A page_token expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression. Learn more about paginating the response.
after	string If `true`, only alerts that occur after the time of alert creation will be returned. If `false` , alerts from the previous 24 hours will be included in returns. Default is false if after is not set.
page_size	integer <int32> Specifies the number of results in a paged response. Example: `GET ...//alerts?pageSize=50` Combining Path Parameters: A page_size expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression. Learn more about paginating the response.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.alertservice.v1.ListAlertsResponse+json

{"alerts": [{"id": "string",
"metric_id": "string",
"alert_info": {"metric_name": "string",
"alert_type": "ALERT_TYPE_UNSPECIFIED"
},
"create_time": "string",
"delivery_time": "string"
}
],
"next_page_token": "string",
"total_available": 0,
"offset": 0
}

Create metric tag for user

Creates a tag for the specified metric, for the signed in user.

Tags configured for a metric by a user are returned and/or have an impact on Pulse views only for that user.

Version: Available in API 3.25 (Tableau Cloud March 2025) and later. Not available for Tableau Server. Version Overview

Permissions: Anyone can make this request but users will see results only for metrics they have permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:read
Access Scopes Overview: Cloud

path Parameters

metric_id

required

string

The LUID of the metric the tag is is being created for.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.metricqueryservice.v1.CreateTagRequest+json

metric_id	string The LUID of the metric the tag is is being created for.
category	string Enum: "CATEGORY_USER_DEFINED" "CATEGORY_SYSTEM_DEFINED" The category of the tag being created. Set the `category` to `CATEGORY_SYSTEM_DEFINED` and `value` to `mute-from-summary` to hide a metric from insight summaries. Currently, `mute-from-summary` is the only valid value for system-defined tags. User-defined tag values must have no blank spaces, be less than 50 characters, and may not be an empty string. User- and system-defined tags appear in responses that give metric details so that you can retrieve them for programmatic use. There is currently no Tableau functionality connected with user defined tags but, depending on user feedback, there may be in the future.
value	string The name of the tag being created.

Responses

Request samples

Payload

Content type

application/vnd.tableau.metricqueryservice.v1.CreateTagRequest+json

{"metric_id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string"
}

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.CreateTagResponse+json

{"tag": {"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
}

Create metric definition

Creates a metric definition.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric definition as long as the user has write and publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions:create
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.metricqueryservice.v1.CreateDefinitionRequest+json

name

string

The name of the metric definition.

description

string

The description of the metric definition.

object (tableau.metricqueryservice.types.v1.DefinitionSpecification)

object (tableau.metricqueryservice.types.v1.ExtensionOptions)

object (tableau.metricqueryservice.types.v1.RepresentationOptions)

object (tableau.metricqueryservice.types.v1.InsightsOptions)

object (tableau.metricqueryservice.types.v1.Comparisons)

Array of objects (tableau.metricqueryservice.types.v1.DatasourceGoalSpecification)

A data source goal defines a metric with a target that is calculated from values in the definition's data source. This is as opposed to a metric goal whose value is defined directly in the request.

CURRENTLY:
Only one data source goal is supported per metric. If multiple data source goals are specified, only the first one will be used.
- The specification of the Basic Metric of a data source goal must use the aggregation value `AGGREGATION_SUM` or `AGGREGATION_COUNT`. That restriction doesn't apply of you configured the definition using the advanced definition editor
If a metric goal is defined in the configuration of a request to generate an insight bundle, then the metric goal will take precedence over any data source goal that is also defined in the request, and nothing will be returned for the data source goal."
When supplying a data source goal as input for a request to generate an insight bundle, it's granularity cannot be higher than the granularity configured in the request for the insight. If the data source goal granularity is higher than the requested insight granularity, then nothing will be returned for the data source goal.

Array of objects (tableau.metricqueryservice.types.v1.Link)

Responses

Request samples

Payload

Content type

application/vnd.tableau.metricqueryservice.v1.CreateDefinitionRequest+json

{"name": "string",
"description": "string",
"specification": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"comparisons": {"comparisons": [{"compare_config": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
},
"index": 0
}
]
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
],
"related_links": [{"link_name": "string",
"link_url": "string"
}
]
}

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.CreateDefinitionResponse+json

{"definition": {"metadata": {"name": "string",
"description": "string",
"id": "string",
"schema_version": "string",
"metric_version": 0,
"definition_version": 0,
"last_updated_user": {"id": "string"
},
"related_links": [{"link_name": "string",
"link_url": "string"
}
]
},
"specification": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
],
"total_metrics": 0,
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"comparisons": {"comparisons": [{"compare_config": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
},
"index": 0
}
]
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}

List metric definitions

Lists the metric definitions configured for a site or, optionally, the details and definition for a specific metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions_metrics:read
Access Scopes Overview: Cloud

query Parameters

enable_sorting	boolean If `True`, the metrics will be sorted by the metric name. If false, the metrics will be returned in the order they were requested. The default is `False`. (Available in API 3.24 (Tableau Cloud December 2024) and later.)
order_by	string The sort order of the results. The format is `<field> <direction>`. The direction can be either `asc` or `desc`. The default is `asc`. (Available in API 3.24 (Tableau Cloud December 2024) and later.)
view	string Enum: "DEFINITION_VIEW_UNSPECIFIED" "DEFINITION_VIEW_BASIC" "DEFINITION_VIEW_FULL" "DEFINITION_VIEW_DEFAULT" The range of metrics to return for a definition. The default is 'DEFINITION_VIEW_BASIC' if not specified. 'DEFINITION_VIEW_BASIC' - Return only the specified metric definition. 'DEFINITION_VIEW_FULL' - Return the metric definition and the specified number of metrics. 'DEFINITION_VIEW_DEFAULT' - Return the metric definition and the default metric.
page_size	integer <int32> Specifies the number of results in a paged response. Example: `GET ...//definitions?pageSize=50` Combining Path Parameters: A page_size expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression. Learn more about paginating the response.
metric_id	string If a metric LUID is specified, only return the definition that is related to the metric, and the details of the metric.
number_of_metrics	integer <int64> (Required if `view` is `DEFINITION_VIEW_FULL`) The number of metrics to return. If not specified, the default is unlimited. (Available in API 3.24 (Tableau Cloud December 2024) and later.)
page_token	string Specifies the page of items to be returned from a requested list. The value of `page_token` for the next page of returns is found in the `next_page_token` of the current response. If there are no further items to return, the value of `next_page_token` will be empty. Example: `GET .../definitions?pageToken={next_page_value}` Combining Path Parameters: A page_token expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression. Learn more about paginating the response.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.ListDefinitionsResponse+json

{"definitions": [{"metadata": {"name": "string",
"description": "string",
"id": "string",
"schema_version": "string",
"metric_version": 0,
"definition_version": 0,
"last_updated_user": {"id": "string"
},
"related_links": [{"link_name": "string",
"link_url": "string"
}
]
},
"specification": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": null
},
"comparison_time": {"field": null
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
],
"total_metrics": 0,
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"comparisons": {"comparisons": [{"compare_config": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": null
},
"comparison_time": {"field": null
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
},
"index": 0
}
]
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
],
"next_page_token": "string",
"total_available": 0,
"offset": 0
}

Delete metric definition

Deletes a metric definition.

When a definition is deleted, all metrics related to it, and all subscriptions to those metrics are also deleted.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can delete a metric definition as long as the user has write and publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions:delete
Access Scopes Overview: Cloud

path Parameters

definition_id

required

string

(Required) The LUID of the metric definition.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Get metric definition

Gets a metric definition and optionally metrics it contains.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions_metrics:read
Access Scopes Overview: Cloud

path Parameters

definition_id

required

string

(Required) The LUID of the metric definition.

query Parameters

view

string

Enum: "DEFINITION_VIEW_UNSPECIFIED" "DEFINITION_VIEW_BASIC" "DEFINITION_VIEW_FULL" "DEFINITION_VIEW_DEFAULT"

The range of metrics to return for a definition. The default is 'DEFINITION_VIEW_BASIC' if not specified.

'DEFINITION_VIEW_BASIC' - Return only the specified metric definition.
'DEFINITION_VIEW_FULL' - Return the metric definition and the specified number of metrics.
'DEFINITION_VIEW_DEFAULT' - Return the metric definition and the default metric."

number_of_metrics

integer <int64>

(Required if 'view' is 'DEFINITION_VIEW_FULL') The number of metrics to return.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.GetDefinitionResponse+json

{"definition": {"metadata": {"name": "string",
"description": "string",
"id": "string",
"schema_version": "string",
"metric_version": 0,
"definition_version": 0,
"last_updated_user": {"id": "string"
},
"related_links": [{"link_name": "string",
"link_url": "string"
}
]
},
"specification": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
],
"total_metrics": 0,
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"comparisons": {"comparisons": [{"compare_config": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
},
"index": 0
}
]
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}

Update metric definition

Updates a metric definition.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can update a metric definition as long as the user has write and publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions:update
Access Scopes Overview: Cloud

path Parameters

definition_id

required

string

(Required) The LUID of the metric definition.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.metricqueryservice.v1.UpdateDefinitionRequest+json

definition_id	string (Required) The LUID of the metric definition.
name	string The name of the metric definition.
description	string The description of the metric definition.
	object (tableau.metricqueryservice.types.v1.DefinitionSpecification)
	object (tableau.metricqueryservice.types.v1.ExtensionOptions)
	object (tableau.metricqueryservice.types.v1.RepresentationOptions)
	object (tableau.metricqueryservice.types.v1.InsightsOptions)
user_link	string
user_link_name	string
	object (tableau.metricqueryservice.types.v1.Comparisons)
	Array of objects (tableau.metricqueryservice.types.v1.DatasourceGoalSpecification) A data source goal defines a metric with a target that is calculated from values in the definition's data source. This is as opposed to a metric goal whose value is defined directly in the request. CURRENTLY: Only one data source goal is supported per metric. The specification of the Basic Metric of a data source goal must use the aggregation value `AGGREGATION_SUM` or `AGGREGATION_COUNT`. If a metric goal is defined in the configuration of a request to generate an insight bundle, then the metric goal will take precedence over any data source goal that is also defined in the request, and nothing will be returned for the data source goal." When supplying a data source goal as input for a request to generate an insight bundle, it's granularity cannot be higher than the granularity configured in the request for the insight. If the data source goal granularity is higher than the requested insight granularity, then nothing will be returned for the data source goal.
	Array of objects (tableau.metricqueryservice.types.v1.Link)

Responses

Request samples

Payload

Content type

application/vnd.tableau.metricqueryservice.v1.UpdateDefinitionRequest+json

{"definition_id": "string",
"name": "string",
"description": "string",
"specification": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"user_link": "string",
"user_link_name": "string",
"comparisons": {"comparisons": [{"compare_config": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
},
"index": 0
}
]
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
],
"related_links": [{"link_name": "string",
"link_url": "string"
}
]
}

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.UpdateDefinitionResponse+json

{"definition": {"metadata": {"name": "string",
"description": "string",
"id": "string",
"schema_version": "string",
"metric_version": 0,
"definition_version": 0,
"last_updated_user": {"id": "string"
},
"related_links": [{"link_name": "string",
"link_url": "string"
}
]
},
"specification": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
],
"total_metrics": 0,
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"comparisons": {"comparisons": [{"compare_config": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
},
"index": 0
}
]
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}

List metrics in definition

Lists the metrics contained in a metric definition.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions_metrics:read
Access Scopes Overview: Cloud

path Parameters

definition_id

required

string

(Required) The LUID of the metric definition.

query Parameters

page_size	integer <int32> Specifies the number of results in a paged response. Example: 'GET .../subscriptions?pageSize=50' Combining Path Parameters: A page_size expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression. Learn more about paginating the response.
page_token	string Specifies the page of items to be returned from a requested list. The value of `page_token` for the next page of returns is found in the `next_page_token` of the current response. If there are no further items to return, the value of `next_page_token` will be empty. Example: `GET ...//definitions/{definition_id}/metrics?pageToken={next_page_value}` Combining Path Parameters: A page_token expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression. Learn more about paginating the response.
enable_sorting	boolean
order_by	string
exclude_metrics_without_followers	boolean If `True`, the metrics will be sorted by the metric name. If false, the metrics will be returned in the order they were requested.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.ListMetricsResponse+json

{"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
],
"next_page_token": "string",
"total_available": 0,
"offset": 0
}

Batch list metric definitions (few) Deprecated

Gets the details of a batch of metric definitions and metrics on a site, specified in a brief comma delimited list of LUIDs.

Note: In API 3.24 (Tableau Cloud December 2025) and later, this method is deprecated and may be retired in future releases. Instead use the Batch list metric definitions (many). That method has the same behavior but supports listing larger batches of definitions.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_definitions_metrics:read
Access Scopes Overview: Cloud

query Parameters

definition_ids	string (Required) The metric definitions to get, formatted as a comma separated list of LUIDs.
view	string Enum: "DEFINITION_VIEW_UNSPECIFIED" "DEFINITION_VIEW_BASIC" "DEFINITION_VIEW_FULL" "DEFINITION_VIEW_DEFAULT" The range of metrics to return for a definition. The default is `DEFINITION_VIEW_BASIC` if not specified. `DEFINITION_VIEW_BASIC` - Return only the specified metric definition. `DEFINITION_VIEW_FULL` - Return the metric definition and the specified number of metrics. `DEFINITION_VIEW_DEFAULT` - Return the metric definition and the default metric."
number_of_metrics	integer <int64> (Required if `view` is `DEFINITION_VIEW_FULL`) The number of metrics to return.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.BatchGetDefinitionsResponse+json

{"definitions": [{"metadata": {"name": "string",
"description": "string",
"id": "string",
"schema_version": "string",
"metric_version": 0,
"definition_version": 0,
"last_updated_user": {"id": "string"
},
"related_links": [{"link_name": "string",
"link_url": "string"
}
]
},
"specification": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": null
},
"comparison_time": {"field": null
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
],
"total_metrics": 0,
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"comparisons": {"comparisons": [{"compare_config": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": null
},
"comparison_time": {"field": null
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
},
"index": 0
}
]
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
],
"errors": [{"id": "string",
"error": "string"
}
]
}

Batch list metric definitions (many)

Gets the details of a batch of definitions specified in a comma delimited list of LUIDs. This method is optimized for batches with large numbers of definitions.

Version: Available in API 3.24 (Tableau Cloud December 2024) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can make this request but users will see results only for metrics they have permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.metricqueryservice.v1.BatchGetDefinitionsByPostRequest+json

definition_ids	Array of strings (Required) The LUIDs of the definitions to retrieve.
view	string Enum: "DEFINITION_VIEW_UNSPECIFIED" "DEFINITION_VIEW_BASIC" "DEFINITION_VIEW_FULL" "DEFINITION_VIEW_DEFAULT" The scope of metrics in the definition to return. The default is `DEFINITION_VIEW_BASIC`, which returns only the basic view. `DEFINITION_VIEW_FULL` returns the definition and all of its metrics. `DEFINITION_VIEW_DEFAULT` returns the definition and the default metric.
number_of_metrics	integer <int64> The number of metrics to return for each definition.

Responses

Request samples

Payload

Content type

application/vnd.tableau.metricqueryservice.v1.BatchGetDefinitionsByPostRequest+json

{"definition_ids": ["string"
],
"view": "DEFINITION_VIEW_UNSPECIFIED",
"number_of_metrics": 0
}

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.BatchGetDefinitionsByPostResponse+json

{"definitions": [{"metadata": {"name": "string",
"description": "string",
"id": "string",
"schema_version": "string",
"metric_version": 0,
"definition_version": 0,
"last_updated_user": {"id": "string"
},
"related_links": [{"link_name": "string",
"link_url": "string"
}
]
},
"specification": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": null
},
"comparison_time": {"field": null
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
],
"total_metrics": 0,
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"comparisons": {"comparisons": [{"compare_config": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": null
},
"comparison_time": {"field": null
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
},
"index": 0
}
]
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
],
"errors": [{"id": "string",
"error": "string"
}
]
}

Get site entitlements

Returns entitlements available for a site. If entitlements are True, then Pulse premium features are enabled for the site.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Can be called by any user, but only details about sited the user has permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:entitlements:read
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.GetEntitlementsResponse+json

{"entitlements": [{"entitlement_type": "ENTITLEMENT_TYPE_UNSPECIFIED",
"enabled": true
}
]
}

Generate current metric value insight bundle

Generates a bundle the current aggregated value for each metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleBANRequest+json

object (tableau.pulse.insightsservice.v1.GenerateInsightBundleRequest)

Responses

Request samples

Payload

Content type

application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleBANRequest+json

{"bundle_request": {"version": 0,
"options": {"output_format": "OUTPUT_FORMAT_UNSPECIFIED",
"now": "string",
"time_zone": "string",
"score_weights": {"impact_score": 0,
"relevance_score": 0,
"certainty_score": 0
},
"language": "LANGUAGE_UNSPECIFIED",
"locale": "LOCALE_UNSPECIFIED"
},
"input": {"metadata": {"name": "string",
"metric_id": "string",
"definition_id": "string",
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
},
"metric": {"definition": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"metric_specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"goals": {"target": {"value": 0
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": null,
"operator": null,
"categorical_values": [ ]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}
}
}
}

Response samples

Content type

application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleBANResponse+json

{"bundle_response": {"result": {"insight_groups": [{"type": "string",
"insights": [{"result": {"type": "string",
"version": 0,
"markup": "string",
"viz": null,
"facts": {"fields": {"property1": null,
"property2": null
}
},
"characterization": "CHARACTERIZATION_UNSPECIFIED",
"question": "string",
"score": 0,
"id": "string",
"insight_feedback_metadata": {"type": "string",
"score": 0,
"dimension_hash": "string"
},
"table": {"columns": [null
],
"rows": [null
]
},
"generation_id": "string"
},
"error": {"code": "string",
"message": "string"
},
"insight_type": "string"
}
],
"summaries": [{"result": {"id": "string",
"markup": "string",
"viz": {"fields": {"property1": null,
"property2": null
}
},
"generation_id": "string",
"timestamp": "string",
"last_attempted_timestamp": "string"
},
"error": {"code": "string",
"message": "string"
}
}
],
"error": {"code": "string",
"message": "string"
}
}
],
"has_errors": true,
"characterization": "CHARACTERIZATION_UNSPECIFIED"
},
"error": {"code": "string",
"message": "string"
}
}
}

Generate basic insight bundle

Generates a basic insight bundle.

Version: Available in API 3.24 (Tableau Cloud December 2024) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleBasicRequest+json

object (tableau.pulse.insightsservice.v1.GenerateInsightBundleRequest)

Responses

Request samples

Payload

Content type

application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleBasicRequest+json

{"bundle_request": {"version": 0,
"options": {"output_format": "OUTPUT_FORMAT_UNSPECIFIED",
"now": "string",
"time_zone": "string",
"score_weights": {"impact_score": 0,
"relevance_score": 0,
"certainty_score": 0
},
"language": "LANGUAGE_UNSPECIFIED",
"locale": "LOCALE_UNSPECIFIED"
},
"input": {"metadata": {"name": "string",
"metric_id": "string",
"definition_id": "string",
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
},
"metric": {"definition": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"metric_specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"goals": {"target": {"value": 0
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": null,
"operator": null,
"categorical_values": [ ]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}
}
}
}

Response samples

Content type

application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleBasicResponse+json

{"bundle_response": {"result": {"insight_groups": [{"type": "string",
"insights": [{"result": {"type": "string",
"version": 0,
"markup": "string",
"viz": null,
"facts": {"fields": {"property1": null,
"property2": null
}
},
"characterization": "CHARACTERIZATION_UNSPECIFIED",
"question": "string",
"score": 0,
"id": "string",
"insight_feedback_metadata": {"type": "string",
"score": 0,
"dimension_hash": "string"
},
"table": {"columns": [null
],
"rows": [null
]
},
"generation_id": "string"
},
"error": {"code": "string",
"message": "string"
},
"insight_type": "string"
}
],
"summaries": [{"result": {"id": "string",
"markup": "string",
"viz": {"fields": {"property1": null,
"property2": null
}
},
"generation_id": "string",
"timestamp": "string",
"last_attempted_timestamp": "string"
},
"error": {"code": "string",
"message": "string"
}
}
],
"error": {"code": "string",
"message": "string"
}
}
],
"has_errors": true,
"characterization": "CHARACTERIZATION_UNSPECIFIED"
},
"error": {"code": "string",
"message": "string"
}
}
}

Generate detail insight bundle

Generates a detail insight bundle.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required. For the usage-based licensing model, each call to this method counts as an analytical impression.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleDetailRequest+json

object (tableau.pulse.insightsservice.v1.GenerateInsightBundleRequest)

Responses

Request samples

Payload

Content type

application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleDetailRequest+json

{"bundle_request": {"version": 0,
"options": {"output_format": "OUTPUT_FORMAT_UNSPECIFIED",
"now": "string",
"time_zone": "string",
"score_weights": {"impact_score": 0,
"relevance_score": 0,
"certainty_score": 0
},
"language": "LANGUAGE_UNSPECIFIED",
"locale": "LOCALE_UNSPECIFIED"
},
"input": {"metadata": {"name": "string",
"metric_id": "string",
"definition_id": "string",
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
},
"metric": {"definition": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"metric_specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"goals": {"target": {"value": 0
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": null,
"operator": null,
"categorical_values": [ ]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}
}
}
}

Response samples

Content type

application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleDetailResponse+json

{"bundle_response": {"result": {"insight_groups": [{"type": "string",
"insights": [{"result": {"type": "string",
"version": 0,
"markup": "string",
"viz": null,
"facts": {"fields": {"property1": null,
"property2": null
}
},
"characterization": "CHARACTERIZATION_UNSPECIFIED",
"question": "string",
"score": 0,
"id": "string",
"insight_feedback_metadata": {"type": "string",
"score": 0,
"dimension_hash": "string"
},
"table": {"columns": [null
],
"rows": [null
]
},
"generation_id": "string"
},
"error": {"code": "string",
"message": "string"
},
"insight_type": "string"
}
],
"summaries": [{"result": {"id": "string",
"markup": "string",
"viz": {"fields": {"property1": null,
"property2": null
}
},
"generation_id": "string",
"timestamp": "string",
"last_attempted_timestamp": "string"
},
"error": {"code": "string",
"message": "string"
}
}
],
"error": {"code": "string",
"message": "string"
}
}
],
"has_errors": true,
"characterization": "CHARACTERIZATION_UNSPECIFIED"
},
"error": {"code": "string",
"message": "string"
}
}
}

Generate springboard insight bundle

Generates a springboard insight bundle.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleSpringboardRequest+json

object (tableau.pulse.insightsservice.v1.GenerateInsightBundleRequest)

Responses

Request samples

Payload

Content type

application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleSpringboardRequest+json

{"bundle_request": {"version": 0,
"options": {"output_format": "OUTPUT_FORMAT_UNSPECIFIED",
"now": "string",
"time_zone": "string",
"score_weights": {"impact_score": 0,
"relevance_score": 0,
"certainty_score": 0
},
"language": "LANGUAGE_UNSPECIFIED",
"locale": "LOCALE_UNSPECIFIED"
},
"input": {"metadata": {"name": "string",
"metric_id": "string",
"definition_id": "string",
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
},
"metric": {"definition": {"datasource": {"id": "string"
},
"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"is_running_total": true
},
"metric_specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"extension_options": {"allowed_dimensions": ["string"
],
"allowed_granularities": ["GRANULARITY_UNSPECIFIED"
],
"offset_from_today": 0,
"custom_calendar": {"day_of_year_field": "string",
"month_of_year_field": "string",
"quarter_field": "string",
"week_of_year_field": "string",
"year_field": "string",
"reference_date_field": "string",
"month_name_field": "string"
}
},
"representation_options": {"type": "NUMBER_FORMAT_TYPE_UNSPECIFIED",
"number_units": {"singular_noun": "string",
"plural_noun": "string"
},
"sentiment_type": "SENTIMENT_TYPE_UNSPECIFIED",
"row_level_id_field": {"identifier_col": "string"
},
"row_level_entity_names": {"entity_name_singular": "string",
"entity_name_plural": "string"
},
"row_level_name_field": {"name_col": "string"
},
"currency_code": "CURRENCY_CODE_UNSPECIFIED"
},
"insights_options": {"settings": [{"type": "INSIGHT_TYPE_UNSPECIFIED",
"disabled": true
}
]
},
"goals": {"target": {"value": 0
},
"datasource_goals": [{"basic_specification": {"measure": {"field": "string",
"aggregation": "AGGREGATION_UNSPECIFIED"
},
"time_dimension": {"field": "string"
},
"filters": [{"field": null,
"operator": null,
"categorical_values": [ ]
}
]
},
"viz_state_specification": {"viz_state_string": "string"
},
"minimum_granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}
}
}
}

Response samples

Content type

application/vnd.tableau.pulse.insightsservice.v1.GenerateInsightBundleSpringboardResponse+json

{"bundle_response": {"result": {"insight_groups": [{"type": "string",
"insights": [{"result": {"type": "string",
"version": 0,
"markup": "string",
"viz": null,
"facts": {"fields": {"property1": null,
"property2": null
}
},
"characterization": "CHARACTERIZATION_UNSPECIFIED",
"question": "string",
"score": 0,
"id": "string",
"insight_feedback_metadata": {"type": "string",
"score": 0,
"dimension_hash": "string"
},
"table": {"columns": [null
],
"rows": [null
]
},
"generation_id": "string"
},
"error": {"code": "string",
"message": "string"
},
"insight_type": "string"
}
],
"summaries": [{"result": {"id": "string",
"markup": "string",
"viz": {"fields": {"property1": null,
"property2": null
}
},
"generation_id": "string",
"timestamp": "string",
"last_attempted_timestamp": "string"
},
"error": {"code": "string",
"message": "string"
}
}
],
"error": {"code": "string",
"message": "string"
}
}
],
"has_errors": true,
"characterization": "CHARACTERIZATION_UNSPECIFIED"
},
"error": {"code": "string",
"message": "string"
}
}
}

Create metric

Creates a metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:create
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.metricqueryservice.v1.CreateMetricRequest+json

definition_id	string (Required) The LUID of the definition.
	object (tableau.metricqueryservice.types.v1.MetricSpecification)

Responses

Request samples

Payload

Content type

application/vnd.tableau.metricqueryservice.v1.CreateMetricRequest+json

{"definition_id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}
}

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.CreateMetricResponse+json

{"metric": {"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
}

Delete metric

Deletes a metric.

Note: When a definition is created, a default metric is created for it. A default metric can't be deleted, unless its definition is deleted, and trying will result in a '400' error.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can delete a metric from a definition as long as the user has write and publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:delete
Access Scopes Overview: Cloud

path Parameters

metric_id

required

string

(Required) The LUID of the metric to be deleted.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

400
401
404
500
503

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Get metric

Gets the details of the specified metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can update a metric if they have both write and publish access to the data source used in the definition. Permissions Overview

As of August 2023 in API 3.23: If a user has both read and connect permissions, but don't have write and publish permissions, then they can update the 'goals' field of a metric, but not other fields.

License: No additional license required.

Access Scope: tableau:insight_metrics:read
Access Scopes Overview: Cloud

path Parameters

metric_id

required

string

(Required) The LUID of the metric to get.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.GetMetricResponse+json

{"metric": {"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
}

Update metric

Updates the specification of a metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric in a definition as long as the user has write and publish access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:update
Access Scopes Overview: Cloud

path Parameters

metric_id

required

string

(Required) The LUID of the metric to be updated.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.metricqueryservice.v1.UpdateMetricRequest+json

metric_id	string
	object (tableau.metricqueryservice.types.v1.MetricSpecification)
	object (tableau.metricqueryservice.types.v1.MetricGoals)

Responses

Request samples

Payload

Content type

application/vnd.tableau.metricqueryservice.v1.UpdateMetricRequest+json

{"metric_id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"goals": {"target": {"value": 0
}
}
}

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.UpdateMetricResponse+json

{"metric": {"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
}

Delete metric tag

Deletes the specified metric tag.

Version: Available in API 3.25 (Tableau Cloud March 2025) and later. Not available for Tableau Server. Version Overview

Permissions: Anyone can make this request but users will see results only for metrics they have permissions to view. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:read
Access Scopes Overview: Cloud

path Parameters

tag_id required	string The LUID of the tag being deleted from a metric.
metric_id required	string The LUID of the metric the tag is being deleted from.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

400
401
404
500
503

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Batch list metrics

Gets a batch of metrics from a definition, specified in a comma delimited list.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can get a batch of metrics as long as the user has read or connect access to the data source used in the definition that contains them. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:read
Access Scopes Overview: Cloud

query Parameters

enable_sorting	boolean (Required) If true, the metrics will be sorted by the metric name. If false, the metrics will be returned in the order they were requested.
metric_ids	string (Required) The metrics to get, formatted as a comma separated list of LUIDs.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.BatchGetMetricsResponse+json

{"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
],
"errors": [{"id": "string",
"error": "string"
}
]
}

List followed metrics groups

Gets the user's followed metrics. Optionally metrics can be grouped by characteristics like datasource, and sorted.

If no grouping and sorting is specified then returns are grouped and sorted by existing user preferences. If no user preferences exist or are specified, then metrics are grouped by most recently followed, in descending order. If metrics are grouped by most recently followed then they are returned in a single group, that is sorted by the specified, existing, or default order.

Version: Available in API 3.23 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. *Permissions Overview*\n

License: No additional license required.

Access Scope: tableau:insights:read
Access Scopes Overview: Cloud

query Parameters

group_by	string Enum: "GROUP_BY_UNSPECIFIED" "GROUP_BY_RECENTLY_FOLLOWED" "GROUP_BY_DEFINITION_NAME" "GROUP_BY_DATASOURCE_LABEL" "GROUP_BY_TIME_RANGE"
sort_order	string Enum: "SORT_ORDER_UNSPECIFIED" "SORT_ORDER_ASCENDING" "SORT_ORDER_DESCENDING" The order to use in sorting returns.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.ListFollowedMetricsGroupsResponse+json

{"metric_groups": [{"group_metadata": {"group_label": "string"
},
"metrics": [{"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": null,
"bool_value": null,
"null_value": null
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": null
},
"comparison_time": {"field": null
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
}
]
}
],
"group_by": "GROUP_BY_UNSPECIFIED",
"sort_order": "SORT_ORDER_UNSPECIFIED",
"errors": [{"id": "string",
"error": "string"
}
]
}

Get or create metric

Returns the details of a metric in a definition if it exists, or creates a new metric if it does not. Also returns 'true' if a new metric was created, or 'false' if it already existed.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview

License: No additional license required.

Access Scope: tableau:insight_metrics:create
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.metricqueryservice.v1.GetOrCreateMetricRequest+json

definition_id	string (Required) The LUID of the definition for the metric.
	object (tableau.metricqueryservice.types.v1.MetricSpecification)

Responses

Request samples

Payload

Content type

application/vnd.tableau.metricqueryservice.v1.GetOrCreateMetricRequest+json

{"definition_id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
}
}

Response samples

Content type

application/vnd.tableau.metricqueryservice.v1.GetOrCreateMetricResponse+json

{"metric": {"id": "string",
"specification": {"filters": [{"field": "string",
"operator": "OPERATOR_UNSPECIFIED",
"categorical_values": [{"string_value": "string",
"bool_value": true,
"null_value": "NULL_VALUE"
}
]
}
],
"measurement_period": {"granularity": "GRANULARITY_UNSPECIFIED",
"range": "RANGE_UNSPECIFIED"
},
"comparison": {"comparison": "TIME_COMPARISON_UNSPECIFIED",
"comparison_period_override": [{"reference_time": {"field": "string"
},
"comparison_time": {"field": "string"
},
"granularity": "GRANULARITY_UNSPECIFIED"
}
]
}
},
"definition_id": "string",
"is_default": true,
"schema_version": "string",
"metric_version": 0,
"goals": {"target": {"value": 0
}
},
"is_followed": true,
"tags": [{"id": "string",
"category": "CATEGORY_USER_DEFINED",
"value": "string",
"created_at": "string",
"created_by": "string"
}
]
},
"is_metric_created": true
}

Create subscription

Creates a subscription to a specified metric for a specified user or group.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can create subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:create
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.pulse.subscriptionservice.v1.CreateSubscriptionRequest+json

metric_id	string (Required) The LUID of the metric being subscribed to.
	object (tableau.pulse.subscriptionservice.types.v1.Follower)

Responses

Request samples

Payload

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.CreateSubscriptionRequest+json

{"metric_id": "string",
"follower": {"user_id": "string",
"group_id": "string"
}
}

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.CreateSubscriptionResponse+json

{"subscription": {"id": "string",
"metric_id": "string",
"follower": {"user_id": "string",
"group_id": "string"
},
"create_time": "string",
"update_time": "string"
}
}

List subscriptions

Lists the subscriptions to a specified metric and/or for a specified user.

If only 'metric-id' is specified, all subscriptions for that metric are returned. If only 'user-id' is specified, al subscriptions for that user are returned. If both 'metric_id' or 'user_id' and specified, then the user's subscription for the specified metric is returned. If no 'metric_id' or 'user_id' is specified, all subscriptions on the site will be returned.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can list subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:read
Access Scopes Overview: Cloud

query Parameters

page_token	string Specifies the page of items to be returned from a requested list. The value of `page_token` for the next page of returns is found in the `next_page_token` of the current response. If there are no further items to return, the value of `next_page_token` will be empty. Example: `GET ...//subscriptions?pageToken={next_page_value}` Combining Path Parameters: A page_token expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression. Learn more about paginating the response.
user_id	string The LUID of a user whose subscriptions will be returned.
order_by	string The sort order of the results. The format is `<field> <direction>`. The direction can be either `asc` or `desc`.
page_size	integer <int32> Specifies the number of results in a paged response. Example: `GET .../subscriptions?pageSize=50` Combining Path Parameters: A page_size expression can be combined with other path parameters using an ampersand (&) as a separator, and is typically used along with a page number expression. Learn more about paginating the response.
metric_id	string The LUID of a metric whose subscriptions will be returned.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.ListSubscriptionsResponse+json

{"subscriptions": [{"id": "string",
"metric_id": "string",
"follower": {"user_id": "string",
"group_id": "string"
},
"create_time": "string",
"update_time": "string"
}
],
"next_page_token": "string"
}

Delete Pulse subscription

Deletes a specified subscription to a metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can delete subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:delete
Access Scopes Overview: Cloud

path Parameters

id

required

string

The LUID of the subscription being deleted.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

400
401
404
500
503

Content type

application/json

{"httpErrorCode": "string",
"message": "string"
}

Get Pulse subscription

Gets a specified subscription to a metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of a subscription. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:read
Access Scopes Overview: Cloud

path Parameters

id

required

string

(Required) The LUID of the subscription being requested.

header Parameters

X-Tableau-Auth	string The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.
X-Tableau-Auth	string The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.GetSubscriptionResponse+json

{"subscription": {"id": "string",
"metric_id": "string",
"follower": {"user_id": "string",
"group_id": "string"
},
"create_time": "string",
"update_time": "string"
}
}

Batch create Pulse subscriptions

Creates multiple subscriptions to a metric for specified users and/or groups.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can create subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:create
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.pulse.subscriptionservice.v1.BatchCreateSubscriptionsRequest+json

metric_id	string (Required) The LUID of the metric that a batch of users and or groups are being subscribed to.
	Array of objects (tableau.pulse.subscriptionservice.types.v1.Follower)

Responses

Request samples

Payload

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.BatchCreateSubscriptionsRequest+json

{"metric_id": "string",
"followers": [{"user_id": "string",
"group_id": "string"
}
]
}

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.BatchCreateSubscriptionsResponse+json

{"subscriptions": [{"id": "string",
"metric_id": "string",
"follower": {"user_id": "string",
"group_id": "string"
},
"create_time": "string",
"update_time": "string"
}
]
}

Batch get Pulse subscriptions

Gets a batch of subscriptions, specified in a comma delimited list of subscriptions LUIDs.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:read
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.BatchGetSubscriptionsResponse+json

{"subscriptions": [{"id": "string",
"metric_id": "string",
"follower": {"user_id": "string",
"group_id": "string"
},
"create_time": "string",
"update_time": "string"
}
]
}

Batch get Pulse subscriber counts

Gets the number of unique users subscribed to a set of metrics specified in a comma separated list of metric LUIDs.

For metrics with group followers, the count will be the union of all the members of the subscribed groups plus all the individual followers. Users are counted only once per metric.

Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can create subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:metric_subscriptions:read
Access Scopes Overview: Cloud

query Parameters

metric_ids

string

(Required) The metrics to get follower counts for, formatted as a comma separated list of LUIDs. If no LUIDs are specified, the follower count for all metrics in a definition will be returned.

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.BatchGetMetricFollowerCountsResponse+json

{"follower_counts": [{"metric_id": "string",
"follower_count": 0
}
]
}

List Pulse user preferences

Gets the signed in user's preferences for notifications channels and cadence, and for grouping and sorting followed metrics in REST responses and UI.

Version: Available in API 3.24 (Tableau Cloud December 2024) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:user_preferences:read
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Responses

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.GetUserPreferencesResponse+json

{"user_preferences_response": {"cadence": "CADENCE_UNSPECIFIED",
"channel_preferences": [{"channel": "DELIVERY_CHANNEL_UNSPECIFIED",
"status": "CHANNEL_STATUS_UNSPECIFIED",
"availability": "CHANNEL_AVAILABILITY_UNSPECIFIED"
}
],
"metric_grouping_preferences": {"group_by": "GROUP_BY_UNSPECIFIED",
"sort_order": "SORT_ORDER_UNSPECIFIED"
}
}
}

Update Pulse user preferences

Updates the signed in user's preferences for notifications channels and cadence, and for grouping and sorting followed metrics in REST responses and UI.

Version: Available in API 3.24 (Tableau Cloud December 2024) and later. Not available for Tableau Server. Version Overview

Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of subscriptions. Permissions Overview

License: No additional license required.

Access Scope: tableau:user_preferences:update
Access Scopes Overview: Cloud

header Parameters

X-Tableau-Auth

string

The Tableau authentication header. The value is a credentials token from a Tableau server's response to an authentication request. The Content-Type and Accept headers should be the mediatype of the request and response except in cases where you want to explicitly allow other versions of the resource.

Request Body schema: application/vnd.tableau.pulse.subscriptionservice.v1.UpdateUserPreferencesRequest+json

cadence	string Enum: "CADENCE_UNSPECIFIED" "CADENCE_DAILY" "CADENCE_WEEKLY" "CADENCE_MONTHLY"
	Array of objects (tableau.pulse.subscriptionservice.types.v1.ChannelPreferencesRequest)
	object (tableau.pulse.subscriptionservice.types.v1.MetricGroupingPreferences)

Responses

Request samples

Payload

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.UpdateUserPreferencesRequest+json

{"cadence": "CADENCE_UNSPECIFIED",
"channel_preferences_request": [{"channel": "DELIVERY_CHANNEL_UNSPECIFIED",
"status": "CHANNEL_STATUS_UNSPECIFIED"
}
],
"metric_grouping_preferences": {"group_by": "GROUP_BY_UNSPECIFIED",
"sort_order": "SORT_ORDER_UNSPECIFIED"
}
}

Response samples

Content type

application/vnd.tableau.pulse.subscriptionservice.v1.UpdateUserPreferencesResponse+json

{"user_preferences_response": {"cadence": "CADENCE_UNSPECIFIED",
"channel_preferences": [{"channel": "DELIVERY_CHANNEL_UNSPECIFIED",
"status": "CHANNEL_STATUS_UNSPECIFIED",
"availability": "CHANNEL_AVAILABILITY_UNSPECIFIED"
}
],
"metric_grouping_preferences": {"group_by": "GROUP_BY_UNSPECIFIED",
"sort_order": "SORT_ORDER_UNSPECIFIED"
}
}
}