Portfolio X-Ray API

1.0OAS 3.1

Try This API

You can try this API by creating an account to get credentials. Once your calls are authorized, you can test the endpoints on this page and get back a limited sample of real data — enough to evaluate the response structure and integrate against it.

Trial responses are restricted to a sample universe. For full data coverage and production access, talk to our sales team.

Before You Start

You’ll need a Client ID and Client Secret. These come from an your account profile — they’re separate from the username and password you use to log in to Morningstar for Developers.

Create Account

Already have an account? Log in and follow the steps below.

  1. Create an application in your portal profile.
  2. Copy the Client ID and Client Secret it issues.

Authenticating Your Requests

Authentication is a two-step process.

  1. Request a token from POST /token/oauth, using your Client ID and Client Secret as HTTP Basic credentials.
  2. Send the token to all other endpoints as an Authorization: Bearer <token> header.

Reuse the token for up to 60 minutes, then request a new one.

Learn More

Ready to go deeper? The Portfolio X-Ray API guide has the concepts, worked examples, and reference material you’ll need to build with confidence.

New to Morningstar’s APIs? The Quick Start takes you from account to first call in a few minutes.

API Base URL
  • Server 1:https://www.us-api.morningstar.com

    Americas Production

  • Server 2:https://www.apac-api.morningstar.com

    APAC Production

  • Server 3:https://www.emea-api.morningstar.com

    EMEA Production

Security
Bearer (http)

JWT obtained from POST /token/oauth.

Send it on every request as Authorization: Bearer <token>. Reuse the token for up to 60 minutes, then request a new one.

Basic (http)

Used only by POST /token/oauth to obtain a bearer token.

Send your Client ID and Client Secret as a Base64-encoded clientId:clientSecret pair.

Authentication

Get token

Exchanges your Client ID and Client Secret for a signed JWT bearer token.

Send your credentials as a Base64-encoded clientId:clientSecret string in the Authorization header. Use the returned access_token as a Bearer token on all other endpoints in this API.

post

Response

application/json

200: OK

OutputToken

A successful authentication response containing a JWT bearer token.

access_tokenstringrequired

The signed JWT to use as a Bearer token in subsequent authenticated requests.

Example:eyJhbGciOiJ example

expires_inintegerrequired

The number of seconds until the token expires. After expiry, request a new token.

Example:3599

token_typestringrequired

The token type. Always Bearer.

Example:Bearer

post/token/oauth
 
application/json

X-Ray

Generate portfolio x-ray

Generate an x-ray of the portfolio(s) specified in the request body. The response will return information about how the portfolio is diversified by region, sector and investment style.

To override the default value in the Accept-Language HTTP header, use the langcult parameter.

post

Query Parameters

langcultstringrequired

Language and locale used for the response. Defaults to en-US.

Allowed values:en-USen-CAen-AUen-GB

Default:en-US

teststringrequired

For internal testing.

Allowed values:self

Default:self

Body

application/json

RequestPortfolioXray

Generate a Portfolio X-Ray for up to 2 portfolios. The maximum number of holdings per portfolio is 250.

Viewobject
Show Child Parameters
Configobject
Show Child Parameters
RequestSettingsobjectrequired

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

Show Child Parameters
Portfoliosarray[object]required

Object representing a portfolio to be analysed. Each holding must specify a security identifier and either Weight or Value to define its allocation. TotalValue is required when holdings use Weight.

>= 1 items<= 2 items

Show Child Parameters

Response

application/json

200: OK

ResponsePortfolioXray

X-Ray response containing analysis results and security reference data.

XRayarray[object]
Show Child Parameters
SecurityReferencearray[object]

Security reference data returned alongside the X-Ray response.

Show Child Parameters
post/portfolioanalysis/v1/xray

Body

{ "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 } ], "Benchmark": { "Type": "Standard" }, "RequestSettings": { "OutputCurrency": "USD", "AnalysisDateTimePeriod": "MonthEnd", "PortfolioPerformanceStartDate": "EarliestCommon", "PerformanceFrequency": "Monthly", "InitialValue": 10000, "DisableRescale": false } } ] }
 
application/json