---
title: "Request Portfolio X-Ray"
description: "Send a request to the Portfolio X-Ray API: endpoint, base URLs, parameters, example request and response codes."
url: "https://developer-beta.morningstar.com/portfolio-xray-api/generate-portfolio-xray"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~UmVxdWVzdCBQb3J0Zm9saW8gWC1SYXkgfCBQb3J0Zm9saW8gWC1SYXkgQVBJ,description_~U2VuZCBhIHJlcXVlc3QgdG8gdGhlIFBvcnRmb2xpbyBYLVJheSBBUEk6IGVuZHBvaW50LCBiYXNlIFVSTHMsIHBhcmFtZXRlcnMsIGV4YW1wbGUgcmVxdWVzdCBhbmQgcmVzcG9uc2UgY29kZXMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9wb3J0Zm9saW8teHJheS1hcGkvZ2VuZXJhdGUtcG9ydGZvbGlvLXhyYXki,s_tg34K9ar-W8AsVv1.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 Portfolio X-Ray

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

Use this endpoint to generate an X-Ray for the portfolios in the request body. The response describes how each portfolio is diversified by region, sector and investment style.

## [Endpoint](#endpoint)

```text
POST /portfolioanalysis/v1/xray?langcult={langcult}
```

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 |

## [Headers](#headers)

| Header        | Value                                                                            |
| :------------ | :------------------------------------------------------------------------------- |
| Authorization | Bearer {token}. Obtain a token from the Authentication API using POST /token/oauth. Tokens are valid for 60 minutes and can be reused across requests. |
| Content-Type  | application/json                                                                 |

## [Query Parameters](#query-parameters)

| Parameter | Required | Description                                                                      |
| :-------- | :------- | :------------------------------------------------------------------------------- |
| langcult  | Yes      | The language and locale for the response: en-US, en-CA, en-AU or en-GB. Defaults to en-US. Use langcult to override the value of the Accept-Language header. |

## [Request Body](#request-body)

The request body contains the portfolios to analyze and the analysis settings. For details, see [Request Structure](https://developer-beta.morningstar.com/portfolio-xray-api/request-structure) and [Configuring the Analysis](https://developer-beta.morningstar.com/portfolio-xray-api/configure-an-analysis).

| Property        | Required | Description                                                   |
| :-------------- | :------- | :------------------------------------------------------------ |
| Portfolios      | Yes      | One or two portfolios, each with a maximum of 250 holdings.   |
| RequestSettings | Yes      | Analysis settings. OutputCurrency is required within it.      |
| View            | No       | The predefined set of data points to return. Defaults to All. |
| Config          | No       | The configuration preset. Defaults to Default.                |

## [Example Request](#example-request)

The following request analyzes a single portfolio.

```bash
curl --request POST \
  --url "https://www.us-api.morningstar.com/portfolioanalysis/v1/xray?langcult=en-US" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "RequestSettings": {
      "OutputCurrency": "USD",
      "AnalysisDateTimePeriod": "MonthEnd",
      "PortfolioPerformanceStartDate": "EarliestCommon",
      "PerformanceFrequency": "Monthly",
      "InitialValue": 10000,
      "DisableRescale": false
    },
    "Portfolios": [
      {
        "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 }
        ]
      }
    ]
  }'
```

## [Responses](#responses)

| Status | Description                                                                      |
| :----- | :------------------------------------------------------------------------------- |
| 200    | The request succeeded. The body contains an XRay array and a SecurityReference array. See Understanding the Response. |
| 400    | The request is invalid. The body describes each problem. See Bad request responses. |
| 401    | Unauthorized. The token is missing, invalid or expired.                          |
| 403    | Forbidden.                                                                       |
| 500    | Internal server error.                                                           |

### [Bad Request Responses](#bad-request-responses)

A `400` response contains a `Message` and a `SpecificErrorStatus` array. Each entry has an `ErrorCode` and an `ErrorMessage`.

```json
{
  "Message": "The request is invalid.",
  "SpecificErrorStatus": [
    {
      "ErrorCode": "40015",
      "ErrorMessage": "Portfolio does not have any valid holdings. Invalid portfolio name: TestPortfolio1. Invalid Holdings: TradingSymbol:DODGX1."
    }
  ]
}
```

When `DisableRescale` is `true` and a portfolio contains invalid or unentitled holdings, the error includes `Metadata` that lists each affected holding and whether its status is `Invalid` or `Unentitled`.

```json
{
  "Message": "The request is invalid.",
  "SpecificErrorStatus": [
    {
      "ErrorCode": "40059",
      "ErrorMessage": "There are holdings present in portfolio which are invalid.",
      "Metadata": {
        "InvalidPortfolios": [
          {
            "Name": "Test Portfolio",
            "InvalidHoldings": [
              { "SecurityId": "FX000015JA3", "Status": "Invalid" },
              { "SecurityId": "F00000YZ48", "Status": "Unentitled" }
            ]
          }
        ]
      }
    }
  ]
}
```

For a full list of errors and how to resolve them, see [Errors](https://developer-beta.morningstar.com/portfolio-xray-api/error-messages) and [Troubleshooting](https://developer-beta.morningstar.com/portfolio-xray-api/troubleshooting).