Overview

The Google Analytics Data API v1 allows you to generate funnel reports. Funnel exploration lets you visualize the steps your users take to complete a task and quickly see how well they are succeeding or failing at each step.

Shared Features with Core Reports

Funnel reporting requests have the same semantics with Core report requests for many shared features. For example pagination, Dimension Filters and User Properties behave the same in Funnel Reports as Core Reports. This guide focuses on funnel reporting features. To familiarize yourself with the Core Reporting functionality of the Data API v1, read the reporting basics guide, as well as advanced use cases guide.

Funnel reporting method

The Data API v1 supports funnel reporting functionality in the runFunnelReport method. This method returns a customized funnel report of your Google Analytics event data.

Selecting a Reporting Entity

All methods of the Data API v1 require the Google Analytics 4 property identifier to be specified inside a URL request path in the form of properties/GA4_PROPERTY_ID, such as:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID:runFunnelReport

The resulting report will be generated based on the Google Analytics event data collected in the specified Google Analytics 4 property.

If you are using one of the Data API client libraries, there is no need to manipulate the request URL path manually. Most API clients provide a property parameter that expects a string in the form of properties/GA4_PROPERTY_ID. See Quick start guide for examples of using the client libraries.

Funnel Report Request

To request a funnel report, you can construct a RunFunnelReportRequest object. We recommend starting with these request parameters:

  • A valid entry in the dateRanges field.

  • A valid funnel specification in the funnel field.

Funnel Specification

A funnel specification in the funnel field of a RunFunnelReportRequest object defines the user journey you want to measure by describing steps of this funnel.

Funnel steps contain one or more conditions that your users must meet to be included in that step of the funnel journey. Conditions for inclusion into each step can be described in the filterExpression field of each step.

Each funnel filter expression is a combination of two types of filters:

  • funnelFieldFilter creates a filter for a dimension or metric.

  • funnelEventFilter creates a filter that matches events of a single event name. If an optional funnelParameterFilterExpression field is specified, only the subset of events that match both the single event name and the parameter filter expressions match this event filter.

Filters can be combined using AND, OR groups, as well as negated using a NOT expression.

Report results for each funnel step will be broken down based on the dimension and specified in the funnelBreakdown field.

Funnel Report Example

Let's use the Google Analytics Data API v1 to reproduce the default funnel report provided in the Funnel exploration template of the Google Analytics UI:

Sample funnel report UI

Funnel Steps

The funnel configuration shown above contains the following steps:

# Step name Condition
1 First open/visit Event name is first_open or first_visit.
2 Organic visitors firstUserMedium dimension contains the term "organic".
3 Session start Event name is session_start.
4 Screen/Page view Event name is screen_view or page_view.
5 Purchase Event name is purchase or in_app_purchase.

Step 1 (First open/visit) of the funnel includes all users after their first interaction with a website or application, i.e. users who triggered purchase or in_app_purchase events.

To implement this behavior, the snippet below specifies a FunnelStep object with a filterExpression field. The filter expression field is a FunnelFilterExpression object constructed by combining two FunnelEventFilter entities using an OR group.

  {
    "name": "Purchase",
    "filterExpression": {
      "orGroup": {
        "expressions": [
          {
            "funnelEventFilter": {
              "eventName": "purchase"
            }
          },
          {
            "funnelEventFilter": {
              "eventName": "in_app_purchase"
            }
          }
        ]
      }
    }
  }

Step 2 (Organic visitors) of the funnel includes users whose first medium includes the term "organic". In the snippet below, the fieldName field of FunnelFieldFilter instructs the filter to match the firstUserMedium dimension. The stringFilter field contains a condition to include only the values of the dimension that contain the term "organic".

  {
    "name": "Organic visitors",
    "filterExpression": {
      "funnelFieldFilter": {
        "fieldName": "firstUserMedium",
        "stringFilter": {
          "matchType": "CONTAINS",
          "caseSensitive": false,
          "value": "organic"
        }
      }
    }
  }

The remaining funnel steps can be specified in a similar fashion.

Breakdown Dimension

An optional breakdown dimension (deviceCategory in this example) can be specified using a FunnelBreakdown object:

  "funnelBreakdown": {
    "breakdownDimension": {
      "name": "deviceCategory"
    }
  }

By default, only the first 5 distinct values of the breakdown dimension are included in the report. You can use the limit field of the FunnelBreakdown object to override this behavior.

Complete Funnel Report Query

Here is a complete query that generates a funnel report using all the steps described above:

HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID:runFunnelReport
{
  "dateRanges": [
    {
      "startDate": "30daysAgo",
      "endDate": "today"
    }
  ],
  "funnelBreakdown": {
    "breakdownDimension": {
      "name": "deviceCategory"
    }
  },
  "funnel": {
    "steps": [
      {
        "name": "First open/visit",
        "filterExpression": {
          "orGroup": {
            "expressions": [
              {
                "funnelEventFilter": {
                  "eventName": "first_open"
                }
              },
              {
                "funnelEventFilter": {
                  "eventName": "first_visit"
                }
              }
            ]
          }
        }
      },
      {
        "name": "Organic visitors",
        "filterExpression": {
          "funnelFieldFilter": {
            "fieldName": "firstUserMedium",
            "stringFilter": {
              "matchType": "CONTAINS",
              "caseSensitive": false,
              "value": "organic"
            }
          }
        }
      },
      {
        "name": "Session start",
        "filterExpression": {
          "funnelEventFilter": {
            "eventName": "session_start"
          }
        }
      },
      {
        "name": "Screen/Page view",
        "filterExpression": {
          "orGroup": {
            "expressions": [
              {
                "funnelEventFilter": {
                  "eventName": "screen_view"
                }
              },
              {
                "funnelEventFilter": {
                  "eventName": "page_view"
                }
              }
            ]
          }
        }
      },
      {
        "name": "Purchase",
        "filterExpression": {
          "orGroup": {
            "expressions": [
              {
                "funnelEventFilter": {
                  "eventName": "purchase"
                }
              },
              {
                "funnelEventFilter": {
                  "eventName": "in_app_purchase"
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Report Response

The Funnel Report Response of a funnel report API request consists of the two main parts, both returned as a FunnelSubReport object: Funnel Visualization and Funnel Table.

Funnel Visualization

Funnel Visualization, returned in the funnelVisualization field of the Funnel Report Response, contains a high level overview of the funnel report. This is useful, as the name implies, for a quick visualization of the generated funnel report.

Each row of the Funnel visualization table contains some or all of the following fields:

  • Funnel step name (funnelStepName dimension).

  • Active users count (activeUsers metric).

  • Segment (segment dimension). Present only if Segment is specified in the funnel query.

  • Date (date dimension). Present only if the TRENDED_FUNNEL visualization type was specified in the query.

  • Next action dimension (funnelStepNextAction dimension). Present only if the FunnelNextAction is specified in the funnel query.

This is how the Google Analytics UI would display the Funnel visualization section of the example report discussed above:

Funnel report headers: sample

Funnel Table

Funnel Table, returned in the funnelTable field of the Funnel Report Response, represents the main part of the report. Each row of the table contains some or all of the following fields:

  • Funnel step name (funnelStepName dimension).

  • Breakdown dimension.

  • Active users count (activeUsers metric).

  • Step completion rate (funnelStepCompletionRate metric).

  • Step abandonments count (funnelStepAbandonments metric).

  • Step abandonments rate (funnelStepAbandonmentRate metric).

  • Segment name (segment dimension). Present only if Segment is specified in the funnel query.

Similar to the Core Reporting functionality, total values are returned in a separate row having RESERVED_TOTAL as a breakdown dimension value.

Below is an example of the Funnel Table displayed in the Google Analytics UI: Funnel report table: sample

Raw response

The snippet below demonstrates an example of raw data returned in response to the runFunnelReport query.

Depending on the data collected by your property, the example report above would return the following report showing the number of active users included into each funnel step.

{
  "funnelTable": {
    "dimensionHeaders": [
      {
        "name": "funnelStepName"
      },
      {
        "name": "deviceCategory"
      }
    ],
    "metricHeaders": [
      {
        "name": "activeUsers",
        "type": "TYPE_INTEGER"
      },
      {
        "name": "funnelStepCompletionRate",
        "type": "TYPE_INTEGER"
      },
      {
        "name": "funnelStepAbandonments",
        "type": "TYPE_INTEGER"
      },
      {
        "name": "funnelStepAbandonmentRate",
        "type": "TYPE_INTEGER"
      }
    ],
    "rows": [
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          },
          {
            "value": "RESERVED_TOTAL"
          }
        ],
        "metricValues": [
          {
            "value": "4621565"
          },
          {
            "value": "0.27780178359495106"
          },
          {
            "value": "3337686"
          },
          {
            "value": "0.72219821640504889"
          }
        ]
      },
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          },
          {
            "value": "desktop"
          }
        ],
        "metricValues": [
          {
            "value": "4015959"
          },
          {
            "value": "0.27425279989163237"
          },
          {
            "value": "2914571"
          },
          {
            "value": "0.72574720010836768"
          }
        ]
      },
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          },
          {
            "value": "mobile"
          }
        ],
        "metricValues": [
          {
            "value": "595760"
          },
          {
            "value": "0.29156035987646034"
          },
          {
            "value": "422060"
          },
          {
            "value": "0.70843964012353966"
          }
        ]
      },
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          },
          {
            "value": "tablet"
          }
        ],
        "metricValues": [
          {
            "value": "33638"
          },
          {
            "value": "0.205571080325822"
          },
          {
            "value": "26723"
          },
          {
            "value": "0.79442891967417806"
          }
        ]
      },

...

    ],
    "metadata": {
      "samplingMetadatas": [
        {
          "samplesReadCount": "9917254",
          "samplingSpaceSize": "1162365416"
        }
      ]
    }
  },

  "funnelVisualization": {
    "dimensionHeaders": [
      {
        "name": "funnelStepName"
      }
    ],
    "metricHeaders": [
      {
        "name": "activeUsers",
        "type": "TYPE_INTEGER"
      }
    ],
    "rows": [
      {
        "dimensionValues": [
          {
            "value": "1. First open/visit"
          }
        ],
        "metricValues": [
          {
            "value": "4621565"
          }
        ]
      },

...

    ],
    "metadata": {
      "samplingMetadatas": [
        {
          "samplesReadCount": "9917254",
          "samplingSpaceSize": "1162365416"
        }
      ]
    }
  },
  "kind": "analyticsData#runFunnelReport"
}

Client libraries

See the Quick start guide for an explanation on how to install and configure client libraries.

Below is an example using the Python client library that runs a funnel query and prints the response.

from google.analytics.data_v1alpha import AlphaAnalyticsDataClient
from google.analytics.data_v1alpha.types import DateRange
from google.analytics.data_v1alpha.types import Dimension
from google.analytics.data_v1alpha.types import Funnel
from google.analytics.data_v1alpha.types import FunnelBreakdown
from google.analytics.data_v1alpha.types import FunnelEventFilter
from google.analytics.data_v1alpha.types import FunnelFieldFilter
from google.analytics.data_v1alpha.types import FunnelFilterExpression
from google.analytics.data_v1alpha.types import FunnelFilterExpressionList
from google.analytics.data_v1alpha.types import FunnelStep
from google.analytics.data_v1alpha.types import RunFunnelReportRequest
from google.analytics.data_v1alpha.types import StringFilter


def run_sample():
    """Runs the sample."""
    # TODO(developer): Replace this variable with your Google Analytics 4
    #  property ID before running the sample.
    property_id = "YOUR-GA4-PROPERTY-ID"
    run_funnel_report(property_id)


def run_funnel_report(property_id="YOUR-GA4-PROPERTY-ID"):
    """Runs a funnel query to build a report with 5 funnel steps.
      Step 1: First open/visit (event name is `first_open` or `first_visit`).
      Step 2: Organic visitors (`firstUserMedium` dimension contains the term
      "organic").
      Step 3: Session start (event name is `session_start`).
      Step 4: Screen/Page view (event name is `screen_view` or `page_view`).
      Step 5: Purchase (event name is `purchase` or `in_app_purchase`).

    The report configuration reproduces the default funnel report provided in
    the Funnel Exploration template of the Google Analytics UI.
    See more at https://support.google.com/analytics/answer/9327974
    """
    client = AlphaAnalyticsDataClient()

    request = RunFunnelReportRequest(
        property=f"properties/{property_id}",
        date_ranges=[DateRange(start_date="30daysAgo", end_date="today")],
        funnel_breakdown=FunnelBreakdown(
            breakdown_dimension=Dimension(name="deviceCategory")
        ),
        funnel=Funnel(
            steps=[
                FunnelStep(
                    name="First open/visit",
                    filter_expression=FunnelFilterExpression(
                        or_group=FunnelFilterExpressionList(
                            expressions=[
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="first_open"
                                    )
                                ),
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="first_visit"
                                    )
                                ),
                            ]
                        )
                    ),
                ),
                FunnelStep(
                    name="Organic visitors",
                    filter_expression=FunnelFilterExpression(
                        funnel_field_filter=FunnelFieldFilter(
                            field_name="firstUserMedium",
                            string_filter=StringFilter(
                                match_type=StringFilter.MatchType.CONTAINS,
                                case_sensitive=False,
                                value="organic",
                            ),
                        )
                    ),
                ),
                FunnelStep(
                    name="Session start",
                    filter_expression=FunnelFilterExpression(
                        funnel_event_filter=FunnelEventFilter(
                            event_name="session_start"
                        )
                    ),
                ),
                FunnelStep(
                    name="Screen/Page view",
                    filter_expression=FunnelFilterExpression(
                        or_group=FunnelFilterExpressionList(
                            expressions=[
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="screen_view"
                                    )
                                ),
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="page_view"
                                    )
                                ),
                            ]
                        )
                    ),
                ),
                FunnelStep(
                    name="Purchase",
                    filter_expression=FunnelFilterExpression(
                        or_group=FunnelFilterExpressionList(
                            expressions=[
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="purchase"
                                    )
                                ),
                                FunnelFilterExpression(
                                    funnel_event_filter=FunnelEventFilter(
                                        event_name="in_app_purchase"
                                    )
                                ),
                            ]
                        )
                    ),
                ),
            ]
        ),
    )
    response = client.run_funnel_report(request)
    print_run_funnel_report_response(response)


def print_funnel_sub_report(funnel_sub_report):
    """Prints the contents of a FunnelSubReport object."""
    print("Dimension headers:")
    for dimension_header in funnel_sub_report.dimension_headers:
        print(dimension_header.name)

    print("\nMetric headers:")
    for metric_header in funnel_sub_report.metric_headers:
        print(metric_header.name)

    print("\nDimensions and metric values for each row in the report:")
    for row_idx, row in enumerate(funnel_sub_report.rows):
        print("\nRow #{}".format(row_idx))
        for field_idx, dimension_value in enumerate(row.dimension_values):
            dimension_name = funnel_sub_report.dimension_headers[field_idx].name
            print("{}: '{}'".format(dimension_name, dimension_value.value))

        for field_idx, metric_value in enumerate(row.metric_values):
            metric_name = funnel_sub_report.metric_headers[field_idx].name
            print("{}: '{}'".format(metric_name, metric_value.value))

    print("\nSampling metadata for each date range:")
    for metadata_idx, metadata in enumerate(
        funnel_sub_report.metadata.sampling_metadatas
    ):
        print(
            "Sampling metadata for date range #{}: samplesReadCount={}, "
            "samplingSpaceSize={}".format(
                metadata_idx, metadata.samples_read_count, metadata.sampling_space_size
            )
        )


def print_run_funnel_report_response(response):
    """Prints results of a runFunnelReport call."""
    print("Report result:")
    print("=== FUNNEL VISUALIZATION ===")
    print_funnel_sub_report(response.funnel_visualization)

    print("=== FUNNEL TABLE ===")
    print_funnel_sub_report(response.funnel_table)