---
title: "Compound Filters"
description: "Combine Equities Screener API filter conditions with and, or and not, nest them for complex logic, and use them in the scope."
url: "https://developer-beta.morningstar.com/equities-screener-api/compound-filters"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~Q29tcG91bmQgRmlsdGVycyB8IEVxdWl0aWVzIFNjcmVlbmVyIEFQSQ,description_~Q29tYmluZSBFcXVpdGllcyBTY3JlZW5lciBBUEkgZmlsdGVyIGNvbmRpdGlvbnMgd2l0aCBhbmQsIG9yIGFuZCBub3QsIG5lc3QgdGhlbSBmb3IgY29tcGxleCBsb2dpYywgYW5kIHVzZSB0aGVtIGluIHRoZSBzY29wZS4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9lcXVpdGllcy1zY3JlZW5lci1hcGkvY29tcG91bmQtZmlsdGVycyI,s_Bs4iiuy3rR149RZ6.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.

# Compound Filters

[View Markdown](https://developer-beta.morningstar.com/equities-screener-api/compound-filters.md)[Download Markdown](https://developer-beta.morningstar.com/equities-screener-api/compound-filters.md)

Compound filters combine other filter conditions into one. Use them when a screen needs more than one condition, or when the logic is more than a simple match.

## [Compound Operators](#compound-operators)

| Operator | Meaning                            |
| :------- | :--------------------------------- |
| and      | All conditions must match.         |
| or       | At least one condition must match. |
| not      | None of the conditions can match.  |

Each operator takes an array of conditions.

```json
{
  "<operator>": [
    { "<dataPointA>": "<value>" },
    { "<dataPointB>": { "gt": "<value>" } }
  ]
}
```

Every element of the array is itself a filter condition. It can be an equality, text or comparison filter, or another compound filter.

Write the operators in lowercase.

## [Require All Conditions with And](#require-all-conditions-with-and)

The following query returns investments that match both a performance ID in the list and a symbol in the list.

```json
"query": {
  "and": [
    {
      "instrumentIdentifiers.performanceId": [
        "0P0001VK70",
        "0P0001VK71",
        "0P0001VK72"
      ]
    },
    {
      "shareClassInformation.symbol": ["CA40", "MSES"]
    }
  ]
}
```

## [Require Any Condition with Or](#require-any-condition-with-or)

The following query returns investments that match the performance ID, or have a symbol in the list, or both.

```json
"query": {
  "or": [
    { "instrumentIdentifiers.performanceId": "0P0001VK70" },
    { "shareClassInformation.symbol": ["FM28", "MSES"] }
  ]
}
```

## [Exclude Conditions with Not](#exclude-conditions-with-not)

The `not` operator excludes investments that match its conditions. The following query returns investments whose status isn't `1` and whose symbol isn't `USSM`.

```json
"query": {
  "not": [
    { "shareClassInformation.investmentStatus": 1 },
    { "shareClassInformation.symbol": "USSM" }
  ]
}
```

## [Nest Compound Filters](#nest-compound-filters)

Compound filters can be nested to any level you need, so you can build complex logic. The following query returns securities that trade in US dollars or Canadian dollars, that are one of two security types, and that have a market capital date in a range.

```json
"query": {
  "and": [
    {
      "or": [
        { "shareClassInformation.tradingCurrency": "USD" },
        { "shareClassInformation.tradingCurrency": "CAD" }
      ]
    },
    {
      "shareClassInformation.securityType": ["ST00000001", "ST00000002"]
    },
    {
      "marketCapital.asOfDate": { "gt": "2020-01-01", "lt": "2024-03-31" }
    }
  ]
}
```

To read a nested filter, start at the outermost operator and work inward. Here, all three conditions in the outer `and` must match, and the first of them is satisfied by either of its two inner conditions.

The following query combines `or` and `and` the other way round. It returns an investment that matches a symbol and a market capital date together, or an investment with a given performance ID.

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

## [Use Compound Filters in the Scope](#use-compound-filters-in-the-scope)

The `scope` uses the same syntax as the `query`, so it can also be a compound filter. When it is, each branch must contain the exchange code data point, which is the scoping data point for equities.

The following scope covers two exchanges, with a different condition on each.

```json
"scope": {
  "or": [
    {
      "and": [
        { "shareClassInformation.exchangeCode": "XPAR" },
        { "shareClassInformation.securityType": "ST00000001" }
      ]
    },
    {
      "and": [
        { "shareClassInformation.exchangeCode": "XNAS" },
        { "shareClassInformation.securityType": "ST00000002" }
      ]
    }
  ]
}
```

A branch without the exchange code isn't a valid scope.

## [Tips](#tips)

-   Use a compound filter whenever you combine conditions, even if only two. It makes the logic explicit.
-   Keep each element of the array to one condition. Group related conditions in a nested filter.
-   Check each data point's metadata to be sure it supports the operator in the condition. See [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points).