Creating a Realtime Report

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

Note: Dimensions are not required in API requests.

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 rows of event data. You can include "limit": -1 in the Realtime Request Body to attempt to retrieve all 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.