ga4-api-reporting

GA4 Data API Reporting Guide

Complete guide for using the GA4 Data API for custom reporting and automated dashboards.

Quick Note: Ad Superpowers MCP Tool

The Ad Superpowers MCP server wraps the GA4 Data API into the ga4_run_report() tool, which handles authentication and pagination automatically. Use it for ad-hoc analysis before building custom API integrations:

ga4_run_report(
    property_id="YOUR_PROPERTY_ID",
    metrics=["sessions", "activeUsers", "keyEvents"],
    dimensions=["date", "sessionDefaultChannelGroup"],
    start_date="30daysAgo",
    end_date="yesterday"
)

For programmatic/automated reporting, use the GA4 Data API v1 (v1beta) directly as documented below. The API base URL is analyticsdata.googleapis.com/v1beta/ — no v2 exists as of 2026.

Available Metrics & Dimensions

COMMONLY USED DIMENSIONS
=========================

USER & SESSION:
├── userId (custom user ID)
├── userAgeBracket
├── userGender
├── newVsReturning
├── sessionSource
├── sessionMedium
├── sessionSourceMedium
├── sessionCampaignName
└── sessionDefaultChannelGroup

TIME:
├── date (YYYYMMDD)
├── dateHour
├── dateHourMinute
├── dayOfWeek
├── hour
├── month
└── year

PAGE & SCREEN:
├── pagePath
├── pageTitle
├── pagePathPlusQueryString
├── landingPage
├── exitPage
└── screenName

DEVICE & GEO:
├── deviceCategory
├── platform
├── browser
├── operatingSystem
├── country
├── city
└── region

E-COMMERCE:
├── itemName
├── itemId
├── itemBrand
├── itemCategory
├── transactionId
└── orderCoupon

COMMONLY USED METRICS
======================

USERS & SESSIONS:
├── activeUsers
├── newUsers
├── totalUsers
├── sessions
├── sessionsPerUser
├── engagedSessions
├── averageSessionDuration
└── bounceRate

ENGAGEMENT:
├── screenPageViews
├── screenPageViewsPerSession
├── eventCount
├── engagementRate
└── userEngagementDuration

E-COMMERCE:
├── ecommercePurchases
├── transactions
├── purchaseRevenue
├── totalRevenue
├── averagePurchaseRevenue
├── itemsPurchased
├── itemRevenue
└── itemsViewed

KEY EVENTS (CONVERSIONS):
├── keyEvents (current metric name — was "conversions" before March 2024, both still work in API)
├── keyEventRate
├── eventValue
└── [customEvent]:eventCount

FULL LIST:
──────────
developers.google.com/analytics/devguides/reporting/data/v1/api-schema