--- title: "Work with Results" description: "Read an Investment List API response: the flat rows, matching rows to your request, warnings for unmatched identifiers and entitlements, and errors." url: "https://developer-beta.morningstar.com/investment-list-api/work-with-results" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~V29yayB3aXRoIFJlc3VsdHMgfCBJbnZlc3RtZW50IExpc3QgQVBJ,description_~UmVhZCBhbiBJbnZlc3RtZW50IExpc3QgQVBJIHJlc3BvbnNlOiB0aGUgZmxhdCByb3dzLCBtYXRjaGluZyByb3dzIHRvIHlvdXIgcmVxdWVzdCwgd2FybmluZ3MgZm9yIHVubWF0Y2hlZCBpZGVudGlmaWVycyBhbmQgZW50aXRsZW1lbnRzLCBhbmQgZXJyb3JzLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9pbnZlc3RtZW50LWxpc3QtYXBpL3dvcmstd2l0aC1yZXN1bHRzIg,s_hZ51C4C6-vEP--2m.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) # Investment List API Build the Investment List API into your digital experience for quick investment and earnings summaries. # Work with Results [View Markdown](https://developer-beta.morningstar.com/investment-list-api/work-with-results.md)[Download Markdown](https://developer-beta.morningstar.com/investment-list-api/work-with-results.md) 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](#response-structure) The response has two top-level properties. | Property | Description | | :---------- | :------------------------------------------------------------------------------- | | investments | An array with one flat object, or row, for each investment that matched. | | metadata | Information about the response: warnings in messages, the request ID and the time. | 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. ```json { "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](#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 `.`, 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](https://developer-beta.morningstar.com/investment-list-api/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](#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](#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. | Property | Description | | :---------- | :----------------------------------------- | | type | The type of message. The value is Warning. | | investments | The investments the message applies to. | | code | The message code. | | message | A description of the issue. | There are two common kinds of warning. ### [Data Points You Aren't Entitled To](#data-points-you-arent-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. | Property | Description | | :----------- | :------------------------------------------------------------- | | id | The investment the warning applies to. | | status | A description of what couldn't be returned for the investment. | | datapointIds | The data points that couldn't be returned. | | errorCode | The error code for the warning. | 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](#identifiers-that-couldnt-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. ```json "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. | Property | Description | | :-------------------------------------------------- | :--------------------------------------------------------- | | id | The identifier you passed in the request. | | idType | The identifier type you passed in the request. | | performanceId | The performance ID, if you didn't pass one in the request. | | baseCurrency, domicile, exchangeCountry, exchangeId | The lookup details you passed for the identifier. | | errorCode | The error code for the warning. | 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](#handle-errors) A request that fails returns an error response instead of rows. | Property | Description | | :--------- | :------------------------------------ | | statusCode | The HTTP status code. | | errorCode | A unique identifier for the error. | | message | A description of the problem. | | requestId | The unique identifier of the request. | The following response is returned when a request includes data point names that aren't valid. ```json { "statusCode": 400, "errorCode": "400.investmentList.004", "message": "Invalid datapoints companyGrade.profitaityGrade, legalName. Please send the name correctly", "requestId": "e08f8bbc-f5f5-4587-a65a-41e7d056a50c" } ``` | Status | Description | | :----- | :------------------------------------------------------------------------------- | | 200 | The request succeeded. Check metadata.messages for warnings. | | 400 | The request is invalid. Read the message to find the problem. | | 401 | Unauthorized. The token is missing, invalid or expired. | | 403 | Forbidden. | | 500 | An internal server error occurred. Retry the request, and contact support if it persists. | For the meaning of each error code, see [Errors](https://developer-beta.morningstar.com/investment-list-api/error-messages). For help with common problems, see [Troubleshooting](https://developer-beta.morningstar.com/investment-list-api/troubleshooting). ## [Use the Request ID](#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](#next-steps) - [Example Lists](https://developer-beta.morningstar.com/investment-list-api/example-lists) has complete requests you can adapt. - [Troubleshooting](https://developer-beta.morningstar.com/investment-list-api/troubleshooting) helps when a response isn't what you expected.