--- title: "Work with Results" description: "Read an Equities Screener API response: the investments array, result counts, pagination tokens, entitlement warnings and error responses." url: "https://developer-beta.morningstar.com/equities-screener-api/work-with-results" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~V29yayB3aXRoIFJlc3VsdHMgfCBFcXVpdGllcyBTY3JlZW5lciBBUEk,description_~UmVhZCBhbiBFcXVpdGllcyBTY3JlZW5lciBBUEkgcmVzcG9uc2U6IHRoZSBpbnZlc3RtZW50cyBhcnJheSwgcmVzdWx0IGNvdW50cywgcGFnaW5hdGlvbiB0b2tlbnMsIGVudGl0bGVtZW50IHdhcm5pbmdzIGFuZCBlcnJvciByZXNwb25zZXMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9lcXVpdGllcy1zY3JlZW5lci1hcGkvd29yay13aXRoLXJlc3VsdHMi,s_gTfl9rw9QayATZZO.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) # Equities Screener API Powerful, criteria-based screening using flexible filtering logic. # Work with Results [View Markdown](https://developer-beta.morningstar.com/equities-screener-api/work-with-results.md)[Download Markdown](https://developer-beta.morningstar.com/equities-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 warnings 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, warnings, and the request ID. | The following response is the first page of a larger result set. It includes a pagination token and a warning. ```json { "investments": [ { "instrumentIdentifiers.performanceId": "0P0001VK70", "shareClassInformation.symbol": "CA40", "marketCapital.asOfDate": "2025-10-02" }, { "instrumentIdentifiers.performanceId": "0P0001VK71", "shareClassInformation.symbol": "MSES", "marketCapital.asOfDate": "2025-10-02" } ], "metadata": { "totalCount": 1043, "paginationTokenNext": "{token}", "messages": [ { "investments": [ { "status": "Data points are not entitled for 0P0001VK71 security", "dataPoints": ["quantitativeFairValues.quantitativeMoat"], "errorCode": "403", "id": "0P0001VK71" } ], "type": "Warning" } ], "requestId": "092fa93b-d63d-4b6e-a53b-d7ace50473ff", "time": "2025-10-03T17:48:16.0302555Z" } } ``` 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 `shareClassInformation.symbol`. 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/equities-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 a warning explains why. See [Handle Warnings](#handle-warnings). ## [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 Equities](https://developer-beta.morningstar.com/equities-screener-api/screen-equities#step-5-paginate-results). ## [Handle Warnings](#handle-warnings) A `200` response doesn't guarantee that every data point was returned for every investment. Warnings are listed in `metadata.messages`, so check it in every response. The `messages` property is present only when there are warnings. Each entry in `messages` has the following properties. | Property | Description | | :---------- | :---------------------------------------- | | type | The type of message, for example Warning. | | investments | The investments the message applies to. | | message | A description of the issue. | | code | The message code. | 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. | | dataPoints | The data points that couldn't be returned for the investment. | | errorCode | The error code for the warning. | The most common warning is for data points that you aren't entitled to. In the example earlier on this page, the investment `0P0001VK71` is returned without `quantitativeFairValues.quantitativeMoat`, and the warning lists it with 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. ## [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.005", "message": "Invalid dataPoint names {0}. Provide valid values.", "requestId": "5c2ad24c-964b-4f9b-9d9e-26b7bdb915d9" } ``` | Status | Description | | :----- | :------------------------------------------------------------------------------- | | 200 | The request succeeded. Check metadata.messages for warnings. | | 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/equities-screener-api/error-messages). For help with common problems, see [Troubleshooting](https://developer-beta.morningstar.com/equities-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/equities-screener-api/example-screens) has complete requests you can adapt. - [Troubleshooting](https://developer-beta.morningstar.com/equities-screener-api/troubleshooting) helps when a response isn't what you expected.