Skip to content
Grid Reporting API
/
Grid API Filters
Last updated

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:

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

Filter Operators

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

OperatorApplies to
Column Types		Examples
string_containsstringFind pages whose final URL contains the string "example.com"
string_regexstringFind pages whose final URL matches regular expression ^example\.(com|org|net)
string_contains_multistringFind pages whose final URL contains any of the following strings: "example.com", "example.org", "example.net"
integer_innumberFind pages whose number of cookies is 1, 2, or 3
number_betweennumberFind pages with more than 20 cookies

Find pages with 10-20 cookies

Find pages with less than 10 cookies
date_time_betweentimestampFind pages visited between October 1, 2025 and October 31, 2025
date_time_relativetimestampFind page visited in the past 7 days
is_presentAllFind tags that have a consent category status
integer_list_containsentity_reference of array valuesFind 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 MatchingwildcardStartwildcardEndEquivalent Pseudocode (SQL)
Exact string matchfalsefalsevalue = arg
String starts withfalsetruevalue like "arg%"
String ends withtruefalsevalue like "%arg"
String containstruetruevalue 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":

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:

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"
          }
        }
      ]
    }
  }
}
Previous page
Next page