Runs a Google Analytics Data API conversions report.

USE THIS TOOL INSTEAD OF `run_report` WHEN:
- You need to report specifically on conversions, ad performance, return on ad spend (ROAS), or attribution.
- You need to query specific conversion metrics (e.g., advertiserAdCost, returnOnAdSpendByInteractionDate, allConversionsByConversionDate, etc.).
- You need to apply a specific attribution model (e.g., DATA_DRIVEN or LAST_CLICK) to your data.
- The user's query explicitly asks about conversions, ad clicks, ad costs, or campaigns related to conversions.

See the conversions report guide at
https://developers.google.com/analytics/devguides/reporting/data/v1/conversions-api-basics
for details and examples.

Args:
    property_id: The Google Analytics property ID. Accepted formats are:
      - A number
      - A string consisting of 'properties/' followed by a number
    date_ranges: A list of date ranges
      (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/DateRange)
      to include in the report.
    dimensions: A list of dimensions to include in the report.
    metrics: A list of metrics to include in the report.
    conversion_spec: The specification for conversions reporting.
      Should include 'conversion_actions' (list of resource names) and
      'attribution_model'.
    dimension_filter: A Data API FilterExpression
      (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/FilterExpression)
      to apply to the dimensions.
    metric_filter: A Data API FilterExpression
      (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/FilterExpression)
      to apply to the metrics.
    order_bys: A list of Data API OrderBy
      (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/OrderBy)
      objects to apply to the dimensions and metrics.
    limit: The maximum number of rows to return in each response. Value must
      be a positive integer <= 250,000.
    offset: The row count of the start row. The first row is counted as row 0.
    currency_code: The currency code to use for currency values.
    return_property_quota: Whether to return 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 the following allowed standard dimensions:
      - campaignName
      - continent
      - country
      - defaultChannelGroup
      - deviceCategory
      - medium
      - platform
      - primaryChannelGroup
      - source
      - sourceMedium
      - sourcePlatform
      - subcontinent

      ### Hints for `metrics`

      The `metrics` list must consist solely of the following allowed standard metrics:
      - advertiserAdClicks
      - advertiserAdCost
      - advertiserAdCostPerAllConversionsByConversionDate
      - advertiserAdCostPerAllConversionsByInteractionDate
      - advertiserAdCostPerClick
      - advertiserAdImpressions
      - allConversionsByConversionDate
      - allConversionsByInteractionDate
      - returnOnAdSpendByConversionDate
      - returnOnAdSpendByInteractionDate
      - totalRevenueByConversionDate
      - totalRevenueByInteractionDate

      ### Hints for `conversion_spec`

      The `conversion_spec` argument is required for conversions reporting.
      You can pass an empty list for `conversion_actions` if you want all conversion events.
      Example:
      {
          "conversion_actions": ["conversionActions/12345"], # Or [] for all actions
          "attribution_model": "DATA_DRIVEN"  # Or "LAST_CLICK"
      }

      ### 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}}}]}}

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}}}}]}}

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.

    Run a Google Analytics Data API funnel report.

See the funnel report guide at
https://developers.google.com/analytics/devguides/reporting/data/v1/funnels
for details and examples.

Args:
    property_id: The Google Analytics property ID. Accepted formats are:
      - A number
      - A string consisting of 'properties/' followed by a number
    funnel_steps: A list of funnel steps. Each step should be a dictionary
      containing:
      - 'name': (str) Display name for the step
      - 'filter_expression': (Dict) Complete filter expression for the step
      OR for simple event-based steps:
      - 'name': (str) Display name for the step
      - 'event': (str) Event name to filter on
    date_ranges: A list of date ranges
      (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange)
      to include in the report.
    funnel_breakdown: Optional breakdown dimension to segment the funnel.
      This creates separate funnel results for each value of the dimension.
      Example: {"breakdown_dimension": "deviceCategory"}
    funnel_next_action: Optional next action analysis configuration.
      This analyzes what users do after completing or dropping off from
      the funnel.
      Example: {"next_action_dimension": "eventName", "limit": 5}
    segments: Optional list of segments to apply to the funnel.
    return_property_quota: Whether to return current property quota
      information.

Returns:
    Dict containing the funnel report response with funnel results
    including:
    - funnel_table: Table showing progression through funnel steps
    - funnel_visualization: Data for visualizing the funnel
    - property_quota: (if requested) Current quota usage information

Raises:
    ValueError: If funnel_steps is empty or contains invalid configurations
    Exception: If the API request fails


    ## Hints for arguments

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

    ### Hints for `funnel_breakdown`

    The `funnel_breakdown` parameter allows you to segment funnel results by a dimension:
    ```json
    {
        "breakdown_dimension": "deviceCategory"
    }
    ```
    Common breakdown dimensions include:
    - `deviceCategory` - Desktop, Mobile, Tablet
    - `country` - User's country
    - `operatingSystem` - User's operating system
    - `browser` - User's browser

    ### Hints for `funnel_next_action`

    The `funnel_next_action` parameter analyzes what users do after completing or dropping off from the funnel:
    ```json
    {
        "next_action_dimension": "eventName",
        "limit": 5
    }
    ```
    Common next action dimensions include:
    - `eventName` - Next events users trigger
    - `pagePath` - Next pages users visit

    ### Hints for `segments`

    The `segments` parameter allows you to segment funnel results by user criteria.
    Each segment is a dictionary passed directly to `data_v1alpha.Segment()`.
    See https://developers.google.com/analytics/devguides/reporting/data/v1/funnels#segments
    for details and examples.

    ### 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 `funnel_steps`
    Example funnel_steps configurations:

1. Simple event-based step (first open/visit):
    {"name": "First open/visit", "filter_expression": {"or_group": {"expressions": [{"funnel_event_filter": {"event_name": "first_open"}}, {"funnel_event_filter": {"event_name": "first_visit"}}]}}, "is_directly_followed_by": false}

2. Field filter for organic traffic:
    {"name": "Organic visitors", "filter_expression": {"funnel_field_filter": {"field_name": "firstUserMedium", "string_filter": {"match_type": 4, "value": "organic", "case_sensitive": false}}}, "is_directly_followed_by": false}

3. Simple event filter:
    {"name": "Session start", "filter_expression": {"funnel_event_filter": {"event_name": "session_start"}}, "is_directly_followed_by": false}

4. Multiple events with OR condition:
    {"name": "Screen/Page view", "filter_expression": {"or_group": {"expressions": [{"funnel_event_filter": {"event_name": "screen_view"}}, {"funnel_event_filter": {"event_name": "page_view"}}]}}, "is_directly_followed_by": false}

5. Purchase events (multiple event types):
    {"name": "Purchase", "filter_expression": {"or_group": {"expressions": [{"funnel_event_filter": {"event_name": "purchase"}}, {"funnel_event_filter": {"event_name": "in_app_purchase"}}]}}, "is_directly_followed_by": false}

6. Event with parameter filter (value > 50):
    {"name": "Add to cart (value > 50)", "filter_expression": {"funnel_event_filter": {"event_name": "add_to_cart", "funnel_parameter_filter_expression": {"funnel_parameter_filter": {"event_parameter_name": "value", "numeric_filter": {"operation": 4, "value": {"double_value": 50.0}}}}}}, "is_directly_followed_by": false}

7. Complex AND condition (page view + specific path):
    {"name": "Home page view", "filter_expression": {"and_group": {"expressions": [{"funnel_event_filter": {"event_name": "page_view"}}, {"funnel_field_filter": {"field_name": "pageLocation", "string_filter": {"match_type": 4, "value": "/", "case_sensitive": false}}}]}}, "is_directly_followed_by": false}


## Complete Funnel Example

A typical e-commerce funnel with 5 steps:
[
    {"name": "First open/visit", "filter_expression": {"or_group": {"expressions": [{"funnel_event_filter": {"event_name": "first_open"}}, {"funnel_event_filter": {"event_name": "first_visit"}}]}}, "is_directly_followed_by": false},
    {"name": "Organic visitors", "filter_expression": {"funnel_field_filter": {"field_name": "firstUserMedium", "string_filter": {"match_type": 4, "value": "organic", "case_sensitive": false}}}, "is_directly_followed_by": false},
    {"name": "Session start", "filter_expression": {"funnel_event_filter": {"event_name": "session_start"}}, "is_directly_followed_by": false},
    {"name": "Screen/Page view", "filter_expression": {"or_group": {"expressions": [{"funnel_event_filter": {"event_name": "screen_view"}}, {"funnel_event_filter": {"event_name": "page_view"}}]}}, "is_directly_followed_by": false},
    {"name": "Purchase", "filter_expression": {"or_group": {"expressions": [{"funnel_event_filter": {"event_name": "purchase"}}, {"funnel_event_filter": {"event_name": "in_app_purchase"}}]}}, "is_directly_followed_by": false}
]

      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}}}]}}

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}}}}]}}

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.

      Runs a Google Analytics Data API report.

Note that the reference docs at
https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta
all use camelCase field names, but field names passed to this method should
be in snake_case since the tool is using the protocol buffers (protobuf)
format. The protocol buffers for the Data API are available at
https://github.com/googleapis/googleapis/tree/master/google/analytics/data/v1beta.

Args:
    property_id: The Google Analytics property ID. Accepted formats are:
      - A number
      - A string consisting of 'properties/' followed by a number
    date_ranges: A list of date ranges
      (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange)
      to include in the report.
    dimensions: A list of dimensions to include in the report.
    metrics: A list of metrics to include in the report.
    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.
    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.
    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.
    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.
    currency_code: The currency code to use for currency values. Must be in
      ISO4217 format, such as "AED", "USD", "JPY". If the field is empty, the
      report uses the property's default currency.
    return_property_quota: Whether to return 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.  Standard dimensions defined in the HTML table at
          https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions.
          These dimensions are available to *every* property.
      2.  Custom dimensions for the `property_id`. Use the
          `get_custom_dimensions_and_metrics` tool to retrieve the list of
          custom dimensions for a property.

      ### Hints for `metrics`

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

      1.  Standard metrics defined in the HTML table at
          https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics.
          These metrics are available to *every* property.
      2.  Custom metrics for the `property_id`. Use the
          `get_custom_dimensions_and_metrics` tool to retrieve the list of
          custom metrics for a property.


      ### 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}}}]}}

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}}}}]}}

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.