--- title: "FAQs" description: "Answers to common questions about Portfolio X-Ray API limits, holdings, position sizes, analysis settings and responses." url: "https://developer-beta.morningstar.com/portfolio-xray-api/faqs" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RkFRcyB8IFBvcnRmb2xpbyBYLVJheSBBUEk,description_~QW5zd2VycyB0byBjb21tb24gcXVlc3Rpb25zIGFib3V0IFBvcnRmb2xpbyBYLVJheSBBUEkgbGltaXRzLCBob2xkaW5ncywgcG9zaXRpb24gc2l6ZXMsIGFuYWx5c2lzIHNldHRpbmdzIGFuZCByZXNwb25zZXMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9wb3J0Zm9saW8teHJheS1hcGkvZmFxcyI,s_NjAXB5PX5eSDBn20.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. # FAQs [View Markdown](https://developer-beta.morningstar.com/portfolio-xray-api/faqs.md)[Download Markdown](https://developer-beta.morningstar.com/portfolio-xray-api/faqs.md) Answers to common questions about the Portfolio X-Ray API. If a request fails or returns unexpected results, see [Troubleshooting](https://developer-beta.morningstar.com/portfolio-xray-api/troubleshooting). ## [General](#general) What does the Portfolio X-Ray API do? 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. Which endpoint do I call? 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). Is the API synchronous? Yes. The analysis is returned in the response to the same request. Do I need a licence to use the API? 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. Should I use this API to analyze a single investment? 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). ## [Authentication](#authentication) How do I authenticate? 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). How long does an access token last? 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\`. ## [Limits](#limits) How many portfolios can I send in one request? A maximum of 2. To analyze more portfolios, split them across multiple requests. How many holdings can a portfolio contain? Each portfolio can contain between 1 and 250 holdings. Portfolios with more positions must be consolidated before you submit them. Which currencies are supported? 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\`. Which languages and locales can the response use? 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. ## [Holdings and Position Sizes](#holdings-and-position-sizes) Which identifiers can I use for holdings? \`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. What happens if I give a holding more than one identifier? \`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. How do I include cash? Add a holding with the \`SecurityId\` value \`CASH%0.000\`. \`\`\`json { "SecurityId": "CASH%0.000", "Weight": 10 } \`\`\` Should I use \`Weight\` or \`Value\`? 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). Can two portfolios in the same request use different position size types? Yes. One portfolio can use \`Weight\` while the other uses \`Value\`. They can also use different identifier types, total values and fees. What happens to holdings that are invalid or that I'm not entitled to? 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\`. ## [Fees](#fees) Can I model fees? 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\`. How do I get both gross and net returns? Set \`IncludeGrossNetReturns\` to \`true\` in \`RequestSettings\`. Trailing returns and calendar year returns then include both values. What is \`IrrFees\`? A portfolio-level property that sets the annual fee used in the internal rate of return calculation. ## [Configuring the Analysis](#configuring-the-analysis) What is the minimum I need in \`RequestSettings\`? Only \`OutputCurrency\` is required. All other settings have defaults. See \[Configure an Analysis\](/portfolio-xray-api/configure-an-analysis). What period does the analysis cover by default? 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. How do I set a custom date range? 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" } \`\`\` How do I make two portfolios cover the same period? 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). How do I get rolling returns or a correlation matrix? 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. What is a view? 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. What is an asset class group? 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). ## [Responses](#responses) How is the response structured? 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). How do I tell which date range was used? Check \`PerformanceDate\` in each \`XRay\` object. It returns \`EarliestCommonDate\`, \`EarliestAvailableDate\`, \`EarliestInceptionDate\` and \`EarliestCommonExtendedDate\` for the portfolio. What return methodology does the API use? \`QuickPortfolio\`. The value is returned in \`ReturnMethodology\`. Where can I see which funds hold the same stocks? In \`Holdings.StockIntersection\`, which shows overlapping equity holdings across the portfolio's funds.