---
title: "Understanding the Response"
description: "Learn how a Portfolio X-Ray response is structured and what each top-level section contains."
url: "https://developer-beta.morningstar.com/portfolio-xray-api/response-structure"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~VW5kZXJzdGFuZGluZyB0aGUgUmVzcG9uc2UgfCBQb3J0Zm9saW8gWC1SYXkgQVBJ,description_Learn+how+a+Portfolio+X-Ray+response+is+structured+and+what+each+top-level+section+contains.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9wb3J0Zm9saW8teHJheS1hcGkvcmVzcG9uc2Utc3RydWN0dXJlIg,s_isO-y4lDWbGV75p7.png"
---

-   [APIs](https://developer-beta.morningstar.com/apis)
-   [API Catalog](https://developer-beta.morningstar.com/api-catalog)
-   [API Assistant MCP Server](https://developer-beta.morningstar.com/api-assistant-mcp)
-   [Guides](https://developer-beta.morningstar.com/api-guides)
-   [Trial Access](https://developer-beta.morningstar.com/trial-access)

# Portfolio X-Ray API

Build Portfolio X-Ray APIs into your digital experience for quick investment and earnings summaries.

# Response Structure

[View Markdown](https://developer-beta.morningstar.com/portfolio-xray-api/response-structure.md)[Download Markdown](https://developer-beta.morningstar.com/portfolio-xray-api/response-structure.md)

A successful request returns a JSON object with two arrays: `XRay`, which holds the analysis, and `SecurityReference`, which holds reference data for the securities involved. This page describes the structure at the section level. For field-level definitions, see the API reference.

```json
{
  "XRay": [
    {
      "PortfolioName": "ExamplePortfolio1",
      "AnalysisDate": "...",
      "ReturnMethodology": "QuickPortfolio",
      "PerformanceDate": { ... },
      "Analysis": { ... },
      "Holdings": { ... },
      "Statistics": { ... },
      "PortfolioBenchmark": { ... },
      "Returns": { ... },
      "SecurityFees": { ... },
      "Risks": { ... },
      "Ownership": { ... },
      "FinraHeader": { ... }
    }
  ],
  "SecurityReference": [ { ... } ]
}
```

-   `XRay` contains one object for each portfolio in the request. Use `PortfolioName` to identify each one.
-   `SecurityReference` contains identifying information for the securities, such as `SecurityId`, `CUSIP`, `ISIN` and `Name`.

## [Portfolio-Level Properties](#portfolio-level-properties)

Each `XRay` object starts with the following properties.

| Property          | Description                                                                      |
| :---------------- | :------------------------------------------------------------------------------- |
| PortfolioName     | The name of the portfolio, as provided in the request.                           |
| AnalysisDate      | The date of the analysis.                                                        |
| ReturnMethodology | The return methodology used in the calculation. The value is QuickPortfolio.     |
| PerformanceDate   | The key dates available for the portfolio: EarliestCommonDate, EarliestAvailableDate, EarliestInceptionDate and EarliestCommonExtendedDate. |

## [Response Sections](#response-sections)

The remaining properties of each `XRay` object are the analysis sections.

| Section            | What it contains                                                                 |
| :----------------- | :------------------------------------------------------------------------------- |
| Analysis           | How the portfolio is allocated and diversified: AssetAllocation, EquityAnalysis, FixedIncomeAnalysis and InvestmentStyle. AssetAllocation reports long, short and net positions by asset class, and the asset classes depend on the asset class group you selected. See Asset Class Group Breakdown. |
| Holdings           | Holdings-based views: RegionAnalysis, TopNetUnderlyingHoldings, PortfolioHoldings and StockIntersection, which shows overlapping equity holdings across the portfolio's funds. |
| Statistics         | PortfolioSummary, including the portfolio value and currency, and FundStatistics. |
| PortfolioBenchmark | The benchmark used for the analysis. Type is Standard, AutoAsset, AutoCategory or Custom, followed by the benchmark holdings and weights. |
| Returns            | TrailingReturns, CalendarYearReturn, RollingReturns, InvestmentActivity and SecurityReturns. |
| SecurityFees       | Fee data for each security in the portfolio.                                     |
| Risks              | RiskStatistics, MPTStatistics, CorrelationMatrix, Drawdown and CaptureRatio.     |
| Ownership          | Ownership zone data for equity holdings.                                         |
| FinraHeader        | The FINRA disclosure message, in Message.                                        |

## [What Affects the Response](#what-affects-the-response)

Several request options change what you receive.

-   **View.** The `View` property selects a predefined set of data points, so not every section appears in every response. If a section is missing, check the view. See [Configuring the Analysis](https://developer-beta.morningstar.com/portfolio-xray-api/configure-an-analysis#views).
-   **Optional data sections.** Rolling returns and the correlation matrix are returned only when you request them with `ReturnDataSections`. Rolling returns also require `RollingReturnFrequencies`.
-   **Gross and net returns.** Set `IncludeGrossNetReturns` to `true` to receive both values in trailing returns and calendar year returns.
-   **Asset class group.** The `AssetClassGroupConfigs` setting determines the asset classes used in `AssetAllocation`. The response returns the group identifier in the `Id` property. See [Asset Class Group Breakdown](https://developer-beta.morningstar.com/portfolio-xray-api/asset-class-group-breakdown).
-   **Analysis period.** The start and end date settings determine the period covered by returns and risk data. `PerformanceDate` shows the dates available for the portfolio.
-   **Locale.** The `langcult` query parameter sets the language and locale of the response.

## [Working With Two Portfolios](#working-with-two-portfolios)

When a request contains two portfolios, `XRay` contains two objects, one per portfolio. `SecurityReference` is a single array for the whole response. See [Compare Two Portfolios](https://developer-beta.morningstar.com/portfolio-xray-api/compare-two-portfolios).

## [Field-Level Detail](#field-level-detail)

Each section contains many nested objects, including data for the portfolio, the benchmark and individual securities. For definitions of every field, see the Portfolio X-Ray API reference.