Method: properties.runRealtimeReport

Returns a customized report of realtime event data for your property. Events appear in realtime reports seconds after they have been sent to the Google Analytics. Realtime reports show events and usage data for the periods of time ranging from the present moment to 30 minutes ago (up to 60 minutes for Google Analytics 360 properties).

For a guide to constructing realtime requests & understanding responses, see Creating a Realtime Report.

HTTP request

POST https://analyticsdata.googleapis.com/v1beta/{property=properties/*}:runRealtimeReport

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
property

string

A Google Analytics GA4 property identifier whose events are tracked. Specified in the URL path and not the body. To learn more, see where to find your Property ID.

Example: properties/1234

Request body

The request body contains data with the following structure:

JSON representation
{
  "dimensions": [
    {
      object (Dimension)
    }
  ],
  "metrics": [
    {
      object (Metric)
    }
  ],
  "dimensionFilter": {
    object (FilterExpression)
  },
  "metricFilter": {
    object (FilterExpression)
  },
  "limit": string,
  "metricAggregations": [
    enum (MetricAggregation)
  ],
  "orderBys": [
    {
      object (OrderBy)
    }
  ],
  "returnPropertyQuota": boolean,
  "minuteRanges": [
    {
      object (MinuteRange)
    }
  ]
}
Fields
dimensions[]

object (Dimension)

The dimensions requested and displayed.

metrics[]

object (Metric)

The metrics requested and displayed.

dimensionFilter

object (FilterExpression)

The filter clause of dimensions. Metrics cannot be used in this filter.

metricFilter

object (FilterExpression)

The filter clause of metrics. Applied at post aggregation phase, similar to SQL having-clause. Dimensions cannot be used in this filter.

limit

string (int64 format)

The number of rows to return. If unspecified, 10,000 rows are returned. The API returns a maximum of 250,000 rows per request, no matter how many you ask for. limit must be positive.

The API can also return fewer rows than the requested limit, if there aren't as many dimension values as the limit. For instance, there are fewer than 300 possible values for the dimension country, so when reporting on only country, you can't get more than 300 rows, even if you set limit to a higher value.

metricAggregations[]

enum (MetricAggregation)

Aggregation of metrics. Aggregated metric values will be shown in rows where the dimensionValues are set to "RESERVED_(MetricAggregation)".

orderBys[]

object (OrderBy)

Specifies how rows are ordered in the response.

returnPropertyQuota

boolean

Toggles whether to return the current state of this Analytics Property's Realtime quota. Quota is returned in PropertyQuota.

minuteRanges[]

object (MinuteRange)

The minute ranges of event data to read. If unspecified, one minute range for the last 30 minutes will be used. If multiple minute ranges are requested, each response row will contain a zero based minute range index. If two minute ranges overlap, the event data for the overlapping minutes is included in the response rows for both minute ranges.

Response body

The response realtime report table corresponding to a request.

If successful, the response body contains data with the following structure:

JSON representation
{
  "dimensionHeaders": [
    {
      object (DimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (MetricHeader)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totals": [
    {
      object (Row)
    }
  ],
  "maximums": [
    {
      object (Row)
    }
  ],
  "minimums": [
    {
      object (Row)
    }
  ],
  "rowCount": integer,
  "propertyQuota": {
    object (PropertyQuota)
  },
  "kind": string
}
Fields
dimensionHeaders[]

object (DimensionHeader)

Describes dimension columns. The number of DimensionHeaders and ordering of DimensionHeaders matches the dimensions present in rows.

metricHeaders[]

object (MetricHeader)

Describes metric columns. The number of MetricHeaders and ordering of MetricHeaders matches the metrics present in rows.

rows[]

object (Row)

Rows of dimension value combinations and metric values in the report.

totals[]

object (Row)

If requested, the totaled values of metrics.

maximums[]

object (Row)

If requested, the maximum values of metrics.

minimums[]

object (Row)

If requested, the minimum values of metrics.

rowCount

integer

The total number of rows in the query result. rowCount is independent of the number of rows returned in the response and the limit request parameter. For example if a query returns 175 rows and includes limit of 50 in the API request, the response will contain rowCount of 175 but only 50 rows.

propertyQuota

object (PropertyQuota)

This Analytics Property's Realtime quota state including this request.

kind

string

Identifies what kind of resource this message is. This kind is always the fixed string "analyticsData#runRealtimeReport". Useful to distinguish between response types in JSON.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

MinuteRange

A contiguous set of minutes: startMinutesAgo, startMinutesAgo + 1, ..., endMinutesAgo. Requests are allowed up to 2 minute ranges.

JSON representation
{
  "name": string,
  "startMinutesAgo": integer,
  "endMinutesAgo": integer
}
Fields
name

string

Assigns a name to this minute range. The dimension dateRange is valued to this name in a report response. If set, cannot begin with date_range_ or RESERVED_. If not set, minute ranges are named by their zero based index in the request: date_range_0, date_range_1, etc.

startMinutesAgo

integer

The inclusive start minute for the query as a number of minutes before now. For example, "startMinutesAgo": 29 specifies the report should include event data from 29 minutes ago and after. Cannot be after endMinutesAgo.

If unspecified, startMinutesAgo is defaulted to 29. Standard Analytics properties can request up to the last 30 minutes of event data (startMinutesAgo <= 29), and 360 Analytics properties can request up to the last 60 minutes of event data (startMinutesAgo <= 59).

endMinutesAgo

integer

The inclusive end minute for the query as a number of minutes before now. Cannot be before startMinutesAgo. For example, "endMinutesAgo": 15 specifies the report should include event data from prior to 15 minutes ago.

If unspecified, endMinutesAgo is defaulted to 0. Standard Analytics properties can request any minute in the last 30 minutes of event data (endMinutesAgo <= 29), and 360 Analytics properties can request any minute in the last 60 minutes of event data (endMinutesAgo <= 59).