run_funnel_report

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