Run up to 5 GA4 reports in a single round-trip.

requests: list of run_report-shaped dicts. Same top-level parameters as ga4_run_report (minus property_id, inferred from the batch). Each entry accepts: dimensions, metrics, date_ranges, dimension_filter, metric_filter, order_bys, metric_aggregations, limit, offset, keep_empty_rows, currency_code.

Useful when the agent needs paired views (e.g. landing pages + referrers for the same window) and wants them atomically + under one quota call.

Validate whether a dim/metric combo can be queried together. Cheap pre-flight.

compatibility_filter: 'COMPATIBLE' (default, returns only fields that work with the provided selection) or 'INCOMPATIBLE' (returns only fields that would conflict).

Use before run_report when composing exploratory queries, cheaper than catching a GoogleAdsException after a big failed report.

Fetch the full GA4 dimension + metric catalog for a property.

If property_id is omitted, returns the universal catalog (excludes property-specific custom fields). Pass a property_id to include custom dimensions and metrics like 'customEvent:foo' and 'customUser:signup_plan'.

Response: {"dimensions": [...], "metrics": [...]}. Each entry has api_name, ui_name, description, category, custom_definition.

Call this before run_report when the agent is uncertain about field names: GA4's catalog is large and custom fields require the property to resolve.

Full metadata for a single GA4 property.

Returns display_name, property_type, parent account, time_zone, currency_code, industry_category, service_level, delete_time, expire_time, account reference, create_time, update_time.

property_id: numeric (e.g. "123456789") or resource (e.g. "properties/123456789").

List every GA4 account and its child properties accessible to this service account.

CALL THIS FIRST to discover which property_id to pass into other tools. The SA only sees accounts/properties where its email has been explicitly added as a user.

Response: {"accounts": [{account, display_name, property_summaries: [...], ...}]}. Each property_summary has property, display_name, property_type, parent.

List audiences defined on a GA4 property.

Each audience has name, display_name, description, membership_duration_days, ads_personalization_enabled, event_trigger, exclusion_duration_mode, filter_clauses. Reference audienceId as a dimension in run_report for audience-based breakdowns.

NOTE: Uses Admin v1alpha since audiences are still alpha in April 2026.

List custom dimensions configured on a GA4 property.

Each entry contains the parameter_name (how you query it, use prefix 'customEvent:' or 'customUser:' when passing to get_metadata / run_report), display_name, scope (EVENT|USER|ITEM), and description. Essential grounding before running reports that reference custom fields.

List custom metrics configured on a GA4 property.

Each entry: parameter_name, display_name, measurement_unit, scope, restricted_metric_type.

List all data streams (web, iOS, Android) on a GA4 property.

Useful for finding the Measurement ID (web), firebase_app_id (mobile), or the hostname of a web stream. Each stream has its creation/update timestamps.

List Google Ads links attached to a GA4 property.

Returns customer_id (the Ads account), can_manage_clients, ads_personalization_enabled, and creator_email. Useful to confirm Ads ↔ GA4 cross-reporting availability before querying Ads-related dimensions like sessionGoogleAdsCampaignId.

List key events (formerly conversions) on a GA4 property.

These are the events the client has marked as conversion-worthy. Query conversion metrics via conversions dimension or direct metric names.

List reporting annotations on a GA4 property.

Annotations are markers (user-added or Google-system) flagging important events on a timeline: product launches, outages, marketing pushes, so downstream analysis can correlate metric swings with known events.

Each annotation has: name, title, description, annotation_date, annotation_date_range, color, creator_email, system_generated.

NOTE: Uses Admin v1alpha since annotations are still alpha in April 2026.

Audit log of who-read-what on a GA4 property (last 12 months).

dimensions (common): userEmail, accessedPropertyName. metrics: accessCount. date_ranges: list of {start_date, end_date} (YYYY-MM-DD or relative). Defaults to last 7d.

Use cases: identify usage of GA4 data by staff, confirm SA activity, compliance audits.

Run a GA4 funnel report. v1alpha, API surface may change.

funnel: { is_open_funnel: bool, steps: [ { name: str, is_directly_followed_by: bool, filter_expression: FunnelFilterExpression, within_duration_from_prior_step: {seconds: int}, }, ... ] } funnel_breakdown: {dimension_name, limit}, optional per-step breakdown. funnel_next_action: {dimension_name, limit}, optional "what came after".

Use for drop-off analysis across a sequence of events. Behind an alpha flag because Google can change the shape, check the Feb 2026 release notes if this fails with a validation error.

Ref: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/runFunnelReport

Run a GA4 pivot report.

pivots: list of pivot specs, each with:

• field_names: list of dimension names to pivot on

• limit: max rows per pivot

• offset: pagination offset

• order_bys: list of OrderBy dicts (same shape as run_report's order_bys)

• metric_aggregations: list of TOTAL|MINIMUM|MAXIMUM|COUNT

Use when you want a 2D view: e.g. rows=date, columns=device, values=sessions.

Run a GA4 real-time report. Covers the last 30 minutes only.

IMPORTANT: realtime uses a SEPARATE, smaller dimension/metric catalog. Do NOT pass 'date', 'totalRevenue', etc: they don't exist in realtime. Common dims: 'minutesAgo', 'country', 'deviceCategory', 'unifiedScreenName', 'eventName'. Common metrics: 'activeUsers', 'screenPageViews', 'eventCount'.

minute_ranges: list of {start_minutes_ago, end_minutes_ago, name?}. Max 2 ranges. Values are 0-29 (0 = now, 29 = 30 min ago).

For historical / batch reports use ga4_run_report instead.

Run a GA4 standard report. The workhorse tool.

Args: property_id: numeric or 'properties/NNN'. dimensions: list of dimension api_names (e.g. ["country", "deviceCategory", "date"]). Custom dims require 'customEvent:' or 'customUser:' prefixes. metrics: list of metric api_names (e.g. ["activeUsers", "sessions", "totalRevenue"]). date_ranges: list of {start_date, end_date, name?}. Accepts 'YYYY-MM-DD', 'NdaysAgo', 'today', 'yesterday'. Up to 4 ranges. dimension_filter / metric_filter: filter expression dicts. Shapes: {"filter": {"field_name": "country", "string_filter": {"value": "US"}}} {"and_group": {"expressions": [...]}} {"or_group": {"expressions": [...]}} {"not_expression": {...}} order_bys: list of {metric: {metric_name}, desc} or {dimension: {...}}. metric_aggregations: list of TOTAL|MINIMUM|MAXIMUM|COUNT. limit: max rows (hard cap 250000 per response). offset: pagination offset. keep_empty_rows: include rows where all metrics are zero. currency_code: override property default for revenue metrics. cohort_spec / comparisons: advanced specs (see REST docs).

Gotchas surfaced in response.metadata:

• samplingMetadatas: present if query was sampled (> 10M events scanned)

• dataLossFromOtherRow: true if high-cardinality dims collapsed into "(other)"

• schemaRestrictionResponse: active thresholding rules

• subjectToThresholding: true if user-privacy thresholding dropped rows

propertyQuota always included so the agent can self-throttle.