Build a runReport request against the GA4 Data API v1 — pick valid metric/dimension combinations, set date ranges that respect data-freshness limits, apply filters, paginate large result sets…

MITAuto-check passed

Install Ga4 Data API Query

skills CLI
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill ga4-data-api-query -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install jeremylongshore/tons-of-skills-marketplace ga4-data-api-query --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.curated/ga4-data-api-query .claude/skills/ga4-data-api-query && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
ga4-data-api-query
GitHub stars
2.8k
Token cost
~2.4k tokens
SKILL.md length
716 words
Files
1
Skills in repo
3,342
Repo updated
First seen
Licence
MIT

At a glance

Build a runReport request against the GA4 Data API v1 — pick valid metric/dimension combinations, set date ranges that respect data-freshness limits, apply filters, paginate large result sets…

  • Works in 2 steps: User-scoped vs session-scoped vs… → High-cardinality custom dimensions can…
  • Fetch GA4 metrics
  • SKILL.md covers Overview, Prerequisites, Instructions and Examples, plus 11 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Ga4 Data API Query is an agent skill from jeremylongshore/tons-of-skills-marketplace. Build a runReport request against the GA4 Data API v1 — pick valid metric/dimension combinations, set date ranges that respect data-freshness limits, apply filters, paginate large result sets, handle sampling thresholds. Trigger with "query GA4", "GA4 Data API", "runReport", "fetch GA4 metrics", "GA4 pageviews", "GA4 sessions".

Its SKILL.md is about 2.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts. Compatibility notes: Designed for Claude Code

It works with Google Analytics. The repository describes itself as: Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com. The licence is MIT.

When your agent uses it

  • Fetch GA4 metrics

Example prompts

  • “query GA4”
  • “GA4 Data API”
  • “runReport”
  • “/ga4-data-api-query”

Requirements

  • Python 3
  • Compatibility (from SKILL.md): Designed for Claude Code
  • Pre-approved tools (allowed-tools): Bash(python3:*), Bash(curl:*)

Workflow steps

2 steps, taken from the first numbered list in SKILL.md.

  1. User-scoped vs session-scoped vs event-scoped dimensions don't always mix with each other's metrics. Stick to dimensions in the same scope…
  2. High-cardinality custom dimensions can trigger sampling. GA4 will silently sample if a single query touches more than the property's…

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Bash(python3:*)
    • Bash(curl:*)

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are python).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • ga-dev-tools.google

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Designed for Claude Code

    From compatibility in the SKILL.md frontmatter.

Context cost

Ga4 Data API Query loads about 2.4k tokens when it runs. Until then it costs about 87 tokens; SKILL.md has 716 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~87
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 716 words, ~2,404 tokens.

Download SKILL.mdSave it as .claude/skills/ga4-data-api-query/SKILL.md (or your agent's skills folder).
name
ga4-data-api-query
description
Build a runReport request against the GA4 Data API v1 — pick valid metric/dimension combinations, set date ranges that respect data-freshness limits, apply filters, paginate large result sets, handle sampling thresholds. Trigger with "query GA4", "GA4 Data API", "runReport", "fetch GA4 metrics", "GA4 pageviews", "GA4 sessions".
allowed-tools
Bash(python3:*), Bash(curl:*)
compatibility
Designed for Claude Code
version
1.3.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
saas, analytics, google-analytics, ga4, data-api

GA4 Data API v1 — runReport

Overview

The Data API v1 is the canonical read path for GA4. One endpoint (runReport) covers most use cases. Two paths matter for picking the right query: dimensions describe rows (date, page, source), metrics describe values (sessions, users, events). Not every combination is valid — see "Compatibility" below.

Prerequisite: auth working (see ga4-auth-setup).

Prerequisites

  • An authenticated GA4 Data API client with access to the target property; follow ga4-auth-setup first.
  • Python and the google-analytics-data package.
  • A numeric GA4 property ID and a bounded date range appropriate to the metric's freshness.

Instructions

Examples

The minimum viable query

python
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    RunReportRequest, DateRange, Metric, Dimension,
)

client = BetaAnalyticsDataClient()

req = RunReportRequest(
    property="properties/123456789",     # YOUR property ID (digits only)
    date_ranges=[
        DateRange(start_date="30daysAgo", end_date="today"),
    ],
    metrics=[Metric(name="activeUsers")],
    dimensions=[Dimension(name="date")],
)
resp = client.run_report(req)

for row in resp.rows:
    date = row.dimension_values[0].value     # YYYYMMDD string
    users = row.metric_values[0].value       # numeric string
    print(f"{date}: {users}")

That's the full skeleton. Everything below extends this shape.

The 12 metrics worth knowing

MetricWhat it countsNotes
activeUsersUnique users with engagement in the windowThe "users" people mean by default
newUsersFirst-seen users in the window
totalUsersAll users (engaged or not) — superset of activeUsers
sessionsSessions started in the windowRe-engages after 30min inactivity
engagedSessionsSessions ≥10s OR ≥2 pageviews OR ≥1 conversionThe "good" sessions
screenPageViewsPageviews + app screenviews combinedWhat people mean by "pageviews"
eventCountTotal event count (every event, not just page_view)Often misleadingly large
bounceRate(sessions - engagedSessions) / sessionsLower is better
averageSessionDurationAvg seconds per sessionAcross sessions, not engagedSessions
eventsPerSessioneventCount / sessions
conversionsEvents flagged as conversions in the property setupProperty-specific
totalRevenueSum of purchase event revenueCurrency = property default

bounceRate and averageSessionDuration are ratios — don't SUM them across rows; they're already aggregated within each row's group.

The 12 dimensions worth knowing

DimensionCardinalityWhen to use
dateLow (1/day)Time series
dateHourMedIntra-day patterns
pagePathHighTop-pages reports
pageTitleHighWhen path is opaque (e.g. SPA hash routes)
sessionSource / sessionMediumMedAttribution
sessionDefaultChannelGroupingLow (~12 channels)High-level traffic source breakdown
country / region / cityMed / Med / HighGeo
deviceCategoryLow (desktop/mobile/tablet)
browser / operatingSystemMedTech audit
landingPageHighEntry-page reports
eventNameMedEvent-level breakdowns
customEvent:<name>Property-specificIf you defined custom dimensions in the property setup

Compatibility — not every (dim, metric) combo is valid

GA4 enforces a compatibility matrix at the API level. If you ask for sessions + customEvent:purchaseId together you may get an empty result or a 400 INVALID_ARGUMENT. Two rules cover ~90% of cases:

  1. User-scoped vs session-scoped vs event-scoped dimensions don't always mix with each other's metrics. Stick to dimensions in the same scope as your headline metric where possible.
  2. High-cardinality custom dimensions can trigger sampling. GA4 will silently sample if a single query touches more than the property's data-quota threshold; the response includes metadata.dataLossFromOtherRow=true. Check it.

If you're unsure, query the compatibility metadata endpoint:

python
from google.analytics.data_v1beta.types import CheckCompatibilityRequest
compat = client.check_compatibility(CheckCompatibilityRequest(
    property="properties/123456789",
    dimensions=[Dimension(name="pagePath"), Dimension(name="sessionSource")],
    metrics=[Metric(name="screenPageViews"), Metric(name="sessions")],
))
print(compat)
Show full SKILL.md (288 more words)Show less

Filters

Filters are nested expressions. The common case: filter rows by a dimension value.

python
from google.analytics.data_v1beta.types import (
    FilterExpression, Filter, FilterExpressionList,
)

# Just pages under /docs/
docs_only = FilterExpression(
    filter=Filter(
        field_name="pagePath",
        string_filter=Filter.StringFilter(
            match_type=Filter.StringFilter.MatchType.BEGINS_WITH,
            value="/docs/",
            case_sensitive=False,
        ),
    ),
)

# AND combine: organic search AND not from referrer "spam.com"
combined = FilterExpression(
    and_group=FilterExpressionList(expressions=[
        FilterExpression(filter=Filter(
            field_name="sessionMedium",
            string_filter=Filter.StringFilter(
                match_type=Filter.StringFilter.MatchType.EXACT,
                value="organic",
            ),
        )),
        FilterExpression(not_expression=FilterExpression(filter=Filter(
            field_name="sessionSource",
            string_filter=Filter.StringFilter(
                match_type=Filter.StringFilter.MatchType.EXACT,
                value="spam.com",
            ),
        ))),
    ]),
)

req = RunReportRequest(
    property="properties/123456789",
    date_ranges=[DateRange(start_date="30daysAgo", end_date="today")],
    metrics=[Metric(name="sessions")],
    dimensions=[Dimension(name="pagePath")],
    dimension_filter=docs_only,
)

Use metric_filter for filtering by metric (e.g. only rows where sessions > 100). Same shape.

Date ranges

FormMeaning
"2026-05-01"Absolute (ISO date)
"30daysAgo"Relative — N days before today
"yesterday", "today"Named relative
"NdaysAgo" to "today"Standard rolling window

GA4 has 48-hour data freshness — today's numbers fluctuate; yesterday's settle ~24h after midnight in the property's timezone; numbers older than 48h are stable. Don't draw conclusions from "today" alone.

Multiple date_ranges in one request gives you a comparison report:

python
DateRange(start_date="30daysAgo", end_date="yesterday", name="current"),
DateRange(start_date="60daysAgo", end_date="31daysAgo", name="prior"),

The response will have dateRange as an extra dimension on each row.

Pagination

python
req = RunReportRequest(
    # ... as above
    limit=10_000,    # max 250_000 per request
    offset=0,
)
resp = client.run_report(req)
# resp.row_count is the TOTAL matching rows; resp.rows is the current page
while resp.row_count > req.offset + len(resp.rows):
    req.offset += len(resp.rows)
    resp = client.run_report(req)
    # process resp.rows

For result sets over ~1M rows, use ga4-bigquery-export instead.

Sampling — always check

python
resp = client.run_report(req)
if resp.metadata.data_loss_from_other_row:
    print("WARNING: data was sampled. Tighten date range, drop high-cardinality dimensions, or use BigQuery export for unsampled data.")

If sampled, results are statistically valid but not exact. For exact counts, BigQuery export is the only path.

Output

A successful runReport response contains dimension and metric values in rows, plus response metadata for pagination and data-quality signals. The examples print those rows; production callers should retain the metadata and handle empty result sets explicitly.

Error Handling

ErrorCauseFix
400 INVALID_ARGUMENT: dimension X is incompatible with metric YCompatibility matrix violationUse check_compatibility to find a valid combination
400 The request must contain at least one valid dimensionAll dimensions in the list are invalid (typo, deprecated name)Check the Dimensions & metrics explorer
503 RESOURCE_EXHAUSTEDPer-property quota hitWait 1h or raise quota; batch fewer queries
Empty rows despite valid queryDate range outside data window OR property has no data for that periodSanity-check with a known-good query (e.g. activeUsers over today)

Resources

  • ga4-auth-setup — prerequisite
  • ga4-realtime-api — for "right now" data instead of runReport's ~24h lag
  • ga4-common-reports — copy-paste recipes for the canonical 6-7 reports
  • ga4-bigquery-export — when you've outgrown the Data API

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/.curated/ga4-data-api-query of jeremylongshore/tons-of-skills-marketplace.

Open the folder on GitHubat commit cfae287

Compare with similar skills

Ga4 Data API Query next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Ga4 Data API Query compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Ga4 Data API Query this skilljeremylongshore/tons-of-skills-marketplace2.8k—~2.4kAutomated safety check: PassMIT
Google SEO APIsAgriciDaniel/claude-seo19k1 repos~4.2kAutomated safety check: PassMIT
AnalyticsNexus-JPF/note-companion8707 repos~2.2kAutomated safety check: PassMIT
Blog GoogleAgriciDaniel/claude-blog2.3k1 repos~3.3kAutomated safety check: NotesMIT
SEO GoogleAgriciDaniel/codex-seo7992 repos~3.4kAutomated safety check: PassMIT
C15tc15t/c15t1.9k1 repos~1.6kAutomated safety check: PassApache-2.0

Similar skills

  • Google SEO APIs

    AgriciDaniel/claude-seo

    Pulls real Google data for SEO work: Search Console, PageSpeed Insights, CrUX field data, the Indexing API and GA4 organic traffic, through /seo google commands.

    19k GitHub starsUsed in 1 repo~4.2k tokens
    Marketing & SEOAuto-check passed
  • Analytics

    Nexus-JPF/note-companion

    When the user wants to set up, improve, or audit analytics tracking and measurement.

    870 GitHub starsUsed in 7 repos~2.2k tokens
    Marketing & SEOAuto-check passed
  • Blog Google

    AgriciDaniel/claude-blog

    Google API integration for blog performance: PageSpeed Insights, CrUX Core Web Vitals with 25-week history, Search Console performance, URL Inspection, Indexing API, GA4 organic traffic, NLP entity…

    2.3k GitHub starsUsed in 1 repo~3.3k tokens
    Marketing & SEOAuto-check: notes
  • SEO Google

    AgriciDaniel/codex-seo

    Google SEO APIs: Search Console (Search Analytics, URL Inspection, Sitemaps), PageSpeed Insights v5, CrUX field data with 25-week history, Indexing API v3, and GA4 organic traffic.

    799 GitHub starsUsed in 2 repos~3.4k tokens
    Frontend & DesignAuto-check passed
  • C15t

    c15t/c15t

    Work with c15t consent management docs, APIs, and integrations for Next.js, React, and JavaScript.

    1.9k GitHub starsUsed in 1 repo~1.6k tokens
    Legal & ComplianceAuto-check passed
  • AI Visibility

    Ryze-AI-Adgent/open-seo-mcp-skills

    Measure real AI-engine visibility — traffic from ChatGPT, Perplexity, Claude, Gemini and which pages they cite — from actual GA4 referral data, not prompt sampling.

    4.7k GitHub stars~611 tokensUpdated 17 days ago
    Marketing & SEOAuto-check passed

More from jeremylongshore/tons-of-skills-marketplace

All 3,342 skills in this repo
  • Performing Security Code Review

    jeremylongshore/tons-of-skills-marketplace

    Execute this skill enables AI assistant to conduct a security-focused code review using the security-agent plugin.

    2.8k GitHub starsUsed in 2 repos~1.3k tokens
    Auto-check: notes
  • Adapting Transfer Learning Models

    jeremylongshore/tons-of-skills-marketplace

    Build this skill automates the adaptation of pre-trained machine learning models using transfer learning techniques.

    2.8k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Agent Context Loader

    jeremylongshore/tons-of-skills-marketplace

    Execute proactive auto-loading: automatically detects and loads agents.md files.

    2.8k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Aggregating Performance Metrics

    jeremylongshore/tons-of-skills-marketplace

    Aggregate and centralize performance metrics from applications, systems, databases, caches, and services.

    2.8k GitHub stars~1.2k tokensUpdated today
    Auto-check passed
  • Analyzing Capacity Planning

    jeremylongshore/tons-of-skills-marketplace

    Execute this skill enables AI assistant to analyze capacity requirements and plan for future growth.

    2.8k GitHub stars~947 tokensUpdated today
    Auto-check passed
  • Analyzing Database Indexes

    jeremylongshore/tons-of-skills-marketplace

    Process use when you need to work with database indexing. An agent skill from jeremylongshore/tons-of-skills-marketplace.

    2.8k GitHub stars~2k tokensUpdated today
    Auto-check passed

Questions about Ga4 Data API Query

What does Ga4 Data API Query do?

Build a runReport request against the GA4 Data API v1 — pick valid metric/dimension combinations, set date ranges that respect data-freshness limits, apply filters, paginate large result sets…. Ga4 Data API Query is an agent skill from jeremylongshore/tons-of-skills-marketplace. Build a runReport request against the GA4 Data API v1 — pick valid metric/dimension combinations, set date ranges that respect data-freshness limits, apply filters, paginate large result sets, handle sampling thresholds.

When should I use Ga4 Data API Query?

Ga4 Data API Query fits situations like: fetch GA4 metrics.

How do I install Ga4 Data API Query in Claude Code?

Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill ga4-data-api-query -a claude-code`. Or copy the skill folder (skills/.curated/ga4-data-api-query in jeremylongshore/tons-of-skills-marketplace) into .claude/skills/ga4-data-api-query in your project. Claude Code loads it when a task matches its description.

How do I install Ga4 Data API Query in Codex?

Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill ga4-data-api-query -a codex`. Or copy the skill folder (skills/.curated/ga4-data-api-query in jeremylongshore/tons-of-skills-marketplace) into .agents/skills/ga4-data-api-query in your project. Codex loads it when a task matches its description.

Can I use Ga4 Data API Query in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill ga4-data-api-query -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ga4-data-api-query, .gemini/skills/ga4-data-api-query, .github/skills/ga4-data-api-query and .opencode/skills/ga4-data-api-query in your project.

What does Ga4 Data API Query need to run?

SKILL.md names no scripts, command-line tools or credentials: Ga4 Data API Query is instructions for the agent only. Our summary lists: Python 3. Its frontmatter pre-approves these tools: Bash(python3:*), Bash(curl:*). Compatibility (from SKILL.md): Designed for Claude Code.

Does Ga4 Data API Query access the network?

SKILL.md names 1 domain. As links in the text: ga-dev-tools.google. This is read from the text; nothing was executed.

Is Ga4 Data API Query safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Ga4 Data API Query use?

Ga4 Data API Query is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Ga4 Data API Query use?

About 2.4k tokens (SKILL.md is roughly 9.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Ga4 Data API Query?

Skills that share tags, products or a category with Ga4 Data API Query: Google SEO APIs (AgriciDaniel/claude-seo, 19k stars), Analytics (Nexus-JPF/note-companion, 870 stars), Blog Google (AgriciDaniel/claude-blog, 2.3k stars) and SEO Google (AgriciDaniel/codex-seo, 799 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Ga4 Data API Query?

jeremylongshore (a GitHub user) maintains it in jeremylongshore/tons-of-skills-marketplace, which has 2,827 GitHub stars. The repository holds 3,342 skills in this directory. The repository was last updated on October 10, 2026.

Source: jeremylongshore/tons-of-skills-marketplace on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.