GA4: Custom Dimensions and Metrics

Scope required: analytics.edit.

Limits (standard properties, GA4 360 in parens)

• Event-scoped custom dimensions: 50 (125)
• User-scoped custom dimensions: 25 (100)
• Item-scoped custom dimensions: 10 (25)
• Custom metrics: 50 (125)

Before creating, list current definitions to check headroom:

python scripts/ga4_admin.py --property X --custom-defs --json

Commands

Validation

The script validates parameter_name before calling the API:

• Must start with a letter
• May contain letters, digits, underscores
• Length ≤ 40 (event-scoped) or 24 (user-scoped)
• Scope must be EVENT, USER, or ITEM

When to use

• EVENT: per-event metadata that varies across hits (logged_in_status, plan_tier, payment_provider, content_topic, video_quality)
• USER: durable user attributes that rarely change (membership_tier, signup_cohort, internal_user_id)
• ITEM: per-product / per-line-item catalog metadata used in ecomm items[] arrays (brand, supplier, category_path)

Cleanup

Archived definitions cannot be undone, but the slot is freed. Use the ga4-property agent to identify definitions with no data flowing.

Every Admin write is gated inside ga4_admin.py: it prints a scrubbed proposal and asks y/N for that operation. Run it in an interactive terminal; piped input, EOF and cancellation refuse the write. There is no bypass flag. MCP stdio tools provide previews; confirm=true returns confirmation_required without terminal approval. Never chain writes.

MCP propose_admin_write saves one exact Admin proposal for an expiring, single-use terminal approval. The user must run its approval_command and answer the existing y/N prompt themselves; agents must not supply approval. admin_proposal_status only reads the outcome. There is no MCP execute tool, and confirm=true remains insufficient. Refused or failed proposals cannot be replayed; applied:null means the result is unknown. See docs/APPROVALS.md.