Execute Insight Analysis

Use this REST API to run Key Contributor Analysis or Variance Decomposition Analysis for a specified Insight.

Required Roles

Service Administrator

REST Resource

POST /HyperionPlanning/rest/v3/applications/{application}/insights/{insightId}/action/analyze

Request

Parameters:

Table 3-536 Request Parameters

Name Description Type Required Default
application The name of the application. path Yes None
insightId Insight UUID returned by the Insights API. path Yes None
includeGenAiSummary Include a generated narrative when available. query No false
fields Comma-separated paths within the selected summary, such as keyContributorAnalysisSummary.observed or vdaAnalysisSummary.decompositions.effects. Unsupported, malformed, and cross-method paths are ignored. If no path applies, the complete selected summary is returned. The summary wrapper is retained; VDA also retains decompositionForm and decompositions. query No None
insightAnalysisMethod KEY_CONTRIBUTOR_ANALYSIS or VARIANCE_DECOMPOSITION_ANALYSIS. The corresponding human-readable values Key Contributor Analysis and Variance Decomposition Analysis are also accepted. payload Yes None
relationshipType Required for VDA. Select Price Volume Mix, Margin, or FX/Constant currency. Compatibility aliases are PVM; MARGIN; and FX_CONSTANT_CURRENCY, FOREIGN_EXCHANGE, foreignExchange, or FX Constant currency, respectively. payload For VDA None
volume Account member name or alias for units or volume. payload Conditional None
price Account member name or alias for price or rate. payload Conditional None
decomposition A displayPath returned by persisted KCA, selecting one VDA decomposition scope. payload No None
fx Account member name or alias for the FX rate. payload For FX None
totalCost Account member name or alias for total cost. payload For Margin None

Send a JSON request body with Content-Type: application/json. Use HTTP Basic authentication. KCA accepts only insightAnalysisMethod; properties outside the selected request schema return HTTP 400.

For Price Volume Mix, supply volume or price, or both. For FX, supply fx and at least one of volume or price. For Margin, supply totalCost and at least two of volume, price, and grossRevenue. The VDA target account is derived from the persisted Insight and cannot be supplied.

The payload rows describe the fields in the following request examples. Other supported options and conditional requirements are described above.

Example request body — Key Contributor Analysis:

{
  "insightAnalysisMethod": "KEY_CONTRIBUTOR_ANALYSIS"
}

Example request body — Price Volume Mix:

{
  "insightAnalysisMethod": "VARIANCE_DECOMPOSITION_ANALYSIS",
  "relationshipType": "Price Volume Mix",
  "volume": "Units Sold",
  "price": "Selling Price USD",
  "decomposition": "USA"
}

Example request body — FX Constant Currency:

{
  "insightAnalysisMethod": "VARIANCE_DECOMPOSITION_ANALYSIS",
  "relationshipType": "FX/Constant currency",
  "fx": "FX Rates Average",
  "volume": "Units Sold",
  "price": "Selling Price USD"
}

Example request body — Margin:

{
  "insightAnalysisMethod": "VARIANCE_DECOMPOSITION_ANALYSIS",
  "relationshipType": "Margin",
  "totalCost": "Total COGS USD",
  "volume": "Units Sold",
  "price": "Selling Price USD"
}

Example URL

https://<BASE-URL>/HyperionPlanning/rest/v3/applications/Vision/insights/<insightId>/action/analyze?includeGenAiSummary=false&fields=keyContributorAnalysisSummary.observed%2CkeyContributorAnalysisSummary.expected

Response

Supported Media Types: application/json

Table 3-537 Key Contributor Analysis Parameters

Name Description
keyContributorAnalysisSummary KCA result containing the analyzed account and POV, observed and expected values, variance, contributor stages, chart data, and narrative.
keyContributorAnalysisSummary.analysisType The analysis representation returned by Key Contributor Analysis.
keyContributorAnalysisSummary.insightType The category of Insight used for the analysis.
keyContributorAnalysisSummary.accountMbr The account member analyzed by Key Contributor Analysis.
keyContributorAnalysisSummary.observed The formatted observed value for the parent Insight.
keyContributorAnalysisSummary.expected The formatted expected value for the parent Insight.
keyContributorAnalysisSummary.parentInsightAbsVariance The formatted absolute variance for the parent Insight.
keyContributorAnalysisSummary.parentInsightRelVariance The formatted percentage variance for the parent Insight.
keyContributorAnalysisSummary.pattern The classification of the contributor distribution.

Table 3-538 Variance Decomposition Analysis Parameters

Name Description
vdaAnalysisSummary VDA result for the selected relationship.
vdaAnalysisSummary.decompositionForm The decomposition model used for the analysis: Price Volume Mix, Margin, or FX/Constant currency.
vdaAnalysisSummary.decompositions Calculated decomposition results, including totals, effects, child contributions, reconciliation, chart data, completeness information, and narrative.
vdaAnalysisSummary.decompositions[].metric The account derived from the Insight for the selected decomposition.
vdaAnalysisSummary.decompositions[].currency The currency member used in the analyzed cell.
vdaAnalysisSummary.decompositions[].unitsLabel The volume account used in the decomposition.
vdaAnalysisSummary.decompositions[].level Indicates whether the decomposition applies to a leaf member or an aggregated parent.
vdaAnalysisSummary.decompositions[].comparisonType The comparison basis used by the calculation, such as forecast.
vdaAnalysisSummary.decompositions[].pattern The classification of the decomposition effect pattern.
vdaAnalysisSummary.decompositions[].totals The observed value, comparison value, and resulting variance.
vdaAnalysisSummary.decompositions[].totals.observed Observed value for the selected decomposition.
vdaAnalysisSummary.decompositions[].totals.comparison Comparison value for the selected decomposition.
vdaAnalysisSummary.decompositions[].totals.variance Observed value minus comparison value.
vdaAnalysisSummary.decompositions[].totals.variancePct Variance divided by the comparison value.
vdaAnalysisSummary.decompositions[].effects The calculated effect contributions to the reported variance.
vdaAnalysisSummary.decompositions[].effects[].name The name of the resource.
vdaAnalysisSummary.decompositions[].effects[].value The current value of the preference.
vdaAnalysisSummary.decompositions[].effects[].share Effect contribution divided by total variance.

Table 3-539 No Key Contributors Parameters

Name Description
details Localized informational message returned with HTTP 200 when KCA finds no key contributors.

Sample Response

Example Key Contributor Analysis response:

{
  "keyContributorAnalysisSummary": {
    "analysisType": "keyContributor",
    "insightType": "Anomaly",
    "accountMbr": "Units Sold",
    "observed": "2.83K",
    "expected": "2.13K",
    "parentInsightAbsVariance": "700.58",
    "parentInsightRelVariance": "32.9%",
    "pattern": "Concentrated"
  }
}

Example Variance Decomposition Analysis response:

{
  "vdaAnalysisSummary": {
    "decompositionForm": "Price Volume Mix",
    "decompositions": [
      {
        "metric": "Gross Revenue",
        "currency": "USD",
        "unitsLabel": "Units Sold",
        "level": "leaf",
        "comparisonType": "forecast",
        "pattern": "volume-dominated",
        "totals": {
          "observed": 1200000,
          "comparison": 1000000,
          "variance": 200000,
          "variancePct": 0.2
        },
        "effects": [
          {
            "name": "Volume",
            "value": 150000,
            "share": 0.75
          },
          {
            "name": "Price",
            "value": 50000,
            "share": 0.25
          }
        ]
      }
    ]
  }
}

Example No Key Contributors response:

{
  "details": "No Key Contributors are found for this Insight"
}