This is an overview of the capabilities Realtime Reporting API Method of the Analytics Data API v1. For a detailed reference of the API, see the API Reference.
Realtime Reports
Realtime Reports are tables of event data from the last 30 minutes for a GA4 Property. Tables have rows and columns. The columns in each report are the Dimensions and Metrics from the Report's API request. Rows are selected by Filters and Pagination.
The following is an example realtime report table.
Country | Active Users |
---|---|
Japan | 2541 |
France | 12 |
Report Request
To request realtime reports, you can construct a RunRealtimeReportRequest object. We recommend starting with these request parameters:
- A valid property ID for the property path parameter.
- At least one valid entry in the dimensions field.
- At least one valid entry in the metrics field.
Here is a sample request with the recommended fields. In these examples, replace
YOUR_PROPERTY_ID
with your Property ID.
POST https://analyticsdata.googleapis.com/v1alpha/properties/YOUR_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
Report Response
The Realtime Report Response of the API request is primarily a header and rows. The header consists of DimensionHeaders and MetricHeaders which list the columns in the Report. Each row consists of DimensionValues and MetricValues for the columns in the report. The ordering of columns is consistent in the request, the header, and every row.
Here is a sample response for the sample request above:
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "2541"
}
]
},
{
"dimensionValues": [
{
"value": "France"
}
],
"metricValues": [
{
"value": "12"
}
]
}
],
"rowCount": 2
}
Dimensions
Dimensions describe and group event data for your
website or app. The city
dimension, for example, indicates the city ("Paris"
or "New York") from which each event originated. In a report request, you can
specify zero or more dimensions. See the Realtime Dimensions
for a full list of API Dimension names available in realtime requests.
For example, this request groups Active Users in two dimension columns:
POST https://analyticsdata.googleapis.com/v1alpha/property/YOUR_PROPERTY_ID:runRealtimeReport
{
"dimensions": [
{
"name": "country"
},
{
"name": "city"
}
],
"metrics": [{ "name": "activeUsers" }]
}
As a sample, a row in the report response could contain the following. This row means there are 47 Active Users for your website or app with events from Cape Town, South Africa in the last 30 minutes.
"rows": [
...
{
"dimensionValues": [
{
"value": "South Africa"
},
{
"value": "Cape Town"
}
],
"metricValues": [
{
"value": "47"
}
]
},
...
],
Metrics
Metrics are quantitative measurements of event data for your website or app. In a report request, you can specify one or more metrics. See the Realtime Metrics for a full list of API Metric names available in requests.
For example, this request will show the two metrics grouped by the dimension
unifiedScreenName
:
POST https://analyticsdata.googleapis.com/v1alpha/property/YOUR_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "unifiedScreenName" }],
"metrics": [
{
"name": "screenPageViews"
},
{
"name": "conversions"
}
],
}
As a sample, a row in report response could contain the following. This row
means that for the page title (web) or screen name (app) of main_menu
, there
were 257 views and 72 conversion events in last 30 minutes.
"rows": [
...
{
"dimensionValues": [
{
"value": "main_menu"
}
],
"metricValues": [
{
"value": "257"
},
{
"value": "72"
}
]
},
...
],
Pagination
By default, the report response contains at most the first 10,000 rows of event
data. For reports with 10,000 to 100,000 rows, you can include "limit": 100000
in the Realtime Request Body
to retrieve up to 100,000 rows.
Shared Features with Core Reports
Realtime report requests have the same semantics with Core report requests for many shared features. For example Dimension Filters and User Properties, behave the same in Realtime Reports as Core Reports.