---
title: "Request Structure"
description: "The structure and rules of a Portfolio X-Ray request: portfolios, holding identifiers, position sizes, currencies and fees."
url: "https://developer-beta.morningstar.com/portfolio-xray-api/request-structure"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~UmVxdWVzdCBTdHJ1Y3R1cmUgfCBQb3J0Zm9saW8gWC1SYXkgQVBJ,description_~VGhlIHN0cnVjdHVyZSBhbmQgcnVsZXMgb2YgYSBQb3J0Zm9saW8gWC1SYXkgcmVxdWVzdDogcG9ydGZvbGlvcywgaG9sZGluZyBpZGVudGlmaWVycywgcG9zaXRpb24gc2l6ZXMsIGN1cnJlbmNpZXMgYW5kIGZlZXMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9wb3J0Zm9saW8teHJheS1hcGkvcmVxdWVzdC1zdHJ1Y3R1cmUi,s_i998weqPLTdpLpNO.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.

# Request Structure

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

A Portfolio X-Ray request describes the portfolios you want to analyze and the settings that control the analysis. This page explains the structure of the request body and the rules for the portfolio portion of it: how holdings are identified, how positions are sized, and how fees are applied. For the settings that control the analysis itself, see [Configuring the Analysis](https://developer-beta.morningstar.com/portfolio-xray-api/configure-an-analysis).

## [Top-Level Properties](#top-level-properties)

The request body is a JSON object with the following top-level properties.

| Property        | Required | Description                                                                      |
| :-------------- | :------- | :------------------------------------------------------------------------------- |
| Portfolios      | Yes      | An array of one or two portfolios to analyze.                                    |
| RequestSettings | Yes      | Analysis settings such as output currency, date range and optional data sections. |
| View            | No       | The predefined set of data points to return. Defaults to All.                    |
| Config          | No       | An account-specific configuration preset. Defaults to Default.                   |

## [Request Limits](#request-limits)

-   A request can include a maximum of **2 portfolios**.
-   Each portfolio can contain a maximum of **250 holdings**.

## [Defining a Portfolio](#defining-a-portfolio)

Each object in the `Portfolios` array has the following properties.

| Property   | Required    | Description                                                                      |
| :--------- | :---------- | :------------------------------------------------------------------------------- |
| Name       | Yes         | The portfolio name. The name is returned in the response as PortfolioName.       |
| Currency   | Yes         | The portfolio currency, as an ISO 4217 code. See Supported currencies.           |
| Holdings   | Yes         | An array of 1 to 250 holdings.                                                   |
| TotalValue | Conditional | The total market value of the portfolio in the portfolio currency. Required when holdings use Weight. Minimum 1. |
| Fees       | No          | Portfolio-level annual fee. See Adding fees.                                     |
| IrrFees    | No          | The annual fee used in the internal rate of return calculation.                  |

## [Identifying Holdings](#identifying-holdings)

Each holding must include one security identifier. The following identifiers are supported.

| Identifier    | Description                                  | Example      |
| :------------ | :------------------------------------------- | :----------- |
| SecurityId    | Morningstar unique identifier of a security. | FOUSA00DFS   |
| CUSIP         | The security's CUSIP.                        | 09251T103    |
| ISIN          | The security's ISIN.                         | US0378331005 |
| PerformanceId | The security's Morningstar Performance ID.   | 0P00002QN3   |
| TradingSymbol | The security's ticker or trading symbol.     | MDLOX        |
| FundCode      | The security's fund code.                    | ABG          |

You can mix identifier types across holdings in the same portfolio. For example, one holding can use `TradingSymbol` and another can use `ISIN`.

If you provide more than one identifier for a single holding, `SecurityId` takes priority. If `SecurityId` is absent, the last identifier listed in the object is used. To avoid ambiguity, provide one identifier per holding.

To include a cash position, use the `SecurityId` value `CASH%0.000`.

## [Sizing Positions](#sizing-positions)

Each holding must also include a position size, expressed as either `Weight` or `Value`. The position size type must be the same for every holding in a portfolio. You can use `Weight` in one portfolio and `Value` in another.

| Position size | Rules                                                                            |
| :------------ | :------------------------------------------------------------------------------- |
| Weight        | A percentage of the portfolio, from 1 to 100. Weights across all holdings must sum to 100. TotalValue is required on the portfolio. |
| Value         | The market value of the holding in the portfolio currency. Minimum 1. Values across all holdings must equal the portfolio's TotalValue. |

## [Supported Currencies](#supported-currencies)

The portfolio `Currency` accepts the following 19 ISO 4217 codes: `AUD`, `BRL`, `CAD`, `CHF`, `DKK`, `EUR`, `GBP`, `HKD`, `INR`, `JPY`, `MXN`, `MYR`, `NOK`, `NZD`, `SEK`, `SGD`, `TWD`, `USD` and `ZAR`.

The same set of currencies is supported for `OutputCurrency` in the request settings.

## [Adding Fees](#adding-fees)

You can apply an annual fee to an entire portfolio, to individual holdings, or both.

| Property           | Level                               | Description                                                                      |
| :----------------- | :---------------------------------- | :------------------------------------------------------------------------------- |
| AnnualFeePercent   | Portfolio (inside Fees) and holding | The annual fee as a percentage of value. For example, 1.15 represents 1.15%. Defaults to 0. |
| AnnualFeeFrequency | Portfolio (inside Fees) and holding | How often the fee is deducted: Monthly, Quarterly, SemiAnnually or Annually. Defaults to Monthly. |

Use `IrrFees` on the portfolio to set the annual fee used in the internal rate of return calculation.

## [Example Portfolio](#example-portfolio)

The following portfolio uses `Weight` for position sizes, mixes a trading symbol with a cash position, and applies a portfolio-level fee.

```json
{
  "Name": "ExamplePortfolio1",
  "Currency": "USD",
  "TotalValue": 50000,
  "Holdings": [
    { "TradingSymbol": "SPY", "Weight": 40 },
    { "TradingSymbol": "AGG", "Weight": 30 },
    { "TradingSymbol": "QQQ", "Weight": 20 },
    { "SecurityId": "CASH%0.000", "Weight": 10 }
  ],
  "Fees": {
    "AnnualFeePercent": 0.5,
    "AnnualFeeFrequency": "Monthly"
  }
}
```

To send this portfolio, add it to the `Portfolios` array along with the required `RequestSettings`. See [Request Portfolio X-Ray](https://developer-beta.morningstar.com/portfolio-xray-api/request-portfolio-xray) for a complete request.