Work with Results

A successful request returns one flat row for each investment that matched, plus metadata about the response. This page explains how to read the rows, how to match them to the investments you asked for, and how to handle warnings and errors.

Response Structure

The response has two top-level properties.

The following response is for a request for six data points for two investments. The first investment is missing three of them because the account isn't entitled to those data points.

{
  "investments": [
    {
      "performanceId": "0P000000YF",
      "basicReference.name": "CMTSU Liquidation Inc",
      "basicReference.ticker": "CBRI",
      "trailingReturn.trailing1YearReturn": "-95.000000"
    },
    {
      "performanceId": "0P000000YD",
      "basicReference.name": "C.H. Robinson Worldwide Inc",
      "basicReference.ticker": "CHRW",
      "instrumentIdentifiers.isin": "US12541W2098",
      "reference.assetType": "STOCK",
      "reference.currency": "USD",
      "trailingReturn.trailing1YearReturn": "83.881688"
    }
  ],
  "metadata": {
    "messages": [
      {
        "investments": [
          {
            "status": "Datapoints are not entitled for 0P000000YF security",
            "datapointIds": [
              "reference.currency",
              "instrumentIdentifiers.isin",
              "reference.assetType"
            ],
            "errorCode": "403",
            "id": "0P000000YF"
          }
        ],
        "type": "Warning"
      }
    ],
    "requestId": "85b6f9b2-01f9-4da8-90b8-5efb3c1ec31d",
    "time": "2026-04-13T14:41:48.4913734Z"
  }
}

The example is shortened. A real response has one row for every matched investment, with all the data points you requested.

Read the Rows

Each object in investments is one row. It has the following characteristics.

• Keys are data point names. Each property is named for a data point, in the format <dataGroup>.<fieldName>, for example trailingReturn.trailing1YearReturn. The names are flat, so they aren't nested inside objects.
• The performance ID is always included. It appears as performanceId, whether or not you asked for it.
• Values vary by data point. A value can be a string or a number, and can be null. The type of each data point is in its metadata. See Explore Data Points.
• Data points that couldn't be returned are left out. If you aren't entitled to a data point for an investment, the row doesn't contain it, and a warning explains why. In the example above, the first row has no reference.currency, instrumentIdentifiers.isin or reference.assetType.
• Rows are sorted. Rows follow your sort order. If you didn't set one, they are in ascending performance ID order.

Match Rows to Your Request

The rows don't repeat the identifiers you sent. Each has a performanceId, and any data points you requested.

• Investments that can't be matched don't return a row, so the response can have fewer rows than the investments you listed. Match rows to your request using the performance ID, not the position of the row.
• If you identified investments with something other than a performance ID, such as an ISIN or a trading symbol, include a data point that returns that identifier, for example basicReference.isin. Then you can match each row to your input.
• If two entries in your request resolve to the same investment, check the messages and the rows to see how they were handled.

Handle Warnings

A 200 response doesn't guarantee that every investment returned a row, or that every row has every data point. Warnings are listed in metadata.messages, so check it in every response. Each message has the following properties.

There are two common kinds of warning.

Data Points You Aren't Entitled To

When you aren't entitled to a data point, the investment is still returned, without that data point. The message lists the investment and the data points that couldn't be returned. Each object in investments has the following properties.

In the example earlier on this page, the investment 0P000000YF is returned without three data points, and the warning gives the error code 403.

If you see this warning:

• Check that you are entitled to the data points. Contact your Morningstar account manager if you expect to have access.
• Remove the data points that you aren't entitled to from dataPoints if you don't need them, so that the warning doesn't appear on every request.

Identifiers That Couldn't Be Matched

When an identifier can't be matched to an investment, the API returns no row for it, and lists it in messages. Each object in investments echoes the identifier and the lookup details from your request.

"messages": [
  {
    "investments": [
      {
        "id": "US0000000000",
        "idType": "isin"
      }
    ],
    "type": "Warning",
    "code": "404.common.125",
    "message": "Lookup : Invalid investments."
  }
]

Each object in investments can have the following properties.

If you see this warning:

• Check the identifier for typos.
• Check that idType matches the identifier.
• Check whether the lookup details are excluding the investment, and add or correct them.
• Try a different identifier for the same investment. The Morningstar Performance ID is the most precise.

Handle Errors

A request that fails returns an error response instead of rows.

The following response is returned when a request includes data point names that aren't valid.

{
  "statusCode": 400,
  "errorCode": "400.investmentList.004",
  "message": "Invalid datapoints companyGrade.profitaityGrade, legalName. Please send the name correctly",
  "requestId": "e08f8bbc-f5f5-4587-a65a-41e7d056a50c"
}

For the meaning of each error code, see Errors. For help with common problems, see Troubleshooting.

Use the Request ID

Every response includes a requestId, in metadata for successful responses and at the top level for errors. Include it if you contact support, so that your request can be traced.

Next Steps

• Example Lists has complete requests you can adapt.
• Troubleshooting helps when a response isn't what you expected.