FAQs
Answers to common questions about the Portfolio X-Ray API. If a request fails or returns unexpected results, see Troubleshooting.
It analyzes one or two portfolios and returns how each is diversified by region, sector and investment style, along with holdings, performance, risk and fee analysis. Morningstar's underlying holdings and classification data is aggregated up to the portfolio level, so you don't need to maintain a portfolio analytics engine of your own.
Every request uses a single endpoint: `POST /portfolioanalysis/v1/xray`. Use the base URL for your region.
| Region | Base URL |
|---|---|
| Americas | `https://www.us-api.morningstar.com` |
| APAC | `https://www.apac-api.morningstar.com` |
| EMEA | `https://www.emea-api.morningstar.com` |
See [Request Portfolio X-Ray](/portfolio-xray-api/request-portfolio-xray).
Yes. The analysis is returned in the response to the same request.
Yes. Access depends on your agreement, and your Morningstar account manager can confirm what's included. See [Trial Accounts](/trial-access) to check whether self-serve trial access is available.
No. For allocation, exposure or risk data on one investment at a time, use the [Investment List API](/investment-list-api) or the [Time Series API](/time-series-api).
The API uses OAuth 2.0. Request an access token from the Authentication API using `POST /token/oauth`, and send it in the `Authorization` header as `Bearer {token}`. See [Authentication](/api-authentication).
Tokens are valid for 60 minutes and can be reused across requests during that time. Long-running jobs must refresh the token and retry any request that returns `401 Unauthorized`.
A maximum of 2. To analyze more portfolios, split them across multiple requests.
Each portfolio can contain between 1 and 250 holdings. Portfolios with more positions must be consolidated before you submit them.
Both the portfolio `Currency` and the `OutputCurrency` setting accept the same 19 ISO 4217 codes: `AUD`, `BRL`, `CAD`, `CHF`, `DKK`, `EUR`, `GBP`, `HKD`, `INR`, `JPY`, `MXN`, `MYR`, `NOK`, `NZD`, `SEK`, `SGD`, `TWD`, `USD` and `ZAR`.
Set the `langcult` query parameter to `en-US`, `en-CA`, `en-AU` or `en-GB`. The default is `en-US`. `langcult` overrides the `Accept-Language` header.
`SecurityId`, `CUSIP`, `ISIN`, `PerformanceId`, `TradingSymbol` and `FundCode`. You can mix identifier types across holdings in the same portfolio. To find Performance IDs for investments in your entitled universe, use the Universe API.
`SecurityId` takes priority. If `SecurityId` is absent, the last identifier listed in the holding object is used. To avoid ambiguity, provide one identifier per holding.
Add a holding with the `SecurityId` value `CASH%0.000`.
```json
{ "SecurityId": "CASH%0.000", "Weight": 10 }
```
Either, but every holding in a portfolio must use the same one.
- **`Weight`** is a percentage from 1 to 100. Weights must sum to 100, and you must also set `TotalValue` on the portfolio.
- **`Value`** is the market value of the holding in the portfolio currency, with a minimum of 1. Values must sum to the portfolio's `TotalValue`.
See [Request Structure](/portfolio-xray-api/request-structure#sizing-positions).
Yes. One portfolio can use `Weight` while the other uses `Value`. They can also use different identifier types, total values and fees.
By default, the API analyzes the remaining holdings and rescales their weights. To receive an error that lists each invalid or unentitled holding instead, set `DisableRescale` to `true` in `RequestSettings`.
Yes. You can apply an annual fee to the whole portfolio (in the portfolio's `Fees` object), to individual holdings, or both. Use `AnnualFeePercent` for the rate (for example, `1.15` is 1.15%) and `AnnualFeeFrequency` for how often it is deducted: `Monthly` (default), `Quarterly`, `SemiAnnually` or `Annually`.
Set `IncludeGrossNetReturns` to `true` in `RequestSettings`. Trailing returns and calendar year returns then include both values.
A portfolio-level property that sets the annual fee used in the internal rate of return calculation.
Only `OutputCurrency` is required. All other settings have defaults. See [Configure an Analysis](/portfolio-xray-api/configure-an-analysis).
The analysis starts at `EarliestCommon`, the earliest date for which all holdings have return data, and ends at the most recent month end (`AnalysisDateTimePeriod` is `MonthEnd`). Performance is calculated monthly.
Set `PortfolioPerformanceStartDate` to `CustomDate` and provide `PortfolioPerformanceCustomStartDate`. For the end date, set `AnalysisDateTimePeriod` to `CustomDate` and provide `PortfolioPerformanceEndDate`. Both dates use the `YYYY-MM-DD` format.
```json
"RequestSettings": {
"OutputCurrency": "USD",
"PortfolioPerformanceStartDate": "CustomDate",
"PortfolioPerformanceCustomStartDate": "2020-01-31",
"AnalysisDateTimePeriod": "CustomDate",
"PortfolioPerformanceEndDate": "2024-12-31"
}
```
By default, each portfolio is analyzed over the period determined by its own holdings. Set `SynchronizePortfolioStartDate` to `true` to use the latest common start date for both portfolios, and `EnablePerformanceCommonEndDate` to `true` to use the most recent common end date. See [Compare Two Portfolios](/portfolio-xray-api/compare-two-portfolios).
Add them to `ReturnDataSections`. Rolling returns also require `RollingReturnFrequencies`.
```json
"ReturnDataSections": ["RollingReturns", "CorrelationMatrix"],
"RollingReturnFrequencies": ["Year1", "Year3", "Year5"]
```
The correlation matrix includes up to 50 holdings by default. Use `MaxCorrelationMatrixHoldingNumber` (2 to 50) to reduce this, and `IncludePortfolioInCorrelationMatrix` to add the portfolio itself as an entry.
The `View` property selects a predefined set of data points to return. Supported IDs are `All` (default), `Default`, `Intersection`, `Operation`, `Portfolio`, `StockIntersection`, `XrayOverview` and `Snapshot`. Use a narrower view when you don't need the full response.
The classification scheme used to break down `AssetAllocation`. Set it with `AssetClassGroupConfigs` in `RequestSettings`. You can pass one group per request, and the default is `ACG-USBROAD`. See [Asset Class Group Breakdown](/portfolio-xray-api/asset-class-group-breakdown).
A successful response contains two arrays. `XRay` has one object per portfolio, identified by `PortfolioName`. `SecurityReference` holds identifying information for the securities in all portfolios. See [Response Structure](/portfolio-xray-api/response-structure#response-structure).
Check `PerformanceDate` in each `XRay` object. It returns `EarliestCommonDate`, `EarliestAvailableDate`, `EarliestInceptionDate` and `EarliestCommonExtendedDate` for the portfolio.
`QuickPortfolio`. The value is returned in `ReturnMethodology`.
In `Holdings.StockIntersection`, which shows overlapping equity holdings across the portfolio's funds.