Equities 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 Equities.

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.

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/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

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

Return the equity with a given symbol on one exchange. This is an equality filter with a single value.

{
  "scope": {
    "shareClassInformation.exchangeCode": "XPAR"
  },
  "query": {
    "shareClassInformation.symbol": "MSES"
  },
  "dataPoints": [
    "shareClassInformation.symbol",
    "shareClassInformation.investmentName",
    "marketCapital.asOfDate"
  ]
}

See Equality and Text Filters.

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.

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

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.

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

See Comparison Filters.

Filter by a Number Range

Return equities whose 24-month beta is greater than 4 and less than 10. Write numbers without quotation marks.

{
  "scope": {
    "shareClassInformation.exchangeCode": "XPAR"
  },
  "query": {
    "dividendResidualRiskAndReturnSensitivity.beta24Month": {
      "gt": 4,
      "lt": 10
    }
  },
  "dataPoints": [
    "shareClassInformation.symbol",
    "dividendResidualRiskAndReturnSensitivity.beta24Month"
  ]
}

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.

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

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.

{
  "scope": {
    "shareClassInformation.exchangeCode": "XPAR"
  },
  "query": {
    "or": [
      { "instrumentIdentifiers.performanceId": "0P0001VK70" },
      { "shareClassInformation.symbol": ["FM28", "MSES"] }
    ]
  },
  "dataPoints": [
    "shareClassInformation.symbol",
    "shareClassInformation.investmentStatus"
  ]
}

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.

{
  "scope": {
    "shareClassInformation.exchangeCode": "XPAR"
  },
  "query": {
    "not": [
      { "shareClassInformation.investmentStatus": 1 },
      { "shareClassInformation.symbol": "USSM" }
    ]
  },
  "dataPoints": [
    "shareClassInformation.symbol",
    "shareClassInformation.investmentStatus"
  ]
}

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.

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

"query": {
  "or": [
    {
      "and": [
        { "shareClassInformation.symbol": ["ALMIL"] },
        { "marketCapital.asOfDate": ["2025-01-06"] }
      ]
    },
    {
      "instrumentIdentifiers.performanceId": ["0P0001DIM8"]
    }
  ]
}

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.

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

Search by Name

Return equities whose name contains a text string. Use contains for a substring match.

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

"query": {
  "basicReference.name": { "value": "appel", "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": {
    "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.

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

Next Steps

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