--- title: "Core Concepts" description: "Understand the key ideas behind the Managed Investments Screener API: scope, filter conditions, data points, sorting, pagination and results." url: "https://developer-beta.morningstar.com/managed-investments-screener-api/core-concepts" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~Q29yZSBDb25jZXB0cyB8IE1hbmFnZWQgSW52ZXN0bWVudHMgU2NyZWVuZXIgQVBJ,description_~VW5kZXJzdGFuZCB0aGUga2V5IGlkZWFzIGJlaGluZCB0aGUgTWFuYWdlZCBJbnZlc3RtZW50cyBTY3JlZW5lciBBUEk6IHNjb3BlLCBmaWx0ZXIgY29uZGl0aW9ucywgZGF0YSBwb2ludHMsIHNvcnRpbmcsIHBhZ2luYXRpb24gYW5kIHJlc3VsdHMu,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9tYW5hZ2VkLWludmVzdG1lbnRzLXNjcmVlbmVyLWFwaS9jb3JlLWNvbmNlcHRzIg,s__JuPajBsv84XQDbN.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. # Core Concepts [View Markdown](https://developer-beta.morningstar.com/managed-investments-screener-api/core-concepts.md)[Download Markdown](https://developer-beta.morningstar.com/managed-investments-screener-api/core-concepts.md) The Managed Investments Screener API finds managed investments that match criteria you define and returns the data you choose for each match. This page explains the terms used throughout the guide, so that requests and responses are easier to build and read. ## [How a Screen Works](#how-a-screen-works) A screen is a single request that describes what to look for and what to return. The API handles it in this order. 1. It starts from your entitled universe of managed investments. 2. It applies the **scope**, which sets the starting universe for the screen. 3. It applies the **query**, which narrows the universe with filter conditions. 4. It returns the **data points** you selected for each match, sorted and divided into pages. A request is made up of the following properties. | Property | Required | Purpose | | :--------- | :------- | :------------------------------------------------------------------------------- | | scope | Yes | Sets the starting universe of investments. | | query | Yes | Narrows the results with filter conditions. | | dataPoints | No | The data points to return for each match, up to 100. If you omit it, only the performance ID is returned. | | sort | No | The order of the results. The default is ascending performance ID. | | pagination | No | The number of results per page, and the tokens for moving between pages. | | languageId | No | The language for language-dependent data points. The default is ENG. | | currencyId | No | The currency for currency-dependent data points. The default is USD. | The API has two endpoints. One lists the data points that you can use, with their metadata. The other runs a screen. Use the first to find out what you can filter on, sort by and return, and the second to build the screen. ## [Entitled Universe](#entitled-universe) Every screen runs against the managed investments you are entitled to. A screen can never return an investment outside your entitled universe, whatever its scope and query say. Entitlements also apply to data points. Only the data points that you are entitled to are returned. If you request a data point that you aren't entitled to for a particular investment, the investment is still returned, and the response metadata explains which data points couldn't be returned. See [Results](#results). ## [Data Points](#data-points) A data point is a named value for a managed investment, such as a name, a base currency, an inception date or a yield. Data point names have the format `.`, for example `basicReference.baseCurrency` and `yieldsHistorical.12MoYield`. You use data points in three ways: - **To filter.** A filter condition applies to a data point. - **To return.** The `dataPoints` array lists the data points to include in the results. - **To sort.** The `sort` array orders results by a data point. The data point must also be in the `dataPoints` array. ### [Data Point Metadata](#data-point-metadata) The API describes each data point with metadata, which tells you how it can be used. | Metadata | Meaning | | :------------------- | :------------------------------------------------------------- | | Data type | The type of value, which determines the operators you can use. | | Operators | The filter operators the data point supports. | | Language dependency | Whether you must pass a languageId to retrieve the data point. | | Currency dependency | Whether you must pass a currencyId to retrieve the data point. | | Sortability | Whether you can sort by the data point. | | Fuzzy search support | Whether the data point supports fuzzy text matching. | ### [Data Types](#data-types) The data type determines which filters apply. | Data Type | Supported Filters | | :-------- | :--------------------------------------------------------- | | boolean | Equals. | | date | Range comparisons, equals and in. | | number | Range comparisons, equals and in. | | string | Equals and in. Some data points also support fuzzy search. | For how to find data points and read their metadata, see [Explore Data Points](https://developer-beta.morningstar.com/managed-investments-screener-api/explore-data-points). ## [Scope](#scope) The `scope` defines the starting universe of investments, limited to your entitled universe. For managed investments, it is defined with the `basicReference.countryAvailableForSale` data point. ```json "scope": { "basicReference.countryAvailableForSale": "USA" } ``` `scope` is written in the same way as a query, so it can use compound filters. If it does, each branch must contain the scoping data point. ## [Query and Filter Conditions](#query-and-filter-conditions) The `query` narrows the scoped universe. It is made up of **filter conditions**, each of which applies to one data point. The conditions fall into three kinds. | Kind | What It Does | Operators | | :--------- | :----------------------------------------------------------------------- | :--------------- | | Equality | Matches an exact value, or any value in a list. | eq, in | | Comparison | Compares numbers and dates. | gt, lt, gte, lte | | Compound | Combines other conditions with logic. Compound conditions can be nested. | and, or, not | A single condition names a data point and a value. ```json "query": { "basicReference.baseCurrency": "USD" } ``` A compound condition combines several conditions, here requiring both a base currency and a minimum Morningstar Rating. ```json "query": { "and": [ { "basicReference.baseCurrency": ["USD", "CAD"] }, { "morningstarRatingHistorical.morningstarRatingOverall": { "gte": 4 } } ] } ``` Filter conditions are the most important and most complex part of a request, so they have their own section. See [Filter Conditions](https://developer-beta.morningstar.com/managed-investments-screener-api/filter-conditions). ## [Languages and Currencies](#languages-and-currencies) Some data points depend on a language or a currency. For example, a data point that returns text in the language of your choice is language-dependent, and one that returns a monetary value or a return is currency-dependent. - Pass `languageId` to request language-dependent data points. The default is `ENG`. - Pass `currencyId` to request currency-dependent data points, using an ISO 4217 currency code. The default is `USD`. The metadata for each data point shows whether it has either dependency. ## [Sorting and Pagination](#sorting-and-pagination) **Sorting.** The `sort` array sets the order of the results. Each entry names a data point and a direction, `asc` or `desc`. Entries are applied in order, so later ones break ties in earlier ones. If you don't set a sort order, results are in ascending performance ID order. **Pagination.** Results are returned in pages. The default and maximum page size is 50. The response includes tokens for the next and previous pages, which you pass back in the `pagination` object to move between pages. Use one token in a request, not both. ## [Results](#results) A screen returns two things: the matching investments and metadata about the response. ```json { "investments": [ { "instrumentIdentifiers.performanceId": "0P0001UMFK", "basicReference.firmName": "Driftwood Euro Solutions LLC", "basicReference.name": "Ser 501TrbtHtlOldSanJuanNtsdue2027$Acc" } ], "metadata": { "totalCount": 10000, "paginationTokenNext": "{token}", "requestId": "d98e0f36-91b3-4cf3-bd61-15841ce6f9f8", "time": "2025-10-27T09:09:01.3362533Z" } } ``` - **Investments.** Each match is a flat object. Its keys are data point names, and its values are strings, numbers, integers or booleans, and can be null. The performance ID is included in every match. - **`totalCount`.** The total number of matches found, across all pages. - **Pagination tokens.** The tokens for retrieving the next and previous pages. - **`messages`.** Information about data points that couldn't be returned for an investment, such as data points that aren't entitled. A `200` response doesn't guarantee that every data point was returned for every investment, so check `messages` every time. - **`requestId` and `time`.** The identifier of the request and the time the response was returned. Include the `requestId` if you contact support. For details, see [Work with Results](https://developer-beta.morningstar.com/managed-investments-screener-api/work-with-results). ## [Next Steps](#next-steps) - [Explore Data Points](https://developer-beta.morningstar.com/managed-investments-screener-api/explore-data-points) to find the data points and operators you can use. - [Screen Investments](https://developer-beta.morningstar.com/managed-investments-screener-api/screen-investments) to build a complete request. - [Filter Conditions](https://developer-beta.morningstar.com/managed-investments-screener-api/filter-conditions) for the syntax and rules of filters. - [Work with Results](https://developer-beta.morningstar.com/managed-investments-screener-api/work-with-results) to read the response.