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 messages and errors.

Response Structure

The response has two top-level properties.

The following response is the first page of a larger result set.

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

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 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.
• 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.

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 Investments.

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.

The following message is returned when you aren't entitled to a data point.

"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

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.05",
  "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.