---
title: "API Inputs"
description: "Input fields for the Portfolio X-Ray API."
url: "https://developer-beta.morningstar.com/portfolio-xray-api/api-inputs"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~QVBJIElucHV0cyB8IFBvcnRmb2xpbyBYLVJheSBBUEk,description_Input+fields+for+the+Portfolio+X-Ray+API.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9wb3J0Zm9saW8teHJheS1hcGkvYXBpLWlucHV0cyI,s_s9xxgwP7A2ot086H.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.

# API Inputs

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

## [Request Inputs](#request-inputs)

This API generates an x-ray of one or two portfolios in a single request (`POST /portfolioanalysis/v1/xray`). The x-ray shows how each portfolio is diversified by region, sector, and investment style. Inputs are passed in the JSON request body, except `langcult`, which is a query parameter.

A maximum of 2 portfolios can be passed per request, with a maximum of 250 holdings per portfolio. The request body has four top-level fields. `Portfolios` and `RequestSettings` are required. Their inputs are described in the following sections:

-   [Request Settings Inputs](#request-settings-inputs)
-   [Portfolio Inputs](#portfolio-inputs)
-   [Holding Inputs](#holding-inputs)
-   [Fee Inputs](#fee-inputs)

```json
{
  "View": { "Id": "All" },
  "RequestSettings": {
    "OutputCurrency": "USD",
    "AnalysisDateTimePeriod": "MonthEnd",
    "PortfolioPerformanceStartDate": "EarliestCommon"
  },
  "Portfolios": [
    {
      "Name": "ExamplePortfolio1",
      "Currency": "USD",
      "TotalValue": 50000,
      "Holdings": [
        { "TradingSymbol": "SPY", "Weight": 40 },
        { "ISIN": "US0378331005", "Weight": 50 },
        { "SecurityId": "CASH%0.000", "Weight": 10 }
      ]
    }
  ]
}
```

### [Config](#config)

| Attribute       | Value                               |
| :-------------- | :---------------------------------- |
| Type            | Request Payload                     |
| Data Type       | object                              |
| Possible Values | {"Id": "Default"}. Default: Default |
| Example         | {"Id": "Default"}                   |

Optional. Account-specific configuration preset, selected with the `Id` field. Settings from the preset can be overridden directly in the request.

### [langcult](#langcult)

| Attribute       | Value                                      |
| :-------------- | :----------------------------------------- |
| Type            | Query Parameter                            |
| Data Type       | string                                     |
| Possible Values | en-US, en-CA, en-AU, en-GB. Default: en-US |
| Example         | en-GB                                      |

Language and locale used for the response. To override the default value in the `Accept-Language` HTTP header, use this parameter.

### [Portfolios](#portfolios)

| Attribute       | Value                                                                            |
| :-------------- | :------------------------------------------------------------------------------- |
| Type            | Request Payload                                                                  |
| Data Type       | array of objects                                                                 |
| Possible Values | Portfolio objects. A minimum of 1 and a maximum of 2 can be passed. See Portfolio Inputs. |
| Example         | [{"Name": "ExamplePortfolio1", "Currency": "USD", "TotalValue": 50000, "Holdings": [...]}] |

Required. Array of portfolios to analyze.

### [RequestSettings](#requestsettings)

| Attribute       | Value                                                                     |
| :-------------- | :------------------------------------------------------------------------ |
| Type            | Request Payload                                                           |
| Data Type       | object                                                                    |
| Possible Values | Settings object. OutputCurrency is required. See Request Settings Inputs. |
| Example         | {"OutputCurrency": "USD"}                                                 |

Required. Analysis settings including output currency, date range, performance frequency, and optional data sections.

### [View](#view)

| Attribute       | Value                                                                            |
| :-------------- | :------------------------------------------------------------------------------- |
| Type            | Request Payload                                                                  |
| Data Type       | object                                                                           |
| Possible Values | {"Id": ...} where Id is one of All, Default, Intersection, Operation, Portfolio, StockIntersection, XrayOverview, Snapshot. Default: All |
| Example         | {"Id": "XrayOverview"}                                                           |

Optional. Selects a predefined set of data points to return in the response, using the `Id` field.

## [Request Settings Inputs](#request-settings-inputs)

These inputs are passed in the `RequestSettings` object.

### [AnalysisDateTimePeriod](#analysisdatetimeperiod)

| Attribute       | Value                                                        |
| :-------------- | :----------------------------------------------------------- |
| Type            | Request Payload (RequestSettings)                            |
| Data Type       | string                                                       |
| Possible Values | MonthEnd, QuarterEnd, YearEnd, CustomDate. Default: MonthEnd |
| Example         | MonthEnd                                                     |

Optional. End date period for the analysis. `CustomDate` requires [PortfolioPerformanceEndDate](#portfolioperformanceenddate) to be set.

### [AssetClassGroupConfigs](#assetclassgroupconfigs)

| Attribute       | Value                                                                            |
| :-------------- | :------------------------------------------------------------------------------- |
| Type            | Request Payload (RequestSettings)                                                |
| Data Type       | object                                                                           |
| Possible Values | {"AssetClassGroupConfig": [{"Id": ...}]} where Id is one of ACG-AUDETAILED, ACG-BROAD-INDIA2, ACG-BROAD-JAPAN, ACG-CABROAD, ACG-CANBROAD4, ACG-EUBROAD, ACG-GLOBBROAD, ACG-NZDETAILED, ACG-UKBROAD, ACG-UK-GBR, ACG-USBROAD. Default: ACG-USBROAD |
| Example         | {"AssetClassGroupConfig": [{"Id": "ACG-USBROAD"}]}                               |

Optional. Asset class group to query. The `AssetClassGroupConfig` array accepts a maximum of one value per request.

### [DisableRescale](#disablerescale)

| Attribute       | Value                             |
| :-------------- | :-------------------------------- |
| Type            | Request Payload (RequestSettings) |
| Data Type       | boolean                           |
| Possible Values | true, false. Default: false       |
| Example         | false                             |

Optional. When `true`, portfolio weights are not rescaled if any holdings are invalid or unentitled.

### [EnablePerformanceCommonEndDate](#enableperformancecommonenddate)

| Attribute       | Value                             |
| :-------------- | :-------------------------------- |
| Type            | Request Payload (RequestSettings) |
| Data Type       | boolean                           |
| Possible Values | true, false. Default: false       |
| Example         | true                              |

Optional. When `true`, the most recent common end date across all portfolios is used as the analysis end date.

### [IncludeGrossNetReturns](#includegrossnetreturns)

| Attribute       | Value                             |
| :-------------- | :-------------------------------- |
| Type            | Request Payload (RequestSettings) |
| Data Type       | boolean                           |
| Possible Values | true, false. Default: false       |
| Example         | true                              |

Optional. When `true`, both gross and net return values are included in trailing returns and calendar year return data.

### [IncludePortfolioInCorrelationMatrix](#includeportfolioincorrelationmatrix)

| Attribute       | Value                             |
| :-------------- | :-------------------------------- |
| Type            | Request Payload (RequestSettings) |
| Data Type       | boolean                           |
| Possible Values | true, false. Default: false       |
| Example         | true                              |

Optional. When `true`, the portfolio is included as an entry in the correlation matrix.

### [InitialValue](#initialvalue)

| Attribute       | Value                                               |
| :-------------- | :-------------------------------------------------- |
| Type            | Request Payload (RequestSettings)                   |
| Data Type       | number                                              |
| Possible Values | A number greater than or equal to 1. Default: 10000 |
| Example         | 10000                                               |

Optional. Initial value of the portfolio in the output currency.

### [MaxCorrelationMatrixHoldingNumber](#maxcorrelationmatrixholdingnumber)

| Attribute       | Value                              |
| :-------------- | :--------------------------------- |
| Type            | Request Payload (RequestSettings)  |
| Data Type       | integer                            |
| Possible Values | Integers from 2 to 50. Default: 50 |
| Example         | 25                                 |

Optional. Maximum number of holdings to include in the correlation matrix. Applies only when [ReturnDataSections](#returndatasections) includes `CorrelationMatrix`.

### [OutputCurrency](#outputcurrency)

| Attribute       | Value                                                                            |
| :-------------- | :------------------------------------------------------------------------------- |
| Type            | Request Payload (RequestSettings)                                                |
| Data Type       | string                                                                           |
| Possible Values | AUD, BRL, CAD, CHF, DKK, EUR, GBP, HKD, INR, JPY, MXN, MYR, NOK, NZD, SEK, SGD, TWD, USD, ZAR. Default: USD |
| Example         | USD                                                                              |

Required. Currency used to calculate output values. 19 currencies are supported; accepted values are ISO 4217 currency codes.

### [PerformanceFrequency](#performancefrequency)

| Attribute       | Value                                |
| :-------------- | :----------------------------------- |
| Type            | Request Payload (RequestSettings)    |
| Data Type       | string                               |
| Possible Values | Monthly, Quarterly. Default: Monthly |
| Example         | Monthly                              |

Optional. Frequency of performance returns and risk calculations.

### [PortfolioPerformanceCustomStartDate](#portfolioperformancecustomstartdate)

| Attribute       | Value                             |
| :-------------- | :-------------------------------- |
| Type            | Request Payload (RequestSettings) |
| Data Type       | string (date)                     |
| Possible Values | yyyy-MM-dd                        |
| Example         | 2022-10-31                        |

Custom start date of the analysis. Required when [PortfolioPerformanceStartDate](#portfolioperformancestartdate) is set to `CustomDate`.

### [PortfolioPerformanceEndDate](#portfolioperformanceenddate)

| Attribute       | Value                             |
| :-------------- | :-------------------------------- |
| Type            | Request Payload (RequestSettings) |
| Data Type       | string (date)                     |
| Possible Values | yyyy-MM-dd                        |
| Example         | 2022-10-31                        |

End date of the analysis. Required when [AnalysisDateTimePeriod](#analysisdatetimeperiod) is set to `CustomDate`.

### [PortfolioPerformanceStartDate](#portfolioperformancestartdate)

| Attribute       | Value                                                                            |
| :-------------- | :------------------------------------------------------------------------------- |
| Type            | Request Payload (RequestSettings)                                                |
| Data Type       | string                                                                           |
| Possible Values | EarliestCommon, EarliestAvailable, EarliestCommonExtended, EarliestCommonExtended10Year, Year10, CustomDate. Default: EarliestCommon |
| Example         | EarliestCommon                                                                   |

Optional. Start date of the analysis. `CustomDate` requires [PortfolioPerformanceCustomStartDate](#portfolioperformancecustomstartdate) to be set.

### [ReturnDataSections](#returndatasections)

| Attribute       | Value                             |
| :-------------- | :-------------------------------- |
| Type            | Request Payload (RequestSettings) |
| Data Type       | array of strings                  |
| Possible Values | CorrelationMatrix, RollingReturns |
| Example         | ["RollingReturns"]                |

Optional. Additional data sections to include in the response. Related inputs are [RollingReturnFrequencies](#rollingreturnfrequencies), [RollingReturnStep](#rollingreturnstep), and [MaxCorrelationMatrixHoldingNumber](#maxcorrelationmatrixholdingnumber).

### [RollingReturnFrequencies](#rollingreturnfrequencies)

| Attribute       | Value                                       |
| :-------------- | :------------------------------------------ |
| Type            | Request Payload (RequestSettings)           |
| Data Type       | array of strings                            |
| Possible Values | Month3, Month6, Year1, Year3, Year5, Year10 |
| Example         | ["Year1", "Year3", "Year5"]                 |

Rolling return periods to calculate. Required when [ReturnDataSections](#returndatasections) includes `RollingReturns`.

### [RollingReturnStep](#rollingreturnstep)

| Attribute       | Value                                           |
| :-------------- | :---------------------------------------------- |
| Type            | Request Payload (RequestSettings)               |
| Data Type       | integer                                         |
| Possible Values | Integers greater than or equal to 1. Default: 1 |
| Example         | 1                                               |

Optional. Step interval, in months, between rolling return calculations. Applies only when [ReturnDataSections](#returndatasections) includes `RollingReturns`.

### [SynchronizePortfolioStartDate](#synchronizeportfoliostartdate)

| Attribute       | Value                             |
| :-------------- | :-------------------------------- |
| Type            | Request Payload (RequestSettings) |
| Data Type       | boolean                           |
| Possible Values | true, false. Default: false       |
| Example         | true                              |

Optional. When `true`, the latest common start date across all portfolios is used as the analysis start date for all portfolios.

## [Portfolio Inputs](#portfolio-inputs)

These inputs are passed in each object of the `Portfolios` array.

### [Currency](#currency)

| Attribute       | Value                                                                            |
| :-------------- | :------------------------------------------------------------------------------- |
| Type            | Request Payload (Portfolios)                                                     |
| Data Type       | string                                                                           |
| Possible Values | AUD, BRL, CAD, CHF, DKK, EUR, GBP, HKD, INR, JPY, MXN, MYR, NOK, NZD, SEK, SGD, TWD, USD, ZAR |
| Example         | USD                                                                              |

Required. Portfolio currency. 19 currencies are supported; accepted values are ISO 4217 currency codes.

### [Fees](#fees)

| Attribute       | Value                                                       |
| :-------------- | :---------------------------------------------------------- |
| Type            | Request Payload (Portfolios)                                |
| Data Type       | object                                                      |
| Possible Values | Fee object. See Fee Inputs.                                 |
| Example         | {"AnnualFeePercent": 1.15, "AnnualFeeFrequency": "Monthly"} |

Optional. Portfolio-level annual fee configuration.

### [Holdings](#holdings)

| Attribute       | Value                                                                            |
| :-------------- | :------------------------------------------------------------------------------- |
| Type            | Request Payload (Portfolios)                                                     |
| Data Type       | array of objects                                                                 |
| Possible Values | Holding objects. A minimum of 1 and a maximum of 250 can be passed. See Holding Inputs. |
| Example         | [{"TradingSymbol": "SPY", "Weight": 60}, {"SecurityId": "CASH%0.000", "Weight": 40}] |

Required. The holdings in the portfolio. Each holding must specify a security identifier and either `Weight` or `Value`.

### [IrrFees](#irrfees)

| Attribute       | Value                               |
| :-------------- | :---------------------------------- |
| Type            | Request Payload (Portfolios)        |
| Data Type       | number                              |
| Possible Values | A number greater than or equal to 1 |
| Example         | 1000                                |

Optional. Annual fee used in the internal rate of return calculation.

### [Name](#name)

| Attribute       | Value                        |
| :-------------- | :--------------------------- |
| Type            | Request Payload (Portfolios) |
| Data Type       | string                       |
| Possible Values | —                            |
| Example         | ExamplePortfolio1            |

Required. Portfolio name.

### [TotalValue](#totalvalue)

| Attribute       | Value                               |
| :-------------- | :---------------------------------- |
| Type            | Request Payload (Portfolios)        |
| Data Type       | number                              |
| Possible Values | A number greater than or equal to 1 |
| Example         | 20000                               |

Total market value of the portfolio in the portfolio currency. Required when holdings use `Weight`. When holdings use `Value`, the sum of all holding values must equal `TotalValue`.

## [Holding Inputs](#holding-inputs)

These inputs are passed in each object of the `Holdings` array.

Each holding requires one security identifier and one position size:

-   **Identifier:** pass one of `SecurityId`, `CUSIP`, `FundCode`, `ISIN`, `PerformanceId`, or `TradingSymbol`. If multiple identifiers are provided for a single holding, `SecurityId` takes priority. If `SecurityId` is absent, the last identifier listed in the object is used. Identifier types can be mixed across holdings.
-   **Position size:** pass either `Weight` or `Value`. The position size type must be the same for every holding in the portfolio.

Holdings can also include the annual fee inputs described under [Fee Inputs](#fee-inputs).

### [CUSIP](#cusip)

| Attribute       | Value                      |
| :-------------- | :------------------------- |
| Type            | Request Payload (Holdings) |
| Data Type       | string                     |
| Possible Values | A security CUSIP           |
| Example         | 09251T103                  |

Security's CUSIP.

### [FundCode](#fundcode)

| Attribute       | Value                      |
| :-------------- | :------------------------- |
| Type            | Request Payload (Holdings) |
| Data Type       | string                     |
| Possible Values | A security fund code       |
| Example         | ABG                        |

Security's fund code.

### [ISIN](#isin)

| Attribute       | Value                      |
| :-------------- | :------------------------- |
| Type            | Request Payload (Holdings) |
| Data Type       | string                     |
| Possible Values | A security ISIN            |
| Example         | US0378331005               |

Security's ISIN.

### [PerformanceId](#performanceid)

| Attribute       | Value                        |
| :-------------- | :--------------------------- |
| Type            | Request Payload (Holdings)   |
| Data Type       | string                       |
| Possible Values | A Morningstar Performance ID |
| Example         | 0P00002QN3                   |

Security's Morningstar Performance ID. Use the Universe API to retrieve Performance IDs for investments in your entitled universe.

### [SecurityId](#securityid)

| Attribute       | Value                                                       |
| :-------------- | :---------------------------------------------------------- |
| Type            | Request Payload (Holdings)                                  |
| Data Type       | string                                                      |
| Possible Values | A Morningstar Security ID, or CASH%0.000 for cash positions |
| Example         | FOUSA00DFS                                                  |

Morningstar unique identifier of a security. Use `CASH%0.000` for cash positions. Takes priority over any other identifier passed for the same holding.

### [TradingSymbol](#tradingsymbol)

| Attribute       | Value                               |
| :-------------- | :---------------------------------- |
| Type            | Request Payload (Holdings)          |
| Data Type       | string                              |
| Possible Values | A security ticker or trading symbol |
| Example         | MDLOX                               |

Security's ticker or trading symbol.

### [Value](#value)

| Attribute       | Value                               |
| :-------------- | :---------------------------------- |
| Type            | Request Payload (Holdings)          |
| Data Type       | number                              |
| Possible Values | A number greater than or equal to 1 |
| Example         | 25000                               |

Market value of the holding in the portfolio currency. The sum of all holding values must equal the portfolio `TotalValue`. Use either `Value` or `Weight`, not both.

### [Weight](#weight)

| Attribute       | Value                      |
| :-------------- | :------------------------- |
| Type            | Request Payload (Holdings) |
| Data Type       | number                     |
| Possible Values | Numbers from 1 to 100      |
| Example         | 60                         |

Holding weight as a percentage of the portfolio total. All holding weights must sum to 100, and the portfolio `TotalValue` is required. Use either `Weight` or `Value`, not both.

## [Fee Inputs](#fee-inputs)

These inputs configure annual fees. They can be passed at the portfolio level, in the `Fees` object of a portfolio, or at the holding level, in an object of the `Holdings` array.

### [AnnualFeeFrequency](#annualfeefrequency)

| Attribute       | Value                                                        |
| :-------------- | :----------------------------------------------------------- |
| Type            | Request Payload (Fees; Holdings)                             |
| Data Type       | string                                                       |
| Possible Values | Monthly, Quarterly, SemiAnnually, Annually. Default: Monthly |
| Example         | Monthly                                                      |

Optional. How often the annual fee is deducted. At the portfolio level the fee is deducted from the portfolio; at the holding level it is deducted from the holding.

### [AnnualFeePercent](#annualfeepercent)

| Attribute       | Value                                                    |
| :-------------- | :------------------------------------------------------- |
| Type            | Request Payload (Fees; Holdings)                         |
| Data Type       | number                                                   |
| Possible Values | A number greater than or equal to 0. Default: 0 (no fee) |
| Example         | 1.15                                                     |

Optional. Annual fee as a percentage of portfolio value (portfolio level) or holding value (holding level). For example, `1.15` is 1.15%.