Filter Structures

Filter Structures

The correct shape for dimension_filter in get_ga4_data. Wrong structure returns an "Invalid dimension_filter" error. Use these templates.

The one rule

Every leaf filter must be wrapped in a "filter" key. fieldName never appears at the top level.

// WRONG — fieldName at top level
{"fieldName": "sessionSource", "stringFilter": {"value": "google"}}

// CORRECT — wrapped in "filter"
{"filter": {"fieldName": "sessionSource", "stringFilter": {"value": "google"}}}

Template: single field filter

{
  "filter": {
    "fieldName": "DIMENSION_NAME",
    "stringFilter": {
      "value": "VALUE",
      "matchType": "EXACT"
    }
  }
}

matchType options: EXACT, BEGINS_WITH, ENDS_WITH, CONTAINS, FULL_REGEXP, PARTIAL_REGEXP

Template: AND — all conditions must match

{
  "andGroup": {
    "expressions": [
      {"filter": {"fieldName": "deviceCategory", "stringFilter": {"value": "mobile", "matchType": "EXACT"}}},
      {"filter": {"fieldName": "country", "stringFilter": {"value": "United States", "matchType": "EXACT"}}}
    ]
  }
}

Template: OR — any condition matches

{
  "orGroup": {
    "expressions": [
      {"filter": {"fieldName": "sessionDefaultChannelGroup", "stringFilter": {"value": "Organic Search", "matchType": "EXACT"}}},
      {"filter": {"fieldName": "sessionDefaultChannelGroup", "stringFilter": {"value": "Organic Social", "matchType": "EXACT"}}}
    ]
  }
}

Template: NOT — exclude matching sessions

{
  "notExpression": {
    "filter": {
      "fieldName": "sessionDefaultChannelGroup",
      "stringFilter": {"value": "Direct", "matchType": "EXACT"}
    }
  }
}

Template: IN LIST — match any of several values

{
  "filter": {
    "fieldName": "country",
    "inListFilter": {
      "values": ["United States", "United Kingdom", "Canada"]
    }
  }
}

Common wrong keys → correct keys

Field names are always camelCase

⚠️ CRITICAL FILTER TRAP: Field names in dimension_filter (inside fieldName) MUST be exact camelCase. Passing page_path or session_default_channel_group will fail with an Unknown field for FilterExpression error.

If you use snake_case in fieldName, the filter will fail with an "Unknown field" error. Do NOT retry snake_case.

Note

Only dimensions can be filtered with dimension_filter. To filter on metric values (e.g. sessions > 100), you must do this in post-processing — the GA4 Data API does not support metric filters in RunReport.