Managed Investments Screener API

Powerful, criteria-based screening using flexible filtering logic.

Example Screens

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.

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.

The following request shows how an example is sent. The body is the first example on this page.

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

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

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.

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

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.

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

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.

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

See Comparison Filters.

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.

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

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.

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

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.

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

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.

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

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.

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

"query": {
  "and": [
    {
      "or": [
        { "basicReference.baseCurrency": "USD" },
        { "basicReference.baseCurrency": "CAD" }
      ]
    },
    {
      "morningstarRatingHistorical.morningstarRatingOverall": { "gte": 4 }
    }
  ]
}

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.

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

Search by Name

Return investments whose benchmark index contains a text string. Use contains for a substring match.

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

"query": {
  "basicReference.legalName": { "value": "vangard", "fuzzy": true }
}

See Equality and Text Filters.

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.

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

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

Next Steps

Filter Conditions covers every filter type in detail.
Work with Results explains how to read the response and handle messages.
Troubleshooting helps when a screen doesn't return what you expected.