It finds equities that match criteria you define. You set the starting universe with a scope, narrow it with filter conditions, and choose the data points to return for each match. The response includes the matching investments and their performance IDs, which you can use in other APIs. See Core Concepts.

The API has two endpoints.

Use the base URL for your region.

• Americas: https://www.us-api.morningstar.com
• APAC: https://www.apac-api.morningstar.com
• EMEA: https://www.emea-api.morningstar.com

Yes. Each match includes its performance ID, which is the primary identifier used by other Morningstar APIs. Pass the performance IDs to another API to retrieve more data. See Work with Results.

No. The Equities Screener API is for finding investments that meet criteria. If you already have performance IDs and want data for those investments, use an API designed for that, such as the Investment List API for list-based data or the Time Series API for history.

Request a token from POST /token/oauth, then send it on every other request in the Authorization header as Bearer {token}. See Authentication.

A token is valid for 60 minutes and can be reused across requests during that time. Long-running jobs must request a new token before it expires, and retry any request that returns 401 Unauthorized.

The scope sets the starting universe of investments, limited to your entitled universe. A request must include one. For equities, it is defined with the exchange code data point, shareClassInformation.exchangeCode. See Screen Equities.

No. If you omit query, no filtering is applied beyond your entitled universe and the scope.

You can use equality filters (a single value, or a list of values), comparison filters (gt, gte, lt and lte) and compound filters (and, or and not). Some text data points also support contains and fuzzy search. See Operators.

Use a list. An investment is returned if its value equals any entry in the list.

"query": {
  "shareClassInformation.symbol": ["MSES", "CA40"]
}

Use and, or and not, which each take an array of conditions. They can be nested.

"query": {
  "and": [
    { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] },
    { "marketCapital.asOfDate": { "gt": "2020-01-01" } }
  ]
}

See Compound Filters.

Check the operators property in the data point's metadata. It lists the operators that the data point supports. See Explore Data Points.

No. Fuzzy search works only on some string data points, only as an equality filter, and the search text must be at least 3 characters. See Equality and Text Filters.

Call the data points endpoint. It lists every data point with its data type, operators, sortability and language and currency dependencies. See Explore Data Points.

Up to 100. If you omit dataPoints, only the performance ID is returned.

Yes. It is returned in every match as instrumentIdentifiers.performanceId, whether or not you ask for it.

These are data points whose values depend on a language or a currency. Pass languageId to retrieve language-dependent data points (the default is ENG) and currencyId to retrieve currency-dependent ones (the default is USD). The metadata for each data point shows whether it has either dependency.

No. The data point must be sortable, which its metadata shows, and it must also be in the dataPoints array of the request.

Results are sorted by performance ID in ascending order. To change this, use the sort array. See Screen Equities.

The default and maximum is 50. Set pagination.pageSize to return fewer.

Take the paginationTokenNext value from the metadata of the response, and send the same request again with the token in pagination.paginationTokenNext.

"pagination": {
  "pageSize": 25,
  "paginationTokenNext": "{token from the previous response}"
}

Read metadata.totalCount. It is the total number of matches across all pages.

The response has no paginationTokenNext. See Work with Results.

No. Use either paginationTokenNext or paginationTokenPrevious in a request.

The response has an investments array, with one object for each match on the page, and a metadata object. Each investment is a flat object keyed by data point name. The metadata contains totalCount, the pagination tokens, any warnings in messages, the requestId and the time. See Work with Results.

No. If you aren't entitled to a data point for an investment, the investment is still returned without it, and a warning in metadata.messages lists the data points that couldn't be returned. Always check metadata.messages.

It is a unique identifier for the request. It is returned in the response metadata, and in error responses. Include it if you contact support.