ga4_run_report

Description

Run a GA4 report (Data API runReport): arbitrary dimensions × metrics over one or more date ranges, with filtering, ordering and acquisition cohorts. Use ga4_get_metadata first to look up valid dimension/metric API names. For ORDERED, step-by-step funnels use ga4_run_funnel_report instead — runReport cannot express sequence. Args: property_id (string, required): GA4 property ID (numeric) or full resource name. dimensions (string[], optional): Up to 9 dimension API names (e.g. sessionDefaultChannelGroup, date). metrics (string[], required): 1-10 metric API names (e.g. sessions, totalUsers, keyEvents, purchaseRevenue). date_ranges (array, required unless cohort_spec is used): 1-4 ranges of { start_date, end_date, name? }. Dates are YYYY-MM-DD or relative (30daysAgo, yesterday, today). dimension_filter (object, optional): A filter expression — exactly one of: { filter: { field_name, string_filter | in_list_filter | numeric_filter | between_filter } } { and_group: { expressions: [ <leaf>, ... ] } } // all must hold { or_group: { expressions: [ <leaf>, ... ] } } // any must hold { not_expression: <leaf> } where <leaf> is { filter: {...} } or { not_expression: { filter: {...} } }. string_filter: { value, match_type?: EXACT|BEGINS_WITH|ENDS_WITH|CONTAINS|FULL_REGEXP|PARTIAL_REGEXP, case_sensitive? } Groups do not nest — one level of and/or over leaves. metric_filter (object, optional): Same shape, applied to metric values after aggregation (use numeric_filter / between_filter). cohort_spec (object, optional): Acquisition cohorts. { cohorts: [{ name?, date_range: { start_date, end_date } }], cohorts_range: { granularity: DAILY|WEEKLY|MONTHLY, start_offset?, end_offset } } Cohort reports REQUIRE the "cohort" dimension and must OMIT date_ranges — the cohort's own date_range defines the window. Pair with cohortNthDay/cohortNthWeek/cohortNthMonth and a metric such as cohortActiveUsers. order_by (object, optional): { type: 'metric'|'dimension', name, desc? }. limit (number, optional): Max rows, default 100, max 10000. offset (number, optional): Row offset for pagination. Returns: data — the rows, flattened as { dimension: value, metric: value } objects. Plus row_count (total rows before pagination) and returned_rows. For a single date range: metric_totals ({ metric: total }). For multiple date ranges: metric_totals_by_range ({ "date_range_0": { metric: total }, ... }) keyed by the dateRange dimension value (or the range's name).

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ga4_run_report",
    "arguments": {
      "property_id": "123456789",
      "dimensions": [
        "sessionDefaultChannelGroup"
      ],
      "metrics": [
        "sessions",
        "totalUsers",
        "keyEvents"
      ],
      "date_ranges": [
        {
          "start_date": "30daysAgo",
          "end_date": "yesterday"
        }
      ],
      "reason": "Channel mix overview for the last 30 days"
    }
  }
}

hopkin ga4 report

{
  "mcpServers": {
    "ga4": {
      "url": "https://ga4.mcp.hopkin.ai",
      "transport": "sse"
    }
  }
}

Parameters

Examples

{
  "property_id": "123456789",
  "dimensions": [
    "sessionDefaultChannelGroup"
  ],
  "metrics": [
    "sessions",
    "totalUsers",
    "keyEvents"
  ],
  "date_ranges": [
    {
      "start_date": "30daysAgo",
      "end_date": "yesterday"
    }
  ],
  "reason": "Channel mix overview for the last 30 days"
}

{
  "property_id": "123456789",
  "dimensions": [
    "landingPagePlusQueryString"
  ],
  "metrics": [
    "sessions",
    "purchaseRevenue"
  ],
  "date_ranges": [
    {
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    }
  ],
  "dimension_filter": {
    "filter": {
      "field_name": "sessionDefaultChannelGroup",
      "string_filter": {
        "value": "Paid Search"
      }
    }
  },
  "order_by": {
    "type": "metric",
    "name": "purchaseRevenue"
  },
  "limit": 25,
  "reason": "Top paid-search landing pages by revenue"
}

{
  "property_id": "123456789",
  "dimensions": [
    "cohort",
    "cohortNthWeek"
  ],
  "metrics": [
    "cohortActiveUsers"
  ],
  "cohort_spec": {
    "cohorts": [
      {
        "name": "week_of_jul_6",
        "date_range": {
          "start_date": "2026-07-06",
          "end_date": "2026-07-12"
        }
      }
    ],
    "cohorts_range": {
      "granularity": "WEEKLY",
      "start_offset": 0,
      "end_offset": 3
    }
  },
  "reason": "Retention of the users acquired in the week of Jul 6"
}