Skip to main content

Generate Pulse Metric Value Insight Bundle

Available June 2026 and later.

Generates an insight bundle for the current aggregated value of a Pulse metric. You supply the full Pulse metric and Pulse metric definition information (most of it comes from data returned by the other Pulse tools). The bundleType argument selects which bundle shape is generated:

  • ban (default) — current aggregated value, period-over-period change, and the highest-ranked insight for each filterable dimension
  • basic — like a springboard insight, but focused on low-bandwidth dimensions with small value sets
  • springboard — current value, period-over-period change, and the highest-ranked insight for the metric
  • detail — performance over time, a summary visualization of highs, lows, and trends, per-dimension top-contributor breakdowns, and follow-up insights
  • exploration — performance trends with BAN, anchor, and follow-up insight groups

APIs called​

Talks to the Tableau REST API (Tableau Cloud or Server) Pulse Insights service. A single call generates the requested bundle, with bundleType selecting the bundle shape via the route's path segment. This tool is gated by the tableau:mcp:insight:create MCP scope; the union of Tableau API scopes it uses is tableau:insights:read and tableau:mcp_site_settings:read.

  • Generate the insight bundle for the metric's current aggregated value. Issued against the Tableau REST API Pulse Insights service; requires the tableau:insights:read OAuth scope (tableau:mcp_site_settings:read is also used to read per-site MCP configuration).
    • POST /api/-/pulse/insights/{bundleType} — generate the requested bundle; {bundleType} (ban, basic, springboard, detail, or exploration) selects the shape. Pulse is served at the fixed /api/- base, not a {version} path. Per-type references: BAN, Basic, Springboard, Detail, Exploration

Required arguments​

bundleRequest​

The request to generate a bundle for. Most of the information comes from data returned by the tools that retrieve Pulse metric and Pulse metric definition information. When building the request, set options using output_format: 'OUTPUT_FORMAT_HTML', time_zone: 'UTC', language: 'LANGUAGE_EN_US', and locale: 'LOCALE_EN_US'.

The datasource field under metric.definition requires an id (datasource LUID) and accepts an optional id_type: omit id_type for standard published datasources (default), or use 'DATASOURCE_ID_TYPE_WORKBOOK_DATASOURCE' when the metric is based on an embedded workbook datasource rather than a published one.

Anchoring the analysis to a specific date​

Set options.now to anchor the analysis to a specific date instead of the current date, so the bundle can target a past whole period rather than only today-relative windows. Format is 'YYYY-MM-DD' (or 'YYYY-MM-DD HH:MM:SS', 24-hour). To analyze a specific past month, set now to the last day of that month with measurement_period.range = 'RANGE_CURRENT_PARTIAL' and granularity = 'GRANULARITY_BY_MONTH' (e.g. now: '2026-05-31' yields the full month of May 2026); note that RANGE_LAST_COMPLETE targets the period before the anchor's period, not the anchor's own. This shifts only the whole-period window. When now is set, time_zone is ignored; omit it (or use an empty string) for today-relative analysis.

Targeting an explicit period or custom date range​

To target an explicit period or an arbitrary date range, set measurement_period.range to 'RANGE_BY_CONFIG' and provide measurement_period.specific_period. This is the only way to analyze a custom span (e.g. April 15-20). measurement_period.specific_period is only honored when measurement_period.range is 'RANGE_BY_CONFIG' (the refusal names the range it received); set outside it, the request is refused rather than silently analyzed for another period. For a today-relative window drop specific_period; to analyze the explicit period or span, set range to 'RANGE_BY_CONFIG'. options.now and measurement_period.specific_period cannot both be set — they are alternative ways to target a period. Use options.now to anchor a relative whole period, or specific_period (with range RANGE_BY_CONFIG) for an explicit period or span.

  • { "date": "YYYY-MM-DD" } — the single period (at the chosen granularity) that contains that date. E.g. GRANULARITY_BY_MONTH + date: '2026-05-10' is the month of May 2026.
  • { "date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD" } — a span from the start of date's period through the end of end_date's period. E.g. GRANULARITY_BY_DAY + date: '2026-04-15', end_date: '2026-04-20' is April 15-20, 2026.

Rolling windows​

Use measurement_period.last_x_period for a rolling window instead of a fixed span. The same fail-closed checks apply as for specific_period, so an unsupported combination is refused rather than analyzed for a different period:

  • measurement_period.last_x_period is only honored when measurement_period.range is 'RANGE_BY_CONFIG' — the refusal names the range it received.
  • measurement_period.last_x_period and measurement_period.specific_period cannot both be set — use last_x_period for a supported rolling window or specific_period for a fixed span.
  • a day-based measurement_period.last_x_period requires measurement_period.granularity = 'GRANULARITY_BY_DAY'.
  • the trailing-year measurement_period.last_x_period requires measurement_period.granularity = 'GRANULARITY_BY_MONTH'.
  • options.now and measurement_period.last_x_period cannot both be set — rolling windows are relative to the live data offset, so anchoring the analysis to another date has no meaning for them.

Example​

{
"bundle_request": {
"version": 1,
"options": {
"output_format": "OUTPUT_FORMAT_HTML",
"time_zone": "UTC",
"language": "LANGUAGE_EN_US",
"locale": "LOCALE_EN_US"
},
"input": {
"metadata": {
"name": "Pulse Metric",
"metric_id": "fd6c4aa0-f6d3-469e-b75b-d597435ae199",
"definition_id": "9ad098f4-49cf-4e8a-bec0-0ca803091dd0"
},
"metric": {
"definition": {
"datasource": {
"id": "2d935df8-fe7e-4fd8-bb14-35eb4ba31d45"
},
"basic_specification": {
"measure": {
"field": "Sales",
"aggregation": "AGGREGATION_SUM"
},
"time_dimension": {
"field": "Order Date"
},
"filters": []
},
"is_running_total": false
},
"metric_specification": {
"filters": [],
"measurement_period": {
"granularity": "GRANULARITY_BY_QUARTER",
"range": "RANGE_LAST_COMPLETE"
},
"comparison": {
"comparison": "TIME_COMPARISON_PREVIOUS_PERIOD"
}
},
"extension_options": {
"allowed_dimensions": [],
"allowed_granularities": [],
"offset_from_today": 0
},
"representation_options": {
"type": "NUMBER_FORMAT_TYPE_NUMBER",
"number_units": {
"singular_noun": "unit",
"plural_noun": "units"
},
"sentiment_type": "SENTIMENT_TYPE_NONE",
"row_level_id_field": {
"identifier_col": "Order ID",
"identifier_label": ""
},
"row_level_entity_names": {
"entity_name_singular": "Order"
},
"row_level_name_field": {
"name_col": "Order Name"
},
"currency_code": "CURRENCY_CODE_USD"
},
"insights_options": {
"show_insights": true,
"settings": []
},
"goals": {
"target": {
"value": 100
}
}
}
}
}
}
Datasource scoping

When the server is configured to limit which data sources may be queried, the metric's metric.definition.datasource.id must be within that allowed set; otherwise the tool refuses the request.

Refusals

The tool refuses the request before calling Pulse when any of the following is true. version must be 1 includes the version that was sent.

  • version must be 1 (got <version>).
  • basic_specification.measure.field is empty.
  • basic_specification.time_dimension.field is required when measurement_period.range and comparison are specified.
  • definition.datasource.id is empty.
  • is_running_total cannot be true with AGGREGATION_USER.
  • metric_specification.comparison.comparison must be set (e.g., TIME_COMPARISON_PREVIOUS_PERIOD, TIME_COMPARISON_YEAR_AGO_PERIOD).
  • metric_specification.measurement_period.granularity must be set (e.g., GRANULARITY_BY_DAY, GRANULARITY_BY_WEEK, GRANULARITY_BY_MONTH).
  • metric_specification.measurement_period.range must be set (e.g., RANGE_CURRENT_PARTIAL, RANGE_LAST_COMPLETE).

Optional arguments​

bundleType​

The type of bundle to generate. Defaults to ban.

ValueDescription
banReturn a basic insight bundle with the current aggregated value for the Pulse Metric, period over period change, and the highest ranked insight for each filterable dimension of the metric.
basicReturn a basic insight bundle. 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.
springboardReturn a springboard insight bundle with the current value, period over period change, and the highest ranked insight for the metric.
detailShows 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.
explorationReturn an exploration insight bundle focused on performance trends, with BAN, anchor, and follow-up insight groups. Available in API 3.26 (Tableau Cloud September 2025) and later. Not available for Tableau Server.

verbosity​

Controls how much of the response is returned. Defaults to full.

  • full — returns the response verbatim, including viz
  • slim — strips the large viz (Vega chart-spec) blobs from every insight and summary result

Example result​

{
"bundle_response": {
"result": {
"insight_groups": [
{
"type": "ban",
"insights": [
{
"result": {
"type": "popc",
"version": 1,
"content": "",
"markup": "<span data-type=\"metric\">Pulse Metric</span> was 135.0K units (Q2 2025), <span data-type=\"insight-type-keyword\">up 7.7%</span> (9.7K units) compared to the prior quarter (Q1 2025).",
"facts": {
"sentiment": "neutral",
"is_custom_comparison": false,
"result_hash": "+lA+/F4el3Q7+N5E3ERLYSwJ1fnexyT/ISrrAXrGcxY=",
"target_period_value": {
"raw": 134990.59600000002,
"formatted": "135.0K"
},
"comparison_period_value": {
"raw": 125288.82819999992,
"formatted": "125.3K"
},
"target_time_period": {
"range": "Q2 2025",
"label": "Q2 2025",
"granularity": "quarter",
"start_timestamp": "2025-04-01T00:00:00Z",
"end_timestamp": "2025-07-01T00:00:00Z"
},
"comparison_time_period": {
"granularity": "quarter",
"start_timestamp": "2025-01-01T00:00:00Z",
"end_timestamp": "2025-04-01T00:00:00Z",
"range": "Q1 2025",
"label": "Q1 2025"
},
"difference": {
"absolute": {
"raw": 9701.767800000103,
"formatted": "9.7K"
},
"relative": {
"raw": 0.07743521860155853,
"formatted": "7.7%"
},
"direction": "up"
}
},
"characterization": "CHARACTERIZATION_UNSPECIFIED",
"question": "How did Pulse Metric change from Q1 2025 to Q2 2025?",
"score": 0
},
"insight_type": "popc"
}
],
"summaries": []
},
{
"type": "top",
"insights": [
{
"result": {
"type": "unusualchange",
"version": 1,
"content": "",
"markup": "<span data-type=\"metric\">Pulse Metric</span> in Q2 2025 was 135.0K units and was <span data-type=\"insight-type-keyword\">within the expected range</span> of 109.6K units to 175.7K units considering seasonal patterns.",
"facts": {
"sentiment": "neutral",
"last_complete_period": {
"granularity": "quarter",
"start_timestamp": "2025-04-01T00:00:00Z",
"end_timestamp": "2025-07-01T00:00:00Z",
"range": "Q2 2025",
"label": "Q2 2025"
},
"unusual_change_type": "notunusual",
"result_hash": "F4hh0qhCnU+hQkqqWFAyzFKngGalVQDZdO7raxcDOnU=",
"direction": "flat",
"value": {
"raw": 134990.59600000002,
"formatted": "135.0K"
},
"value_change": {
"relative": {
"raw": 0.07743521860155853,
"formatted": "7.7%"
},
"direction": "up",
"absolute": {
"formatted": "9.7K",
"raw": 9701.767800000103
}
},
"expected_value_change": {
"raw": 17353.50481379211,
"formatted": "17.4K"
}
},
"characterization": "CHARACTERIZATION_UNSPECIFIED",
"question": "Is this change unexpected?",
"score": 0.4333333333333333
},
"insight_type": "unusualchange"
}
],
"summaries": []
},
{
"type": "timely",
"insights": [],
"summaries": []
}
],
"has_errors": false,
"characterization": "CHARACTERIZATION_UNSPECIFIED"
}
}
}
Trimmed for readability

The example above omits the large viz (Vega-Lite chart-spec) blobs that a full response returns for each insight and summary. Pass verbosity: 'slim' to strip those blobs from the actual response.

Arguments no longer accepted​

These arguments were described on an earlier page and are not accepted by the current tool.

slim​

Deprecated: use verbosity=slim.