Ga4 API

Google Analytics 4 Data API Skill

Fetch and process data from the GA4 Data API v1.

Quick Start

All scripts:

• Save raw JSON and processed CSV to ./output/ (override with --output-dir)
• Return JSON with {"output_files": [...], "summary": "..."}

Core Operations

Standard Reports

Fetch GA4 data with flexible dimensions and metrics:

python skills/ga4-api/scripts/run_report.py \
  --property-id 123456789 \
  --start-date 2025-01-01 \
  --end-date 2025-01-07 \
  --dimensions date,sessionSource,sessionMedium \
  --metrics sessions,totalUsers,conversions \
  --row-limit 10000

Common dimension combinations:

• date - Daily trends
• sessionSource,sessionMedium - Traffic sources
• pagePath - Top pages
• country,city - Geographic breakdown
• deviceCategory - Device types
• eventName - Event analysis

Optional filters:

--dimension-filter 'country equals US' \
--metric-filter 'sessions greaterThan 100'

Date range comparison:

--compare-start 2024-12-25 \
--compare-end 2024-12-31

Batch Reports

Run multiple reports in a single API call:

python skills/ga4-api/scripts/batch_reports.py \
  --property-id 123456789 \
  --config-file reports_config.json

Config file format:

{
  "date_range": {"start": "2025-01-01", "end": "2025-01-07"},
  "reports": [
    {"name": "traffic_sources", "dimensions": ["sessionSource"], "metrics": ["sessions", "totalUsers"]},
    {"name": "top_pages", "dimensions": ["pagePath"], "metrics": ["screenPageViews", "averageSessionDuration"]}
  ]
}

Realtime Reports

Fetch real-time data (last 30 minutes):

python skills/ga4-api/scripts/realtime_report.py \
  --property-id 123456789 \
  --dimensions unifiedScreenName \
  --metrics activeUsers

Pivot Reports

Create pivot table reports:

python skills/ga4-api/scripts/pivot_report.py \
  --property-id 123456789 \
  --start-date 2025-01-01 \
  --end-date 2025-01-07 \
  --dimensions sessionSource,sessionMedium \
  --pivot-dimension deviceCategory \
  --metrics sessions

Funnel Reports

Analyze user funnels:

python skills/ga4-api/scripts/funnel_report.py \
  --property-id 123456789 \
  --start-date 2025-01-01 \
  --end-date 2025-01-07 \
  --funnel-steps "session_start,page_view,purchase"

List Properties

List accessible GA4 properties:

python skills/ga4-api/scripts/list_properties.py

Helper Scripts

Traffic Overview

Quick traffic summary report:

python skills/ga4-api/scripts/helpers/traffic_overview.py \
  --property-id 123456789 \
  --start-date 2025-01-01 \
  --end-date 2025-01-07

Conversion Report

Focused conversion analysis:

python skills/ga4-api/scripts/helpers/conversion_report.py \
  --property-id 123456789 \
  --start-date 2025-01-01 \
  --end-date 2025-01-07 \
  --conversion-events purchase,sign_up

Engagement Report

User engagement metrics:

python skills/ga4-api/scripts/helpers/engagement_report.py \
  --property-id 123456789 \
  --start-date 2025-01-01 \
  --end-date 2025-01-07

Advanced Topics

For detailed API parameters, dimension/metric lists, and filter syntax, see:

• API Reference - Complete GA4 Data API documentation
• Dimensions & Metrics - Full list of available fields

Authentication

Scripts authenticate to Google via the shared lib/google_auth helper. Provide OAuth2 credentials through environment variables (or a .env file at the repo root):

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_REFRESH_TOKEN

Alternatively, place a token file under secrets/ at the repo root (e.g. secrets/ga4_token.json or a unified token). Service-account JSON key files are also supported. The GA4 scope is https://www.googleapis.com/auth/analytics.readonly.

Output Format

All scripts return:

{
  "output_files": [
    "output/ga4_report_raw.json",
    "output/ga4_report.csv"
  ],
  "summary": "Fetched 1,247 rows: 50,234 sessions, 42,567 users",
  "stats": {
    "rows": 1247,
    "property_id": "123456789",
    "date_range": "2025-01-01 to 2025-01-07",
    "dimensions": ["date", "sessionSource"],
    "metrics": ["sessions", "totalUsers"]
  }
}

Rate Limits and Best Practices

• Quota: 10,000 requests per day per project
• Concurrent: Up to 10 concurrent requests
• Row limit: 100,000 rows per request (use pagination for more)
• Batch limit: Up to 5 reports per batch request

Scripts include automatic retry with exponential backoff for rate limit errors.