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
dateRangesfield.A valid funnel specification in the
funnelfield.
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:
funnelFieldFiltercreates a filter for a dimension or metric.funnelEventFiltercreates a filter that matches events of a single event name. If an optionalfunnelParameterFilterExpressionfield 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 (
funnelStepNamedimension).Active users count (
activeUsersmetric).Segment (
segmentdimension). Present only ifSegmentis specified in the funnel query.Date (
datedimension). Present only if theTRENDED_FUNNELvisualization type was specified in the query.Next action dimension (
funnelStepNextActiondimension). Present only if theFunnelNextActionis 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 (
funnelStepNamedimension).Breakdown dimension.
Active users count (
activeUsersmetric).Step completion rate (
funnelStepCompletionRatemetric).Step abandonments count (
funnelStepAbandonmentsmetric).Step abandonments rate (
funnelStepAbandonmentRatemetric).Segment name (
segmentdimension). Present only ifSegmentis 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)