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"
}