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 optionalfunnelParameterFilterExpression
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:
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 first_open
or first_visit
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": "first_open"
}
},
{
"funnelEventFilter": {
"eventName": "first_visit"
}
}
]
}
}
}
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 ifSegment
is specified in the funnel query.Date (
date
dimension). Present only if theTRENDED_FUNNEL
visualization type was specified in the query.Next action dimension (
funnelStepNextAction
dimension). Present only if theFunnelNextAction
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 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 ifSegment
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:
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, Dimension, Funnel, FunnelBreakdown, FunnelEventFilter, FunnelFieldFilter, FunnelFilterExpression, FunnelFilterExpressionList, FunnelStep, RunFunnelReportRequest, 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)