Tableau REST API Help

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:

• 'basic' - Contains the current number, percentage, or currency value aggregated for the metric.

• 'springboard' - Contains period-over-period change, time series, and the top-ranked insight that exceed a "usefulness" score.

• 'detail' - Contains all ranked insights and follow up suggestions for a metric.

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.

Value	Name	Description
popc	Period over Period Change	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.
riskmo	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	Top Contributors	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.
top-contributors	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	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	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.
unusualchange	Unusually High/Low Metric value	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.
newtrend	New Trend Detected	Shows new trends that vary significantly from the current trend. This insight communicates the rate of change, direction, and fluctuations for the metric value.

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

Batch list metric definitions

Gets a batch of metric definitions and metrics available on a site.

GET {server}/api/-/pulse/definitions:batchGet

view details

Batch list metrics

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

GET {server}/api/-/pulse/metrics:batchGet

view details

Create metric definition

Creates a metric definition.

POST {server}/api/-/pulse/definitions

view details

Create metric

Creates a metric.

POST {server}/api/-/pulse/metrics

view details

Delete metric definition

Deletes a metric definition.

DELETE {server}/api/-/pulse/definitions/{definition_id}

view details

Delete metric

Deletes a metric.

DELETE {server}/api/-/pulse/metrics/{metric_id}

view details

Get metric definition

Gets a metric definition and optionally metrics it contains.

GET {server}/api/-/pulse/definitions/{definition_id}

view details

Get site entitlements

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

GET {server}/api/-/pulse/entitlements

view details

Get metric

Gets the details of the specified metric.

GET {server}/api/-/pulse/metrics/{metric_id}

view details

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.

POST {server}/api/-/pulse/metrics:getOrCreate

view details

List metric definitions

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

GET {server}/api/-/pulse/definitions

view details

List metrics in definition

Lists the metrics contained in a metric definition.

GET {server}/api/-/pulse/definitions/{definition_id}/metrics

view details

Update metric definition

Updates a metric definition.

PATCH {server}/api/-/pulse/definitions/{definition_id}

view details

Update metric

Updates the specification of a metric.

PATCH {server}/api/-/pulse/metrics/{metric_id}

view details

Generate current metric value insight bundle

Generates a bundle the current aggregated value for each metric.

POST {server}/api/-/pulse/insights/ban

view details

Generate detail insight bundle

Generates a detail insight bundle.

POST {server}/api/-/pulse/insights/detail

view details

Generate springboard insight bundle

Generates a springboard insight bundle.

POST {server}/api/-/pulse/insights/springboard

view details

Batch create subscriptions

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

POST {server}/api/-/pulse/subscriptions:batchCreate

view details

Batch get subscriber counts

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

GET {server}/api/-/pulse/subscriptions:batchGetMetricFollowerCounts

view details

Batch get subscriptions

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

GET {server}/api/-/pulse/subscriptions:batchGet

view details

Create subscription

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

POST {server}/api/-/pulse/subscriptions

view details

Delete subscription

Deletes a specified subscription to a metric.

DELETE {server}/api/-/pulse/subscriptions/{id}

view details

Get subscription

Gets a specified subscription to a metric.

GET {server}/api/-/pulse/subscriptions/{id}

view details

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.

GET {server}/api/-/pulse/metrics:followedMetricsGroups

view details

List subscriptions

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

GET {server}/api/-/pulse/subscriptions

view details