Work with Results

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

The response has two top-level properties.

The following response is the first page of a larger result set. It includes a pagination token and a warning.

{
  "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

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 <dataGroup>.<fieldName>, 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.
• 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.

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.

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.

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.

Each object in investments has the following properties.

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

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

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

{
  "statusCode": 400,
  "errorCode": "400.screener.005",
  "message": "Invalid dataPoint names {0}. Provide valid values.",
  "requestId": "5c2ad24c-964b-4f9b-9d9e-26b7bdb915d9"
}

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 Screens has complete requests you can adapt.
• Troubleshooting helps when a response isn't what you expected.