--- title: "Example Screens" description: "Complete Equities Screener API requests you can adapt: equality, range, compound and nested filters, sorting, currency and pagination." url: "https://developer-beta.morningstar.com/equities-screener-api/example-screens" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RXhhbXBsZSBTY3JlZW5zIHwgRXF1aXRpZXMgU2NyZWVuZXIgQVBJ,description_~Q29tcGxldGUgRXF1aXRpZXMgU2NyZWVuZXIgQVBJIHJlcXVlc3RzIHlvdSBjYW4gYWRhcHQ6IGVxdWFsaXR5LCByYW5nZSwgY29tcG91bmQgYW5kIG5lc3RlZCBmaWx0ZXJzLCBzb3J0aW5nLCBjdXJyZW5jeSBhbmQgcGFnaW5hdGlvbi4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9lcXVpdGllcy1zY3JlZW5lci1hcGkvZXhhbXBsZS1zY3JlZW5zIg,s_cQ2vMlB4BHztFqpo.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. # Example Screens [View Markdown](https://developer-beta.morningstar.com/equities-screener-api/example-screens.md)[Download Markdown](https://developer-beta.morningstar.com/equities-screener-api/example-screens.md) This page has complete screens that you can adapt. Each example shows the request body for a common task, from a simple equality match to nested filters. To see how a request is built, see [Screen Equities](https://developer-beta.morningstar.com/equities-screener-api/screen-equities). ## [Before You Use the Examples](#before-you-use-the-examples) - Each example is the body of a `POST` request to the screener endpoint. Send it with your access token in the `Authorization` header and `Content-Type: application/json`. - The examples return a few data points to keep them short. A request can include up to 100. - Symbols, performance IDs and other values are illustrative. Replace them with values from your own entitled universe. - Before you use a data point in a filter, check that it supports the operator. See [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points). The following request shows how an example is sent. The body is the first example on this page. ```bash curl --request POST \ --url "https://www.us-api.morningstar.com/direct-web-services/v1/screeners/equities" \ --header "Authorization: Bearer {token}" \ --header "Content-Type: application/json" \ --data '{ "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "shareClassInformation.symbol": "MSES" }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.investmentName", "marketCapital.asOfDate" ] }' ``` ## [Examples at a Glance](#examples-at-a-glance) | Example | What It Shows | Filter Type | | :-------------------------------------- | :---------------------------------------------- | :---------- | | Find an Investment by Symbol | Matching a single value. | Equality | | Find Several Investments by Symbol | Matching any of a list of values, with sorting. | Equality | | Filter by a Date Range | Comparing dates, with a page size. | Comparison | | Filter by a Number Range | Comparing numbers. | Comparison | | Combine Conditions with And | Requiring every condition. | Compound | | Match Any Condition with Or | Requiring at least one condition. | Compound | | Exclude Investments with Not | Excluding investments. | Compound | | Nest Filters | Combining or and and. | Compound | | Rank by a Currency-Dependent Data Point | Sorting and setting the currency. | Equality | | Search by Name | Matching text. | Text | | Page Through Results | Retrieving a second page. | Pagination | ## [Find an Investment by Symbol](#find-an-investment-by-symbol) Return the equity with a given symbol on one exchange. This is an equality filter with a single value. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "shareClassInformation.symbol": "MSES" }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.investmentName", "marketCapital.asOfDate" ] } ``` See [Equality and Text Filters](https://developer-beta.morningstar.com/equities-screener-api/equality-and-text-filters). ## [Find Several Investments by Symbol](#find-several-investments-by-symbol) Return the equities that match any of several symbols, with the most recent market capital date first. A list of values matches any entry in the list. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "shareClassInformation.symbol": ["CA40", "MSES"] }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.investmentName", "marketCapital.asOfDate" ], "sort": [ { "dataPoint": "marketCapital.asOfDate", "orderBy": "desc" } ], "pagination": { "pageSize": 10 } } ``` The data point used in `sort` is also in `dataPoints`, as it must be. ## [Filter by a Date Range](#filter-by-a-date-range) Return equities whose market capital date is later than 1 January 2020 and earlier than 31 March 2024. Dates are strings in `yyyy-MM-dd` format. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "marketCapital.asOfDate": { "gt": "2020-01-01", "lt": "2024-03-31" } }, "dataPoints": [ "shareClassInformation.symbol", "marketCapital.asOfDate" ], "pagination": { "pageSize": 10 } } ``` A broad filter like this can match many investments, so use `metadata.totalCount` and the pagination tokens to retrieve them all. See [Page Through Results](#page-through-results). See [Comparison Filters](https://developer-beta.morningstar.com/equities-screener-api/comparison-filters). ## [Filter by a Number Range](#filter-by-a-number-range) Return equities whose 24-month beta is greater than 4 and less than 10. Write numbers without quotation marks. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "dividendResidualRiskAndReturnSensitivity.beta24Month": { "gt": 4, "lt": 10 } }, "dataPoints": [ "shareClassInformation.symbol", "dividendResidualRiskAndReturnSensitivity.beta24Month" ] } ``` ## [Combine Conditions with And](#combine-conditions-with-and) Return equities of two security types whose market capital date falls in a range. Every condition in the `and` array must match. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "and": [ { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] }, { "marketCapital.asOfDate": { "gt": "2020-01-01", "lt": "2024-03-31" } } ] }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.securityType", "marketCapital.asOfDate" ] } ``` See [Compound Filters](https://developer-beta.morningstar.com/equities-screener-api/compound-filters). ## [Match Any Condition with Or](#match-any-condition-with-or) Return the equity with a given performance ID, and any equities with the given symbols. An investment is returned if it matches at least one condition. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "or": [ { "instrumentIdentifiers.performanceId": "0P0001VK70" }, { "shareClassInformation.symbol": ["FM28", "MSES"] } ] }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.investmentStatus" ] } ``` ## [Exclude Investments with Not](#exclude-investments-with-not) Return equities whose status isn't `1` and whose symbol isn't `USSM`. The `not` operator excludes investments that match its conditions. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "not": [ { "shareClassInformation.investmentStatus": 1 }, { "shareClassInformation.symbol": "USSM" } ] }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.investmentStatus" ] } ``` ## [Nest Filters](#nest-filters) Combine `or` and `and` to build more complex logic. The following screen returns equities that trade in US or Canadian dollars, are one of two security types, and have a market capital date in a range. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "and": [ { "or": [ { "shareClassInformation.tradingCurrency": "USD" }, { "shareClassInformation.tradingCurrency": "CAD" } ] }, { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] }, { "marketCapital.asOfDate": { "gt": "2020-01-01", "lt": "2024-03-31" } } ] }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.tradingCurrency", "shareClassInformation.securityType", "marketCapital.asOfDate" ] } ``` The nesting can go the other way round. The following query returns an equity that matches a symbol and a market capital date together, or an equity with a given performance ID. ```json "query": { "or": [ { "and": [ { "shareClassInformation.symbol": ["ALMIL"] }, { "marketCapital.asOfDate": ["2025-01-06"] } ] }, { "instrumentIdentifiers.performanceId": ["0P0001DIM8"] } ] } ``` ## [Rank by a Currency-Dependent Data Point](#rank-by-a-currency-dependent-data-point) Return equities of two security types, ranked by their 10-year trailing return, highest first. The trailing return is currency-dependent, so the request sets `currencyId`. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] }, "dataPoints": [ "shareClassInformation.symbol", "shareClassInformation.investmentName", "trailingReturn.trailing10YearReturn" ], "sort": [ { "dataPoint": "trailingReturn.trailing10YearReturn", "orderBy": "desc" } ], "pagination": { "pageSize": 20 }, "currencyId": "EUR" } ``` For a language-dependent data point, set `languageId` in the same way. See [Screen Equities](https://developer-beta.morningstar.com/equities-screener-api/screen-equities#set-the-language-and-currency). ## [Search by Name](#search-by-name) Return equities whose name contains a text string. Use `contains` for a substring match. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "basicReference.name": { "contains": "APP" } }, "dataPoints": [ "shareClassInformation.symbol", "basicReference.name" ] } ``` To tolerate spelling differences, use fuzzy search instead. The search text must be at least 3 characters. ```json "query": { "basicReference.name": { "value": "appel", "fuzzy": true } } ``` See [Equality and Text Filters](https://developer-beta.morningstar.com/equities-screener-api/equality-and-text-filters). ## [Page Through Results](#page-through-results) When a screen matches more investments than fit on one page, use the pagination tokens. The first request sets the page size. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "marketCapital.asOfDate": { "gt": "2020-01-01", "lt": "2024-03-31" } }, "dataPoints": [ "shareClassInformation.symbol", "marketCapital.asOfDate" ], "pagination": { "pageSize": 10 } } ``` The response includes `metadata.totalCount` and `metadata.paginationTokenNext`. To retrieve the second page, send the same request with the token. ```json { "scope": { "shareClassInformation.exchangeCode": "XPAR" }, "query": { "marketCapital.asOfDate": { "gt": "2020-01-01", "lt": "2024-03-31" } }, "dataPoints": [ "shareClassInformation.symbol", "marketCapital.asOfDate" ], "pagination": { "pageSize": 10, "paginationTokenNext": "{token from the previous response}" } } ``` Repeat until a response has no `paginationTokenNext`. See [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results#use-the-result-count-and-pagination-tokens). ## [Next Steps](#next-steps) - [Filter Conditions](https://developer-beta.morningstar.com/equities-screener-api/filter-conditions) covers every filter type in detail. - [Work with Results](https://developer-beta.morningstar.com/equities-screener-api/work-with-results) explains how to read the response and handle warnings. - [Troubleshooting](https://developer-beta.morningstar.com/equities-screener-api/troubleshooting) helps when a screen doesn't return what you expected.