--- title: "Overview" description: "Overview of the Portfolio X-Ray API." url: "https://developer-beta.morningstar.com/portfolio-xray-api" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~T3ZlcnZpZXcgfCBQb3J0Zm9saW8gWC1SYXkgQVBJ,description_Overview+of+the+Portfolio+X-Ray+API.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9wb3J0Zm9saW8teHJheS1hcGki,s_dWEXXhrmTuya2Fin.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. # About [View Markdown](https://developer-beta.morningstar.com/portfolio-xray-api.md)[Download Markdown](https://developer-beta.morningstar.com/portfolio-xray-api.md) Understanding what a portfolio actually holds — its allocation, exposure, and risk, not just its list of positions — is central to advice, client reporting, and ongoing oversight. The API serves product owners and platform teams building client-facing portfolio tools, and advisor and research teams reviewing portfolio structure, by aggregating holdings and applying Morningstar's underlying holdings and classification data on demand, without maintaining a portfolio analytics engine in-house. **Looking for a single investment instead of a portfolio?** For allocation, exposure, or risk data on one investment at a time, use the [Investment List API](https://developer-beta.morningstar.com/investment-list-api) or [Time Series API](https://developer-beta.morningstar.com/time-series-api). ## [Common Use Cases](#common-use-cases) - **Show clients what they own** Break a client portfolio down into asset allocation, sector, and regional exposure for an advisor dashboard or client report. - **Diagnose overlap and concentration** Compare holdings across a portfolio's underlying funds to surface overlapping positions and concentration risk. - **Report risk and performance together** Pair trailing and calendar-year returns with risk statistics — Sharpe ratio, standard deviation, alpha, beta, drawdown, and capture ratios — in one response. - **Compare two portfolios side by side** Submit a current and a proposed portfolio in the same request to evaluate a rebalance or a switch before it happens. ## [Capabilities](#capabilities) - **Multi-portfolio requests** Submit up to 2 portfolios in a single request, each with up to 250 holdings, identified by security ID, CUSIP, fund code, ISIN, performance ID, or trading symbol. - **Equity and fixed income analysis** Equity exposure across sector, world region, market maturity, style box, price ratios, and profitability; fixed income exposure across sector, maturity distribution, credit quality, and interest rate risk. - **Risk statistics** Sharpe ratio, standard deviation, alpha, beta, drawdown, and capture ratios, calculated at the portfolio level. - **Returns** Trailing and calendar-year returns, with optional rolling returns and correlation matrices across the submitted portfolios. - **Fee modelling** Apply portfolio-level or holding-level annual fees to model net-of-fee performance alongside gross returns. - **Configurable output views** Select from predefined view presets to control which blocks of analysis are returned, instead of receiving the full response every time. ## [Limits](#limits) - **2 portfolios per request** Larger comparisons must be split across multiple requests. - **250 holdings per portfolio** Portfolios with more positions must be consolidated before submission. - **One position size field per portfolio** Holdings are sized by either `Weight` or `Value`, uniformly across the whole portfolio; `Weight`\-based portfolios must also supply `TotalValue`. - **Identifier priority** If more than one identifier is supplied for a holding, `SecurityId` takes priority; otherwise the last identifier listed on the holding is used. - **Unmatched or unentitled holdings** Holdings that can't be resolved or aren't covered by your entitlement are surfaced in the `SecurityReference` block rather than failing the whole request. - **Token lifetime** Access tokens last 60 minutes, so long-running jobs must refresh tokens and retry requests that return `401 Unauthorized`. ## [Access](#access) - **Licence Required** Yes. Where access depends on your agreement, your Morningstar account manager can confirm what's included. - **Self-Serve Trial Access** See [Trial Access](https://developer-beta.morningstar.com/trial-access) to check current eligibility for the Portfolio X-Ray API. ## [Looking for Something Else?](#looking-for-something-else) - **A fixed list of investments and their current values** [Investment List API](https://developer-beta.morningstar.com/investment-list-api) - **How a value has changed over time** [Time Series API](https://developer-beta.morningstar.com/time-series-api) - **A detailed profile for a single investment** [Investment Details API](https://developer-beta.morningstar.com/investment-details-api) - **Detailed profiles for up to 250 investments at once** [Investment Details Feed API](https://developer-beta.morningstar.com/investment-details-feed-api)