--- title: "Work with Results" description: "Read a Managed Investments Screener API response: the investments array, result counts, pagination tokens, entitlement messages and error responses." url: "https://developer-beta.morningstar.com/managed-investments-screener-api/work-with-results" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~V29yayB3aXRoIFJlc3VsdHMgfCBNYW5hZ2VkIEludmVzdG1lbnRzIFNjcmVlbmVyIEFQSQ,description_~UmVhZCBhIE1hbmFnZWQgSW52ZXN0bWVudHMgU2NyZWVuZXIgQVBJIHJlc3BvbnNlOiB0aGUgaW52ZXN0bWVudHMgYXJyYXksIHJlc3VsdCBjb3VudHMsIHBhZ2luYXRpb24gdG9rZW5zLCBlbnRpdGxlbWVudCBtZXNzYWdlcyBhbmQgZXJyb3IgcmVzcG9uc2VzLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9tYW5hZ2VkLWludmVzdG1lbnRzLXNjcmVlbmVyLWFwaS93b3JrLXdpdGgtcmVzdWx0cyI,s_L0mcM-WlhTrBXyxr.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) # Work with Results [View Markdown](https://developer-beta.morningstar.com/managed-investments-screener-api/work-with-results.md)[Download Markdown](https://developer-beta.morningstar.com/managed-investments-screener-api/work-with-results.md) A successful screen returns the matching investments and metadata about the response. This page explains how to read the investments, how to use the result count and pagination tokens to retrieve every page, and how to handle messages and errors. ## [Response Structure](#response-structure) The response has two top-level properties. | Property | Description | | :---------- | :------------------------------------------------------------------------------- | | investments | An array with one object for each matching investment on the current page. | | metadata | Information about the response: the number of results, pagination tokens, messages about data points that couldn't be returned, and the request ID. | The following response is the first page of a larger result set. ```json { "investments": [ { "instrumentIdentifiers.performanceId": "0P0001UMFK", "basicReference.firmName": "Driftwood Euro Solutions LLC", "basicReference.name": "Ser 501TrbtHtlOldSanJuanNtsdue2027$Acc", "basicReference.legalName": "(Series 501) Tribute Hotel Old San Juan Notes Due 2027 USD Accumulation" }, { "instrumentIdentifiers.performanceId": "0P0001O9X4", "basicReference.firmName": "VS TRUST", "basicReference.name": "-1x Short VIX Futures ETF", "basicReference.legalName": "-1x Short VIX Futures ETF" } ], "metadata": { "totalCount": 10000, "paginationTokenNext": "{token}", "requestId": "d98e0f36-91b3-4cf3-bd61-15841ce6f9f8", "time": "2025-10-27T09:09:01.3362533Z" } } ``` The example is shortened. A real page contains up to the number of investments set by `pageSize`. ## [Read the Investments](#read-the-investments) Each object in `investments` is one match. It has the following characteristics. - **Keys are data point names.** Each property is named for a data point, in the format `.`, for example `basicReference.name`. The names are flat, so they aren't nested inside objects. - **The performance ID is always included.** It appears as `instrumentIdentifiers.performanceId`, whether or not you asked for it. You can use it to look up the investment in other APIs. - **Values vary by data point.** A value can be a string, number, integer or boolean, and can be null. The data type of each data point is in its metadata. See [Explore Data Points](https://developer-beta.morningstar.com/managed-investments-screener-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 investment is still returned without it, and the response metadata explains why. See [Handle Messages](#handle-messages). ## [Use the Result Count and Pagination Tokens](#use-the-result-count-and-pagination-tokens) Results are returned in pages. The `metadata` object tells you how many results there are and how to retrieve the rest. | Property | Description | | :---------------------- | :--------------------------------------------------------------------------- | | totalCount | The total number of matches, across all pages. | | paginationTokenNext | The token for the next page. It is present only when there are more results. | | paginationTokenPrevious | The token for the previous page. | Compare `totalCount` with the number of investments in the response to see how many pages to expect. For example, 1,043 matches with a page size of 50 is 21 pages. To retrieve every page: 1. Send the request, with the page size you want in `pagination.pageSize`. The default and maximum is 50. 2. Read the investments in the response, and read `metadata.paginationTokenNext`. 3. If the token is present, send the same request again with the token in `pagination.paginationTokenNext`. 4. Repeat until a response has no `paginationTokenNext`. To go back a page, send the request with the `paginationTokenPrevious` value in `pagination.paginationTokenPrevious` instead. Use one token in a request, not both. For how to set up the request, see [Screen Investments](https://developer-beta.morningstar.com/managed-investments-screener-api/screen-investments#step-5-paginate-results). ## [Handle Messages](#handle-messages) A `200` response doesn't guarantee that every data point was returned for every investment. When data points couldn't be returned, `metadata.messages` explains why, so check it in every response. `metadata.messages` has the following properties. | Property | Description | | :--------- | :------------------------------------------------------------- | | id | The investment the message applies to. | | status | A description of what couldn't be returned for the investment. | | dataPoints | The data points that couldn't be returned for the investment. | | errorCode | The error code for the message. | The following message is returned when you aren't entitled to a data point. ```json "messages": { "status": "Datapoints are not entitled for 0P0001VK70 security", "dataPoints": [ "esgFundLevelProductInvolvement.productInvolvementPercPesticides" ], "errorCode": "403", "id": "0P0001VK70" } ``` In this example, the investment `0P0001VK70` is returned without the listed data point. If you see this message: - 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 message doesn't appear on every request. ## [Handle Errors](#handle-errors) A request that fails returns an error response instead of results. | 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 a data point name that isn't valid. ```json { "statusCode": 400, "errorCode": "400.screener.05", "message": "Invalid dataPoint names {0}. Provide valid values.", "requestId": "5c2ad24c-964b-4f9b-9d9e-26b7bdb915d9" } ``` | Status | Description | | :----- | :------------------------------------------------------------------------------- | | 200 | The request succeeded. Check metadata.messages for messages about data points. | | 400 | The request is invalid. Read the message to find the problem. | | 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/managed-investments-screener-api/error-messages). For help with common problems, see [Troubleshooting](https://developer-beta.morningstar.com/managed-investments-screener-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 Screens](https://developer-beta.morningstar.com/managed-investments-screener-api/example-screens) has complete requests you can adapt. - [Troubleshooting](https://developer-beta.morningstar.com/managed-investments-screener-api/troubleshooting) helps when a response isn't what you expected.