GA4: Saved Segment Definitions

GA4 has no public Segment API. We persist filter expressions locally and inject them into runReport calls - same effect for analytics, but they do not propagate to the GA4 UI or to Google Ads. Users who need cohorts visible inside GA4 should use the ga4-audiences skill instead. For funnel drop-off cohort analysis (read-only), use ga4-segments.

Storage: ~/.claude/ga4-definitions/segments/<slug>.json

No API call is made by this skill; auth is only needed when a segment is applied to a runReport via ga4-custom-report.

Commands

Shorthand operators

EXACT, CONTAINS, BEGINS_WITH, IN_LIST. For NOT, AND, OR groups, save as raw JSON.

Raw expression shape

A Data API FilterExpression dict, e.g.

{
  "and_group": {
    "expressions": [
      {"filter": {"field_name": "deviceCategory", "string_filter": {"value": "mobile", "match_type": "EXACT"}}},
      {"filter": {"field_name": "sessionSource", "string_filter": {"value": "brand", "match_type": "CONTAINS"}}}
    ]
  }
}

Applying a segment

Run a saved custom report with a segment applied:

python scripts/ga4_definitions.py --run-report channel-by-week --property 123 --segment "branded-traffic" --format html --output channel-branded.html

PII scrubbing also applies to Admin responses, cached data, context, MCP and rendered reports. Sensitive camelCase/custom-dimension keys and encoded email values are redacted; numeric metrics and GA resource names are retained. Scrubbing is a defensive filter, not a guarantee that arbitrary free text is anonymous. Saved-segment reports use one normal cached, scrubbed Data API call.