GA4 Pull

skill

Pull GA4 (Google Analytics 4) metrics via API and normalize them into a working file.

Download .md

GA4 Pull

Pull GA4 (Google Analytics 4) metrics via the Google Analytics Data API and normalize the results into a clean working file for downstream reporting.

When to use

  • A human or another agent asks for current traffic, conversion, or engagement metrics from GA4.
  • A recurring marketing report needs fresh GA4 numbers pulled and reshaped before it can be summarized.
  • Another skill or task depends on a normalized GA4 dataset (CSV/JSON) rather than raw API output.

Tools

  • http-get: calls the GA4 Data API to retrieve report data (dimensions, metrics, date ranges).
  • shell-execute: runs a small script to parse, dedupe, and normalize the raw API response into a consistent tabular structure.
  • write-file: saves the normalized metrics to a working file for reuse by later steps or other agents.

Playbook

  1. Confirm the GA4 property ID, date range, and the specific dimensions/metrics requested before making any call.
  2. Call the Google Analytics Data API with http-get (e.g. GET https://analyticsdata.googleapis.com/v1beta/properties/{propertyId}:runReport with query params for dimensions, metrics, and date range). Authentication is injected by the org's Integration row for this host — never ask for, echo, or hardcode credentials.
  3. If the call returns 401/403 or no Integration row exists, stop and message a human via send-message asking them to create the Integration, naming the service (Google Analytics 4) and required scopes.
  4. If the response body is empty or contains zero rows, re-check the property ID, date range, and dimension/metric names, then retry http-get once with corrected parameters.
  5. Use shell-execute to run a short script that parses the raw JSON response, flattens dimension/metric rows into a simple table, and removes duplicate rows.
  6. Use shell-execute to normalize field names and units (e.g. consistent date format, numeric types for counts and rates) across the dataset.
  7. Use write-file to save the normalized dataset (CSV or JSON) to a working file with a clear, descriptive name and the date range in the filename or header.
  8. Note any GA4 report update/edit requests are out of scope — the Data API is read-only for this skill; if someone asks to modify a GA4 configuration or saved report, hand that off to a human via send-message rather than attempting it.
  9. Summarize the pull (property, date range, row count, output file location) when completing the task.

Failure modes

  • 401/403 response: missing or invalid Integration for the GA4 host — stop and escalate via send-message naming the required scopes.
  • Empty result set: verify the property ID, date range, and dimension/metric names are correct, then retry with corrected parameters.
  • Rate limit (429) response: back off before retrying and record the rate-limit encounter via update-memory so future pulls space out calls.
  • Unexpected schema or missing fields in the response: treat as a page/API change and fall back to browser-search to check for GA4 API updates before retrying.

Done when

  • The GA4 Data API call succeeds and returns a non-empty report for the requested property and date range.
  • A normalized working file has been written via write-file containing consistent, deduplicated rows of the requested metrics.
  • The task summary names the output file location, date range covered, and row count pulled.