Google Analytics 4

Get the status and metadata of an audience export.

Use this after calling create_audience_export to check whether the export has
completed processing. The response includes:
  - name: resource name of the export
  - audience: which audience was exported
  - audienceDisplayName: human-readable name
  - state: "CREATING", "ACTIVE", "FAILED"
  - beginCreatingTime / creationQuotaTokensCharged
  - rowCount: number of users in the export (once active)
  - dimensions: which dimensions were requested

Poll this endpoint until state === "ACTIVE" before calling query_audience_export.

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/get

List all audience exports for a GA4 property.

Returns an array of audience export resources with their current state,
audience info, dimensions, and row counts. Useful for discovering existing
exports or checking on multiple exports at once.

Each export in the list includes:
  - name: full resource name
  - audience / audienceDisplayName
  - state: "CREATING", "ACTIVE", or "FAILED"
  - dimensions, rowCount, creation time, etc.

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/list

Retrieve only the custom dimensions and custom metrics defined for a GA4 property.

This is a convenience wrapper around get_metadata that filters results to only
include fields where customDefinition === true.

Returns:
  {
    custom_dimensions: [ {apiName, uiName, description, ...}, ... ],
    custom_metrics:    [ {apiName, uiName, description, ...}, ... ]
  }

Custom dimensions/metrics are those you define yourself in GA4 Admin > Custom definitions.
They typically have apiNames like "customEvent:my_param" or "customUser:my_property".

Use this when you need to discover property-specific custom fields for reporting.

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/getMetadata

Search change history events for a Google Analytics 4 account. Returns a list of changes made to the account and its child resources (properties, data streams, etc.), including who made the change and when.

Parameters:
  - accountId (required): The account to search, e.g. "123456" or "accounts/123456".
  - propertyId (optional): Narrow results to a specific property, e.g. "properties/123456".
  - resourceType (optional): Filter by resource types. Values include:
      "ACCOUNT", "PROPERTY", "FIREBASE_LINK", "GOOGLE_ADS_LINK",
      "CONVERSION_EVENT", "CUSTOM_DIMENSION", "CUSTOM_METRIC",
      "DATA_RETENTION_SETTINGS", "DATA_STREAM", etc.
    Example: ["PROPERTY", "DATA_STREAM"]
  - action (optional): Filter by change actions. Values: "CREATED", "UPDATED", "DELETED".
    Example: ["CREATED", "UPDATED"]
  - earliestChangeTime (optional): ISO 8601 date string, e.g. "2024-01-01T00:00:00Z".
  - latestChangeTime (optional): ISO 8601 date string, e.g. "2024-12-31T23:59:59Z".
  - pageSize (optional): Maximum number of results to return.

Run up to 5 GA4 pivot reports in a single batch request.

Each request in the array follows the same schema as run_pivot_report
(dateRanges, dimensions, metrics, pivots, filters, etc.).

Useful for running multiple pivot analyses (e.g. different date ranges or dimension
combinations) with a single API call.

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/batchRunPivotReports

Run up to 5 GA4 reports in a single batch request. Each request object follows the same
schema as run_report (dateRanges, dimensions, metrics, filters, orderBys, etc.).

Batching is useful when you need several related reports for the same property and want
to minimise API round-trips and quota usage.

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/batchRunReports

Each request in the array should have:
  - dateRanges: [{startDate, endDate, name?}, ...]
  - dimensions: ["dim1", "dim2", ...]
  - metrics: ["metric1", "metric2", ...]
  - dimensionFilter (optional): FilterExpression object
  - metricFilter (optional): FilterExpression object
  - orderBys (optional): [{dimension:{dimensionName}, desc?}, ...]
  - limit (optional): max rows per sub-report
  - offset (optional): row offset
  - currencyCode (optional)
  - keepEmptyRows (optional)
  - returnPropertyQuota (optional)

See run_report tool description for detailed examples of filters and ordering.

Check whether specific dimensions and metrics can be used together in a GA4 report.

Not all dimension/metric combinations are compatible. This tool lets you validate
a proposed report configuration before running it.

Returns:
  - dimensionCompatibilities: for each dimension, whether it is compatible.
  - metricCompatibilities: for each metric, whether it is compatible.

Example use case: You want to report on "sessionSource" + "itemName" + "sessions" +
"itemRevenue" - call check_compatibility first to verify the combination is valid.

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/checkCompatibility

Retrieve all available dimensions and metrics for a GA4 property.

Returns the complete metadata catalogue including:
  - All standard dimensions and metrics available for the property.
  - Custom dimensions and metrics (marked with customDefinition: true).
  - API name, UI name, description, category, and data type for each.

This is the authoritative source for which dimensions/metrics are valid
when building reports for a specific property. Different properties may
have different available fields depending on configuration.

Use this before building a report to discover exact field names.

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/getMetadata

Run a funnel report to analyze user conversion paths through defined steps. This is an alpha API feature. Each funnel step defines a condition users must meet. The report shows how users progress through (or drop off from) each step.

The funnel configuration requires a 'steps' array where each step has:
  - 'name': A label for the step (e.g. "First visit", "Add to cart", "Purchase").
  - 'filterExpression': An object describing the condition (andGroup, orGroup, notExpression, funnelFieldFilter, or funnelEventFilter).

Optional funnel-level fields:
  - 'isOpenFunnel' (boolean, default false): When true, users can enter the funnel at any step rather than only the first.

You can also provide:
  - funnelBreakdown: Adds a dimension to break down each step (e.g. by deviceCategory).
  - funnelNextAction: Shows what users did after each step.

Response includes 'funnelTable' (tabular data) and 'funnelVisualization' (summary counts per step).

NOTE: This is an alpha API. If you receive a NOT_FOUND or UNIMPLEMENTED error, the alpha API may not be enabled for this property.

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

Run a GA4 pivot report. Pivot reports create cross-tabulations (like Excel pivot tables)
by rotating dimension values into column headers.

This is ideal for creating tables where:
  - Rows represent one dimension (e.g. country)
  - Columns represent another dimension (e.g. device category)
  - Cells contain metric values (e.g. sessions)

PIVOTS - each pivot defines a set of dimensions to rotate into columns:
  Example: {fieldNames: ["deviceCategory"], limit: 3}
  This creates columns for the top 3 device categories.

  Multiple pivots can be used to create multi-level column headers:
    pivots: [
      {fieldNames: ["browser"], limit: 5},
      {fieldNames: ["deviceCategory"], limit: 3}
    ]

DIMENSIONS & METRICS - same as run_report. All dimensions referenced by pivots
  must be included in the top-level dimensions array.
  Reference: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema

DATE RANGES - same as run_report.
  Example: [{startDate: "30daysAgo", endDate: "yesterday"}]

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runPivotReport

Run a GA4 realtime report. Returns data about activity on the property within the last 30 minutes
(or up to 60 minutes for some dimensions/metrics).

REALTIME DIMENSIONS - a subset of standard dimensions plus realtime-specific ones.
  Reference: https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#dimensions
  Common examples:
    "city", "country", "deviceCategory", "platform", "unifiedScreenName",
    "unifiedScreenClass", "audienceName", "minutesAgo",
    "streamName", "eventName", "conversions".

REALTIME METRICS - realtime-specific metrics.
  Reference: https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#metrics
  Common examples:
    "activeUsers", "screenPageViews", "eventCount", "conversions",
    "keyEvents".

NOTE: Realtime reports do NOT accept dateRanges - data always covers the
last 30 minutes of activity.

DIMENSION FILTER - same FilterExpression structure as regular reports:
  String filter: {"filter":{"fieldName":"country","stringFilter":{"matchType":"EXACT","value":"United States"}}}
  In-list:       {"filter":{"fieldName":"eventName","inListFilter":{"values":["page_view","scroll"]}}}

ORDER BYS:
  [{"metric":{"metricName":"activeUsers"},"desc":true}]

Full reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport

Run a standard GA4 report. Returns rows of dimension/metric values for the given property.

DIMENSIONS - name strings from the GA4 schema.
  Reference: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions
  Common examples: "date", "city", "country", "sessionSource", "sessionMedium",
  "sessionDefaultChannelGroup", "pagePath", "pageTitle", "eventName",
  "deviceCategory", "operatingSystem", "browser", "language",
  "firstUserSource", "firstUserMedium", "unifiedScreenName".

METRICS - name strings from the GA4 schema.
  Reference: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics
  Common examples: "sessions", "totalUsers", "newUsers", "activeUsers",
  "screenPageViews", "engagedSessions", "engagementRate",
  "averageSessionDuration", "eventCount", "conversions",
  "totalRevenue", "bounceRate", "sessionsPerUser".

DATE RANGES - each with startDate and endDate.
  Examples:
    {startDate: "2025-01-01", endDate: "2025-01-31"}
    {startDate: "30daysAgo",  endDate: "yesterday"}
    {startDate: "7daysAgo",   endDate: "today"}

DIMENSION FILTER - a FilterExpression JSON object. Examples:
  String filter:   {"filter":{"fieldName":"country","stringFilter":{"matchType":"EXACT","value":"United States"}}}
  In-list filter:  {"filter":{"fieldName":"eventName","inListFilter":{"values":["page_view","scroll"]}}}
  Numeric filter:  {"filter":{"fieldName":"sessions","numericFilter":{"operation":"GREATER_THAN","value":{"int64Value":"100"}}}}
  AND group:       {"andGroup":{"expressions":[...]}}
  OR group:        {"orGroup":{"expressions":[...]}}

ORDER BYS - array of ordering objects. Examples:
  By dimension (ascending):  [{"dimension":{"dimensionName":"date"}}]
  By metric (descending):    [{"metric":{"metricName":"sessions"},"desc":true}]

Full API reference: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport