# Ga4 API

> Google Analytics 4 Data API Skill

- Skill: `buzzmatic/ga4-api` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add buzzmatic/ga4-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/buzzmatic/ga4-api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: Buzzmatic (https://skillmd.com/u/buzzmatic)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/buzzmatic/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:

```bash
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:**
```bash
--dimension-filter 'country equals US' \
--metric-filter 'sessions greaterThan 100'
```

**Date range comparison:**
```bash
--compare-start 2024-12-25 \
--compare-end 2024-12-31
```

### Batch Reports

Run multiple reports in a single API call:

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

Config file format:
```json
{
  "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):

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

### Pivot Reports

Create pivot table reports:

```bash
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:

```bash
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:

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

## Helper Scripts

### Traffic Overview

Quick traffic summary report:

```bash
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:

```bash
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:

```bash
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](references/api_reference.md) - Complete GA4 Data API documentation
- [Dimensions & Metrics](references/dimensions_metrics.md) - 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:

```json
{
  "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.