---
title: "Getting Started"
description: "Getting started information for Portfolio X-Ray API."
url: "https://developer-beta.morningstar.com/portfolio-xray-api/getting-started"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~R2V0dGluZyBTdGFydGVkIHwgUG9ydGZvbGlvIFgtUmF5IEFQSQ,description_Getting+started+information+for+Portfolio+X-Ray+API.,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9wb3J0Zm9saW8teHJheS1hcGkvZ2V0dGluZy1zdGFydGVkIg,s_uZGNxh1L9Vx8NH1u.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.

# Getting Started

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

The Portfolio X-Ray API analyzes up to two portfolios in a single synchronous request. For each portfolio, it returns how the holdings are diversified by region, sector, and investment style, along with holdings, performance, risk, and fee analysis. This guide covers the workflow for making your first call and where to go when something goes wrong.

## [Workflow](#workflow)

1.

The API uses OAuth 2.0 to authenticate users. Before you can call any endpoint, you must authenticate your account and get an access token.

See the [Authentication](https://developer-beta.morningstar.com/api-authentication) article for information about obtaining and using access tokens. ::

1.

Each holding needs a security identifier. The API accepts Morningstar Security IDs, CUSIPs, fund codes, ISINs, Morningstar Performance IDs, and trading symbols. You can mix identifier types across holdings. If you provide more than one identifier for a holding, the Security ID takes priority.

Use the Security ID `CASH%0.000` to represent a cash position. ::

1.

A request can include up to two portfolios, each with up to 250 holdings. Give each portfolio a name and a currency, and list its holdings.

Set each holding's position size as either a weight or a value. Use the same approach for every holding in a portfolio. If you use weights, they must add up to 100 and you must also provide the portfolio's total value. If you use values, they must add up to the portfolio's total value. ::

1.

The request settings control the analysis. The only required setting is the output currency. You can also choose the analysis start and end dates, the performance frequency, and optional sections such as rolling returns and the correlation matrix.

Use the view ID to choose which data points the response includes. If you don't set one, the API returns all of them. ::

1.

Send a `POST` request to `/portfolioanalysis/v1/xray` with your access token in the `Authorization` header and your portfolios and settings in a JSON body. Use the `langcult` query parameter to choose the language and locale of the response.

See [API Requests](https://developer-beta.morningstar.com/portfolio-xray-api/request-structure) for the full list of request inputs and limits. ::

1.

The response contains one x-ray for each portfolio, plus reference data for the securities in them. If some holdings are invalid or you aren't entitled to them, the API analyzes the remaining holdings and rescales their weights by default. To get an error instead, set `DisableRescale` to `true`. The error response lists each invalid or unentitled holding.

See the [Response Structure](https://developer-beta.morningstar.com/portfolio-xray-api/response-structure) page for the response structure and how to handle invalid holdings. ::

::

:::::

## [Limits](#limits)

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

## [Managing Issues](#managing-issues)

If a request fails or returns unexpected results:

-   **Check the [Error Messages](https://developer-beta.morningstar.com/portfolio-xray-api/error-messages) page** to find out what an error code or message means.
-   **See [Troubleshooting](https://developer-beta.morningstar.com/portfolio-xray-api/troubleshooting)** for help with common issues, such as missing data or unexpected responses.
-   **Browse the [FAQs](https://developer-beta.morningstar.com/portfolio-xray-api/faqs)** for answers to frequently asked questions.