Skip to main content
Glama
AnalyticsRHD

ga4-mcp

by AnalyticsRHD
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Run Realtime Report

run_realtime_report

Fetch real-time Google Analytics 4 data to monitor current user activity and events. Provide property ID, dimensions, and metrics to get up-to-date reports for immediate analysis.

Instructions

      Runs a Google Analytics Data API realtime report.

See https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-basics for more information.

Args: property_id: The Google Analytics property ID. Accepted formats are: - A number - A string consisting of 'properties/' followed by a number dimensions: A list of dimensions to include in the report. Dimensions must be realtime dimensions. metrics: A list of metrics to include in the report. Metrics must be realtime metrics. dimension_filter: A Data API FilterExpression (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/FilterExpression) to apply to the dimensions. Don't use this for filtering metrics. Use metric_filter instead. The field_name in a dimension_filter must be a dimension, as defined in the get_standard_dimensions and get_dimensions tools. For more information about the expected format of this argument, see the run_report_dimension_filter_hints tool. metric_filter: A Data API FilterExpression (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/FilterExpression) to apply to the metrics. Don't use this for filtering dimensions. Use dimension_filter instead. The field_name in a metric_filter must be a metric, as defined in the get_standard_metrics and get_metrics tools. For more information about the expected format of this argument, see the run_report_metric_filter_hints tool. order_bys: A list of Data API OrderBy (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/OrderBy) objects to apply to the dimensions and metrics. For more information about the expected format of this argument, see the run_report_order_bys_hints tool. limit: The maximum number of rows to return in each response. Value must be a positive integer <= 250,000. Used to paginate through large reports, following the guide at https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination. offset: The row count of the start row. The first row is counted as row 0. Used to paginate through large reports, following the guide at https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination. return_property_quota: Whether to return realtime property quota in the response.

      ## Hints for arguments

      Here are some hints that outline the expected format and requirements
      for arguments.

      ### Hints for `dimensions`

      The `dimensions` list must consist solely of either of the following:

      1.  Realtime standard dimensions defined in the HTML table at
          https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#dimensions.
          These dimensions are available to *every* property.
      2.  User-scoped custom dimensions for the `property_id`. Use the
          `get_custom_dimensions_and_metrics` tool to retrieve the list of
          custom dimensions for a property, and look for the custom
          dimensions with an `apiName` that begins with "customUser:".

      ### Hints for `metrics`

      The `metrics` list must consist solely of the Realtime standard
      metrics defined in the HTML table at
      https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#metrics.
      These metrics are available to *every* property.

      Realtime reports can't use custom metrics.

      ### Hints for `date_ranges`:
      Example date_range arguments:
  1. A single date range:

    [ {"start_date": "2025-01-01", "end_date": "2025-01-31", "name": "Jan2025"} ]

  2. A relative date range using 'yesterday' and 'today':
    [ {"start_date": "yesterday", "end_date": "today", "name": "YesterdayAndToday"} ]

  3. A relative date range using 'NdaysAgo' and 'today':
    [ {"start_date": "30daysAgo", "end_date": "yesterday", "name": "Previous30Days"}]

  4. Multiple date ranges:
    [ {"start_date": "2025-01-01", "end_date": "2025-01-31", "name": "Jan2025"}, {"start_date": "2025-02-01", "end_date": "2025-02-28", "name": "Feb2025"} ]


      ### Hints for `dimension_filter`:
      Example dimension_filter arguments:
  1. A simple filter:
    {"filter": {"field_name": "eventName", "string_filter": {"match_type": 2, "value": "add", "case_sensitive": false}}}

  2. A NOT filter:
    {"not_expression": {"filter": {"field_name": "eventName", "string_filter": {"match_type": 2, "value": "add", "case_sensitive": false}}}}

  3. An empty value filter:
    {"filter": {"field_name": "source", "empty_filter": {}}}

  4. An AND group filter:
    {"and_group": {"expressions": [{"filter": {"field_name": "sourceMedium", "string_filter": {"match_type": 1, "value": "google / cpc", "case_sensitive": false}}}, {"filter": {"field_name": "eventName", "in_list_filter": {"values": ["first_visit", "purchase", "add_to_cart"], "case_sensitive": true}}}]}}

  5. An OR group filter:
    {"or_group": {"expressions": [{"filter": {"field_name": "sourceMedium", "string_filter": {"match_type": 1, "value": "google / cpc", "case_sensitive": false}}}, {"filter": {"field_name": "eventName", "in_list_filter": {"values": ["first_visit", "purchase", "add_to_cart"], "case_sensitive": true}}}]}}

Notes: The API applies the dimension_filter and metric_filter independently. As a result, some complex combinations of dimension and metric filters are not possible in a single report request.

For example, you can't create a `dimension_filter` and `metric_filter`
combination for the following condition:

(
  (eventName = "page_view" AND eventCount > 100)
  OR
  (eventName = "join_group" AND eventCount < 50)
)

This isn't possible because there's no way to apply the condition
"eventCount > 100" only to the data with eventName of "page_view", and
the condition "eventCount < 50" only to the data with eventName of
"join_group".

More generally, you can't define a `dimension_filter` and `metric_filter`
for:

(
  ((dimension condition D1) AND (metric condition M1))
  OR
  ((dimension condition D2) AND (metric condition M2))
)

If you have complex conditions like this, either:

a)  Run a single report that applies a subset of the conditions that
    the API supports as well as the data needed to perform filtering of the
    API response on the client side. For example, for the condition:
    (
      (eventName = "page_view" AND eventCount > 100)
      OR
      (eventName = "join_group" AND eventCount < 50)
    )
    You could run a report that filters only on:
    eventName one of "page_view" or "join_group"
    and include the eventCount metric, then filter the API response on the
    client side to apply the different metric filters for the different
    events.

or

b)  Run a separate report for each combination of dimension condition and
    metric condition. For the example above, you'd run one report for the
    combination of (D1 AND M1), and another report for the combination of
    (D2 AND M2).

Try to run fewer reports (option a) if possible. However, if running
fewer reports results in excessive quota usage for the API, use option
b. More information on quota usage is at
https://developers.google.com/analytics/blog/2023/data-api-quota-management.


      ### Hints for `metric_filter`:
      Example metric_filter arguments:
  1. A simple filter:
    {"filter": {"field_name": "eventCount", "numeric_filter": {"operation": 4, "value": {"int64_value": "10"}}}}

  2. A NOT filter:
    {"not_expression": {"filter": {"field_name": "eventCount", "numeric_filter": {"operation": 4, "value": {"int64_value": "10"}}}}}

  3. An empty value filter:
    {"filter": {"field_name": "purchaseRevenue", "empty_filter": {}}}

  4. An AND group filter:
    {"and_group": {"expressions": [{"filter": {"field_name": "eventCount", "numeric_filter": {"operation": 4, "value": {"int64_value": "10"}}}}, {"filter": {"field_name": "purchaseRevenue", "between_filter": {"from_value": {"double_value": 10.0}, "to_value": {"double_value": 25.0}}}}]}}

  5. An OR group filter:
    {"or_group": {"expressions": [{"filter": {"field_name": "eventCount", "numeric_filter": {"operation": 4, "value": {"int64_value": "10"}}}}, {"filter": {"field_name": "purchaseRevenue", "between_filter": {"from_value": {"double_value": 10.0}, "to_value": {"double_value": 25.0}}}}]}}

Notes: The API applies the dimension_filter and metric_filter independently. As a result, some complex combinations of dimension and metric filters are not possible in a single report request.

For example, you can't create a `dimension_filter` and `metric_filter`
combination for the following condition:

(
  (eventName = "page_view" AND eventCount > 100)
  OR
  (eventName = "join_group" AND eventCount < 50)
)

This isn't possible because there's no way to apply the condition
"eventCount > 100" only to the data with eventName of "page_view", and
the condition "eventCount < 50" only to the data with eventName of
"join_group".

More generally, you can't define a `dimension_filter` and `metric_filter`
for:

(
  ((dimension condition D1) AND (metric condition M1))
  OR
  ((dimension condition D2) AND (metric condition M2))
)

If you have complex conditions like this, either:

a)  Run a single report that applies a subset of the conditions that
    the API supports as well as the data needed to perform filtering of the
    API response on the client side. For example, for the condition:
    (
      (eventName = "page_view" AND eventCount > 100)
      OR
      (eventName = "join_group" AND eventCount < 50)
    )
    You could run a report that filters only on:
    eventName one of "page_view" or "join_group"
    and include the eventCount metric, then filter the API response on the
    client side to apply the different metric filters for the different
    events.

or

b)  Run a separate report for each combination of dimension condition and
    metric condition. For the example above, you'd run one report for the
    combination of (D1 AND M1), and another report for the combination of
    (D2 AND M2).

Try to run fewer reports (option a) if possible. However, if running
fewer reports results in excessive quota usage for the API, use option
b. More information on quota usage is at
https://developers.google.com/analytics/blog/2023/data-api-quota-management.


      ### Hints for `order_bys`:
      Example order_bys arguments:

1.  Order by ascending 'eventName':
    [ {"dimension": {"dimension_name": "eventName", "order_type": 1}, "desc": false} ]

2.  Order by descending 'eventName', ignoring case:
    [ {"dimension": {"dimension_name": "campaignName", "order_type": 2}, "desc": true} ]

3.  Order by ascending 'audienceId':
    [ {"dimension": {"dimension_name": "audienceId", "order_type": 3}, "desc": false} ]

4.  Order by descending 'eventCount':
    [ {"metric": {"metric_name": "eventValue"}, "desc": true} ]

5.  Order by ascending 'eventCount':
    [ {"metric": {"metric_name": "eventCount"}, "desc": false} ]

6.  Combination of dimension and metric order bys:
    [
      {"dimension": {"dimension_name": "eventName", "order_type": 1}, "desc": false},
      {"metric": {"metric_name": "eventValue"}, "desc": true},
    ]

7.  Order by multiple dimensions and metrics:
    [
      {"dimension": {"dimension_name": "eventName", "order_type": 1}, "desc": false},
      {"dimension": {"dimension_name": "audienceId", "order_type": 3}, "desc": false},
      {"metric": {"metric_name": "eventValue"}, "desc": true},
    ]

The dimensions and metrics in order_bys must also be present in the report
request's "dimensions" and "metrics" arguments, respectively.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoThe maximum number of rows to return in each response. Value must be a positive integer <= 250,000. Used to paginate through large reports, following the guide at https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination.
offsetNoThe row count of the start row. The first row is counted as row 0. Used to paginate through large reports, following the guide at https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination.
metricsYesA list of metrics to include in the report. Metrics must be realtime metrics.
order_bysNoA list of Data API OrderBy (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/OrderBy) objects to apply to the dimensions and metrics. For more information about the expected format of this argument, see the `run_report_order_bys_hints` tool.
dimensionsYesA list of dimensions to include in the report. Dimensions must be realtime dimensions.
property_idYesThe Google Analytics property ID. Accepted formats are: - A number - A string consisting of 'properties/' followed by a number
metric_filterNoA Data API FilterExpression (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/FilterExpression) to apply to the metrics. Don't use this for filtering dimensions. Use dimension_filter instead. The `field_name` in a `metric_filter` must be a metric, as defined in the `get_standard_metrics` and `get_metrics` tools. For more information about the expected format of this argument, see the `run_report_metric_filter_hints` tool.
dimension_filterNoA Data API FilterExpression (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/FilterExpression) to apply to the dimensions. Don't use this for filtering metrics. Use metric_filter instead. The `field_name` in a `dimension_filter` must be a dimension, as defined in the `get_standard_dimensions` and `get_dimensions` tools. For more information about the expected format of this argument, see the `run_report_dimension_filter_hints` tool.
return_property_quotaNoWhether to return realtime property quota in the response.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It discloses a key limitation: dimension_filter and metric_filter are applied independently, with detailed examples of what cannot be expressed and workarounds. It also mentions quota management and pagination via limit/offset. However, it omits operational details like realtime data latency (~30 min window) and that the operation is read-only, though these are somewhat implied by the nature of a report. The thorough filter-limitation disclosure elevates this above average.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very long and contains redundant sections: the identical 'Notes' about filter independence appears twice (once under dimension_filter, once under metric_filter). More problematically, it includes a 'Hints for date_ranges' section even though date_ranges is not a parameter in the schema, which could mislead the agent. The structure is front-loaded with a clear purpose but suffers from repetition and an irrelevant block, reducing efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 9 parameters, nested objects, and complex filter logic, the description is highly complete. It covers all parameters with examples, cross-references supporting tools, and provides strategic advice for handling filter limitations. The presence of an output schema means return values don't need explanation. The main gap is the phantom date_ranges hints and a slight lack of explicit realtime data-window constraints, but overall it is thorough enough for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema already documents every parameter (100% coverage), the description goes far beyond by providing concrete JSON examples for dimension_filter, metric_filter, and order_bys, and by linking each complex parameter to dedicated hint tools. It clarifies accepted formats for property_id and enforces that dimensions must be realtime dimensions, metrics must be realtime metrics. This is exemplary parameter guidance that adds substantial meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Runs a Google Analytics Data API realtime report.' — a specific verb and resource that immediately distinguishes it from the sibling run_report (standard reporting). The term 'realtime' in the first sentence and in the tool name makes the scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While it doesn't explicitly compare to run_report, the description clearly frames when realtime data is appropriate and guides the agent to supporting tools (get_standard_dimensions, get_custom_dimensions_and_metrics, and the hint tools). It also provides decision guidance for complex filter combinations, offering two strategies and recommending one based on quota. This is more than implied usage, though it stops short of an explicit 'use this instead of X' statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools