run_realtime_report
Run real-time reports on Google Analytics data by specifying property, dimensions, and metrics, with support for filtering and ordering.
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
| Name | Required | Description | Default |
|---|---|---|---|
| property_id | Yes | ||
| dimensions | Yes | ||
| metrics | Yes | ||
| dimension_filter | No | ||
| metric_filter | No | ||
| order_bys | No | ||
| limit | No | ||
| offset | No | ||
| return_property_quota | No |
Implementation Reference
- Main handler function for the run_realtime_report tool. Builds a RunRealtimeReportRequest with dimensions, metrics, filters, order_bys, limit, offset, and returns the response as a dict.
async def run_realtime_report( property_id: int | str, dimensions: List[str], metrics: List[str], dimension_filter: Dict[str, Any] = None, metric_filter: Dict[str, Any] = None, order_bys: List[Dict[str, Any]] = None, limit: int = None, offset: int = None, return_property_quota: bool = False, ) -> Dict[str, Any]: """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. """ request = data_v1beta.RunRealtimeReportRequest( property=construct_property_rn(property_id), dimensions=[ data_v1beta.Dimension(name=dimension) for dimension in dimensions ], metrics=[data_v1beta.Metric(name=metric) for metric in metrics], return_property_quota=return_property_quota, ) if dimension_filter: request.dimension_filter = data_v1beta.FilterExpression( dimension_filter ) if metric_filter: request.metric_filter = data_v1beta.FilterExpression(metric_filter) if order_bys: request.order_bys = [ data_v1beta.OrderBy(order_by) for order_by in order_bys ] if limit: request.limit = limit if offset: request.offset = offset def _sync_call(): return create_data_api_client().run_realtime_report(request) response = await asyncio.to_thread(_sync_call) return proto_to_dict(response) - Description builder for the run_realtime_report tool. Generates dynamic help text with hints for dimensions, metrics, date_ranges, dimension_filter, metric_filter, and order_bys arguments.
def _run_realtime_report_description() -> str: """Returns the description for the `run_realtime_report` tool.""" return f""" {run_realtime_report.__doc__} ## 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`: {get_date_ranges_hints()} ### Hints for `dimension_filter`: {get_dimension_filter_hints()} ### Hints for `metric_filter`: {get_metric_filter_hints()} ### Hints for `order_bys`: {get_order_bys_hints()} """ - analytics_mcp/coordinator.py:56-75 (registration)Registration: Creates FunctionTool wrapping run_realtime_report, sets description via _run_realtime_report_description(), and adds it to the tools list.
run_realtime_report_with_description = FunctionTool(run_realtime_report) run_realtime_report_with_description.description = ( _run_realtime_report_description() ) run_funnel_report_with_description = FunctionTool(run_funnel_report) run_funnel_report_with_description.description = ( _run_funnel_report_description() ) # Instantiate the ADK tools tools = [ FunctionTool(get_account_summaries), FunctionTool(list_google_ads_links), FunctionTool(get_property_details), FunctionTool(list_property_annotations), FunctionTool(get_custom_dimensions_and_metrics), run_report_with_description, run_realtime_report_with_description, run_funnel_report_with_description, ] - analytics_mcp/coordinator.py:134-135 (registration)Required fields configuration: Marks property_id, dimensions, and metrics as required in the input schema for the run_realtime_report tool.
elif tool.name == "run_realtime_report": tool.inputSchema["required"] = ["property_id", "dimensions", "metrics"] - analytics_mcp/tools/client.py:73-78 (helper)Helper: create_data_api_client() returns a BetaAnalyticsDataClient used by run_realtime_report to make the API call.
def create_data_api_client() -> data_v1beta.BetaAnalyticsDataClient: """Returns the Google Analytics Data API client.""" with _client_lock: return data_v1beta.BetaAnalyticsDataClient( client_info=_CLIENT_INFO, credentials=_get_credentials() )