filter-structures

name	filter-structures
description	The correct shape for `dimension_filter` in `get_ga4_data`. Wrong structure returns an "Invalid dimension_filter" error. Use these templates.

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

Wrong key	Correct key
and_filter	andGroup
or_filter	orGroup
not_filter	notExpression
filters	expressions
field	fieldName
stringFilter.exact	stringFilter.value

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.

Wrong (snake_case)	Correct (camelCase)
page_path	pagePath
session_default_channel_group	sessionDefaultChannelGroup
session_source	sessionSource
session_source_medium	sessionSourceMedium
session_campaign_name	sessionCampaignName
landing_page	landingPage
device_category	deviceCategory
event_name	eventName

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.