--- title: "Example Screens" description: "Complete Managed Investments Screener API requests you can adapt: equality, range, compound and nested filters, sorting, currency and pagination." url: "https://developer-beta.morningstar.com/managed-investments-screener-api/example-screens" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RXhhbXBsZSBTY3JlZW5zIHwgTWFuYWdlZCBJbnZlc3RtZW50cyBTY3JlZW5lciBBUEk,description_~Q29tcGxldGUgTWFuYWdlZCBJbnZlc3RtZW50cyBTY3JlZW5lciBBUEkgcmVxdWVzdHMgeW91IGNhbiBhZGFwdDogZXF1YWxpdHksIHJhbmdlLCBjb21wb3VuZCBhbmQgbmVzdGVkIGZpbHRlcnMsIHNvcnRpbmcsIGN1cnJlbmN5IGFuZCBwYWdpbmF0aW9uLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9tYW5hZ2VkLWludmVzdG1lbnRzLXNjcmVlbmVyLWFwaS9leGFtcGxlLXNjcmVlbnMi,s_4_jZ2Ut2Lr_hW1cS.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) # Managed Investments Screener API Powerful, criteria-based screening using flexible filtering logic. # Example Screens [View Markdown](https://developer-beta.morningstar.com/managed-investments-screener-api/example-screens.md)[Download Markdown](https://developer-beta.morningstar.com/managed-investments-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 Investments](https://developer-beta.morningstar.com/managed-investments-screener-api/screen-investments). ## [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. - Country codes, currencies and other values are illustrative. Replace them with values that suit your own screen. - Before you use a data point in a filter, check that it supports the operator. See [Explore Data Points](https://developer-beta.morningstar.com/managed-investments-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/managed-investments" \ --header "Authorization: Bearer {token}" \ --header "Content-Type: application/json" \ --data '{ "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "basicReference.baseCurrency": "USD" }, "dataPoints": [ "basicReference.legalName", "basicReference.baseCurrency", "basicReference.name", "basicReference.firmName" ], "sort": [ { "dataPoint": "basicReference.legalName", "orderBy": "asc" } ], "pagination": { "pageSize": 5 } }' ``` ## [Examples at a Glance](#examples-at-a-glance) | Example | What It Shows | Filter Type | | :-------------------------------------- | :-------------------------------------------------------- | :---------- | | Find Investments by Base Currency | Matching a single value, with sorting on two data points. | Equality | | Find Investments in Several Currencies | Matching any of a list of values. | Equality | | Filter by a Date Range | Comparing dates. | 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. | Comparison | | Search by Name | Matching text. | Text | | Page Through Results | Retrieving a second page. | Pagination | ## [Find Investments by Base Currency](#find-investments-by-base-currency) Return investments available for sale in the USA whose base currency is US dollars. This is an equality filter with a single value. Results are sorted by legal name ascending, then by firm name descending. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "basicReference.baseCurrency": "USD" }, "dataPoints": [ "basicReference.legalName", "basicReference.baseCurrency", "basicReference.name", "basicReference.firmName" ], "sort": [ { "dataPoint": "basicReference.legalName", "orderBy": "asc" }, { "dataPoint": "basicReference.firmName", "orderBy": "desc" } ], "pagination": { "pageSize": 5 } } ``` The data points used in `sort` are also in `dataPoints`, as they must be. See [Equality and Text Filters](https://developer-beta.morningstar.com/managed-investments-screener-api/equality-and-text-filters). ## [Find Investments in Several Currencies](#find-investments-in-several-currencies) Return investments whose base currency is any of US dollars, British pounds or euros. A list of values matches any entry in the list. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "basicReference.baseCurrency": ["USD", "GBP", "EUR"] }, "dataPoints": [ "basicReference.legalName", "basicReference.baseCurrency", "basicReference.name", "basicReference.firmName" ], "sort": [ { "dataPoint": "basicReference.legalName", "orderBy": "asc" } ], "pagination": { "pageSize": 5 } } ``` ## [Filter by a Date Range](#filter-by-a-date-range) Return investments whose inception date is later than 1 January 2005 and earlier than 31 March 2024. Dates are strings in `yyyy-MM-dd` format. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "basicReference.inceptionDate": { "gt": "2005-01-01", "lt": "2024-03-31" } }, "dataPoints": [ "basicReference.legalName", "basicReference.name", "basicReference.inceptionDate" ], "sort": [ { "dataPoint": "basicReference.legalName", "orderBy": "asc" } ], "pagination": { "pageSize": 5 } } ``` 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/managed-investments-screener-api/comparison-filters). ## [Filter by a Number Range](#filter-by-a-number-range) Return investments whose 12-month yield is greater than 1.5 and less than 10.55. Write numbers without quotation marks. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "yieldsHistorical.12MoYield": { "gt": 1.5, "lt": 10.55 } }, "dataPoints": [ "basicReference.legalName", "basicReference.name", "basicReference.inceptionDate", "yieldsHistorical.12MoYield" ], "sort": [ { "dataPoint": "basicReference.legalName", "orderBy": "asc" } ], "pagination": { "pageSize": 5 } } ``` ## [Combine Conditions with And](#combine-conditions-with-and) Return investments that have a 12-month yield in a range and a base currency of US dollars. Every condition in the `and` array must match. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "and": [ { "yieldsHistorical.12MoYield": { "gt": 1.5, "lt": 10.55 } }, { "basicReference.baseCurrency": "USD" } ] }, "dataPoints": [ "basicReference.legalName", "basicReference.baseCurrency", "yieldsHistorical.12MoYield" ], "sort": [ { "dataPoint": "basicReference.legalName", "orderBy": "asc" } ], "pagination": { "pageSize": 5 } } ``` See [Compound Filters](https://developer-beta.morningstar.com/managed-investments-screener-api/compound-filters). ## [Match Any Condition with Or](#match-any-condition-with-or) Return investments that have a 12-month yield in a range, or a base currency of US dollars, or both. An investment is returned if it matches at least one condition. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "or": [ { "yieldsHistorical.12MoYield": { "gt": 1.5, "lt": 10.55 } }, { "basicReference.baseCurrency": "USD" } ] }, "dataPoints": [ "basicReference.legalName", "basicReference.baseCurrency", "yieldsHistorical.12MoYield" ], "sort": [ { "dataPoint": "basicReference.legalName", "orderBy": "asc" } ], "pagination": { "pageSize": 5 } } ``` ## [Exclude Investments with Not](#exclude-investments-with-not) Return investments whose 12-month yield isn't in the range and whose base currency isn't US dollars. The `not` operator excludes investments that match its conditions. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "not": [ { "yieldsHistorical.12MoYield": { "gt": 1.5, "lt": 10.55 } }, { "basicReference.baseCurrency": "USD" } ] }, "dataPoints": [ "basicReference.legalName", "basicReference.baseCurrency", "yieldsHistorical.12MoYield" ], "sort": [ { "dataPoint": "basicReference.legalName", "orderBy": "asc" } ], "pagination": { "pageSize": 5 } } ``` ## [Nest Filters](#nest-filters) Combine `or` and `and` to build more complex logic. The following screen returns investments that either have a portfolio date in a range and a low risk score, or have a Morningstar Rating of 4 or higher. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "or": [ { "and": [ { "basicReference.portfolioDate": { "gt": "2010-01-01", "lt": "2024-03-31" } }, { "morningstarPortfolioRiskScore.portfolioRiskScore": { "lte": 25.555 } } ] }, { "morningstarRatingHistorical.morningstarRatingOverall": { "gte": 4 } } ] }, "dataPoints": [ "basicReference.legalName", "basicReference.portfolioDate", "morningstarPortfolioRiskScore.portfolioRiskScore", "morningstarRatingHistorical.morningstarRatingOverall" ] } ``` The nesting can go the other way round. The following query returns investments in one of two base currencies that also have a high rating. ```json "query": { "and": [ { "or": [ { "basicReference.baseCurrency": "USD" }, { "basicReference.baseCurrency": "CAD" } ] }, { "morningstarRatingHistorical.morningstarRatingOverall": { "gte": 4 } } ] } ``` ## [Rank by a Currency-Dependent Data Point](#rank-by-a-currency-dependent-data-point) Return investments with a base currency of US dollars, ranked by their one-week total return, highest first. The return is currency-dependent, so the request sets `currencyId`. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "basicReference.baseCurrency": "USD" }, "dataPoints": [ "basicReference.legalName", "basicReference.baseCurrency", "dailyReturnsMostRecent.totalRet1WkDaily" ], "sort": [ { "dataPoint": "dailyReturnsMostRecent.totalRet1WkDaily", "orderBy": "desc" } ], "pagination": { "pageSize": 20 }, "currencyId": "EUR" } ``` For a language-dependent data point, set `languageId` in the same way. See [Screen Investments](https://developer-beta.morningstar.com/managed-investments-screener-api/screen-investments#set-the-language-and-currency). ## [Search by Name](#search-by-name) Return investments whose benchmark index contains a text string. Use `contains` for a substring match. ```json { "scope": { "basicReference.countryAvailableForSale": "USA" }, "query": { "investmentBasicDetails.mptIndex": { "contains": "bloo" } }, "dataPoints": [ "basicReference.legalName", "investmentBasicDetails.mptIndex" ] } ``` To tolerate spelling differences, use fuzzy search instead. The search text must be at least 3 characters. ```json "query": { "basicReference.legalName": { "value": "vangard", "fuzzy": true } } ``` See [Equality and Text Filters](https://developer-beta.morningstar.com/managed-investments-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": { "basicReference.countryAvailableForSale": "USA" }, "query": { "basicReference.inceptionDate": { "gt": "2005-01-01", "lt": "2024-03-31" } }, "dataPoints": [ "basicReference.legalName", "basicReference.inceptionDate" ], "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": { "basicReference.countryAvailableForSale": "USA" }, "query": { "basicReference.inceptionDate": { "gt": "2005-01-01", "lt": "2024-03-31" } }, "dataPoints": [ "basicReference.legalName", "basicReference.inceptionDate" ], "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/managed-investments-screener-api/work-with-results#use-the-result-count-and-pagination-tokens). ## [Next Steps](#next-steps) - [Filter Conditions](https://developer-beta.morningstar.com/managed-investments-screener-api/filter-conditions) covers every filter type in detail. - [Work with Results](https://developer-beta.morningstar.com/managed-investments-screener-api/work-with-results) explains how to read the response and handle messages. - [Troubleshooting](https://developer-beta.morningstar.com/managed-investments-screener-api/troubleshooting) helps when a screen doesn't return what you expected.