# Grid API Filters

You can filter the results from the Grid API using the optional `filters` field in your `POST` request.
Filters are composed of `conditions` that describe the data you want. Each condition has an `operator`
and a `filteredColumn` that describes the data you want to match.

## Simple Filter Example

This example matches only the pages that have `"example.com"` in their final URL:


```javascript Example filter request
{
  ... // other fields omitted for brevity
  "filters": {
    "conditions": [
      {
        "filteredColumn": {
          "columnId": "FINAL_PAGE_URL",
        }
        "operator": "string_contains",
        "arg": "example.com"
      }
    ]
  }
}
```

style

table td:first-child {
  white-space: nowrap;
}

## Filter Operators

The Grid API lets you filter by any of the following operators:

| Operator | Applies toColumn Types | Examples |
|  --- | --- | --- |
| `string_contains` | `string` | Find pages whose final URL contains the string `"example.com"` |
| `string_regex` | `string` | Find pages whose final URL matches regular expression `^example\.(com|org|net)` |
| `string_contains_multi` | `string` | Find pages whose final URL contains any of the following strings: `"example.com"`, `"example.org"`, `"example.net"` |
| `integer_in` | `number` | Find pages whose number of cookies is 1, 2, or 3 |
| `number_between` | `number` | Find pages with more than 20 cookiesFind pages with 10-20 cookiesFind pages with less than 10 cookies |
| `date_time_between` | `timestamp` | Find pages visited between October 1, 2025 and October 31, 2025 |
| `date_time_relative` | `timestamp` | Find page visited in the past 7 days |
| `is_present` | All | Find tags that have a consent category status |
| `integer_list_contains` | `entity_reference` of array values | Find tags that are either Adobe Analytics or Google Analytics |


## String Matching

The Grid API is designed to minimize the number of operators while maximizing your expressive power. One example
of this is the `string_contains` operator, which can provide the following functionality:

* Exact string match
* String starts with
* String ends with
* String contains


This is done with the `wildcardStart` and `wildcardEnd` boolean fields, which tell the Grid API to
interpret the `arg` value as a pattern that should allow (or disallow) strings before or after the
`arg` value.

How to use the `wildcardStart` and `wildcardEnd` fields:

| String Matching | `wildcardStart` | `wildcardEnd` | Equivalent Pseudocode (SQL) |
|  --- | --- | --- | --- |
| Exact string match | `false` | `false` | `value = arg` |
| String starts with | `false` | `true` | `value like "arg%"` |
| String ends with | `true` | `false` | `value like "%arg"` |
| String contains | `true` | `true` | `value like "%arg%"` |


### Exact Match Example with `string_contains`

If you set both `wildcardStart` and `wildcardEnd` to `false`, the `arg` value is interpreted as an exact match.

Exact match example for pages whose base domain exactly matches `"example.com"`:


```javascript Example exact string match filter
{
  ... // other fields omitted for brevity
  "filters": {
    "conditionMatchMode": "all",
    "conditions": [
      {
        "filteredColumn": {
          "columnId": "FINAL_PAGE_URL_BASE_DOMAIN"
        },
        "operator": "string_contains",
        "arg": "example.com",
        // These are used to do exact match
        "wildcardStart": false,
        "wildcardEnd": false
      }
    ]
  }
}
```

## Combining Filters

The Grid API lets you express complex filter criteria:

* You can combine `conditions` with a logical "and" or "or" using the `conditionMatchMode` field.
* You can negate any filter condition by specifying `"negated": true` in the condition.


Here's an example filter that finds tags which were found **either** within the past 10 days **or** more than 90 days ago:


```javascript Example filter
{
  ... // other fields omitted for brevity
  "filters": {
    {
      "conditionMatchMode": "any", // this is logical "or" mode
      "conditions": [
        {
          "startDuration": 90,
          "startUnit": "day",
          "operator": "date_time_relative",
          "filteredColumn": {
            "columnId": "ABSOLUTE_PAGE_VISIT_START_TIME"
          }
        },
        {
          "startDuration": 10,
          "startUnit": "day",
          "operator": "date_time_relative",
          "filteredColumn": {
            "columnId": "ABSOLUTE_PAGE_VISIT_START_TIME"
          }
        }
      ]
    }
  }
}
```