Method: properties.runAccessReport

Stay organized with collections Save and categorize content based on your preferences.

Returns a customized report of data access records. The report provides records of each time a user reads Google Analytics reporting data. Access records are retained for up to 2 years.

Data Access Reports can be requested for a property. The property must be in Google Analytics 360. This method is only available to Administrators.

These data access records include GA4 UI Reporting, GA4 UI Explorations, GA4 Data API, and other products like Firebase & Admob that can retrieve data from Google Analytics through a linkage. These records don't include property configuration changes like adding a stream or changing a property's time zone. For configuration change history, see searchChangeHistoryEvents.

HTTP request

POST https://analyticsadmin.googleapis.com/v1alpha/{entity=properties/*}:runAccessReport

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
entity

string

The Data Access Report is requested for this property. For example if "123" is your GA4 property ID, then entity should be "properties/123".

Request body

The request body contains data with the following structure:

JSON representation
{
  "dimensions": [
    {
      object (AccessDimension)
    }
  ],
  "metrics": [
    {
      object (AccessMetric)
    }
  ],
  "dateRanges": [
    {
      object (AccessDateRange)
    }
  ],
  "dimensionFilter": {
    object (AccessFilterExpression)
  },
  "metricFilter": {
    object (AccessFilterExpression)
  },
  "offset": string,
  "limit": string,
  "timeZone": string,
  "orderBys": [
    {
      object (AccessOrderBy)
    }
  ],
  "returnEntityQuota": boolean
}
Fields
dimensions[]

object (AccessDimension)

The dimensions requested and displayed in the response. Requests are allowed up to 9 dimensions.

metrics[]

object (AccessMetric)

The metrics requested and displayed in the response. Requests are allowed up to 10 metrics.

dateRanges[]

object (AccessDateRange)

Date ranges of access records to read. If multiple date ranges are requested, each response row will contain a zero based date range index. If two date ranges overlap, the access records for the overlapping days is included in the response rows for both date ranges. Requests are allowed up to 2 date ranges.

dimensionFilter

object (AccessFilterExpression)

Dimension filters allow you to restrict report response to specific dimension values which match the filter. For example, filtering on access records of a single user. To learn more, see Fundamentals of Dimension Filters for examples. Metrics cannot be used in this filter.

metricFilter

object (AccessFilterExpression)

Metric filters allow you to restrict report response to specific metric values which match the filter. Metric filters are applied after aggregating the report's rows, similar to SQL having-clause. Dimensions cannot be used in this filter.

offset

string (int64 format)

The row count of the start row. The first row is counted as row 0. If offset is unspecified, it is treated as 0. If offset is zero, then this method will return the first page of results with limit entries.

To learn more about this pagination parameter, see Pagination.

limit

string (int64 format)

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

The API may return fewer rows than the requested limit, if there aren't as many remaining rows 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.

To learn more about this pagination parameter, see Pagination.

timeZone

string

This request's time zone if specified. If unspecified, the property's time zone is used. The request's time zone is used to interpret the start & end dates of the report.

Formatted as strings from the IANA Time Zone database (https://www.iana.org/time-zones); for example "America/New_York" or "Asia/Tokyo".

orderBys[]

object (AccessOrderBy)

Specifies how rows are ordered in the response.

returnEntityQuota

boolean

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

Response body

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

The customized Data Access Record Report response.

JSON representation
{
  "dimensionHeaders": [
    {
      object (AccessDimensionHeader)
    }
  ],
  "metricHeaders": [
    {
      object (AccessMetricHeader)
    }
  ],
  "rows": [
    {
      object (AccessRow)
    }
  ],
  "rowCount": integer,
  "quota": {
    object (AccessQuota)
  }
}
Fields
dimensionHeaders[]

object (AccessDimensionHeader)

The header for a column in the report that corresponds to a specific dimension. The number of DimensionHeaders and ordering of DimensionHeaders matches the dimensions present in rows.

metricHeaders[]

object (AccessMetricHeader)

The header for a column in the report that corresponds to a specific metric. The number of MetricHeaders and ordering of MetricHeaders matches the metrics present in rows.

rows[]

object (AccessRow)

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

rowCount

integer

The total number of rows in the query result. rowCount is independent of the number of rows returned in the response, the limit request parameter, and the offset 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.

To learn more about this pagination parameter, see Pagination.

quota

object (AccessQuota)

The quota state for this Analytics property including this request.

Authorization Scopes

Requires one of the following OAuth scopes:

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

AccessDimension

Dimensions are attributes of your data. For example, the dimension userEmail indicates the email of the user that accessed reporting data. Dimension values in report responses are strings.

JSON representation
{
  "dimensionName": string
}
Fields
dimensionName

string

The API name of the dimension. See Data Access Schema for the list of dimensions supported in this API.

Dimensions are referenced by name in dimensionFilter and orderBys.

AccessMetric

The quantitative measurements of a report. For example, the metric accessCount is the total number of data access records.

JSON representation
{
  "metricName": string
}
Fields
metricName

string

The API name of the metric. See Data Access Schema for the list of metrics supported in this API.

Metrics are referenced by name in metricFilter & orderBys.

AccessDateRange

A contiguous range of days: startDate, startDate + 1, ..., endDate.

JSON representation
{
  "startDate": string,
  "endDate": string
}
Fields
startDate

string

The inclusive start date for the query in the format YYYY-MM-DD. Cannot be after endDate. The format NdaysAgo, yesterday, or today is also accepted, and in that case, the date is inferred based on the current time in the request's time zone.

endDate

string

The inclusive end date for the query in the format YYYY-MM-DD. Cannot be before startDate. The format NdaysAgo, yesterday, or today is also accepted, and in that case, the date is inferred based on the current time in the request's time zone.

AccessFilterExpression

Expresses dimension or metric filters. The fields in the same expression need to be either all dimensions or all metrics.

JSON representation
{

  // Union field one_expression can be only one of the following:
  "andGroup": {
    object (AccessFilterExpressionList)
  },
  "orGroup": {
    object (AccessFilterExpressionList)
  },
  "notExpression": {
    object (AccessFilterExpression)
  },
  "accessFilter": {
    object (AccessFilter)
  }
  // End of list of possible types for union field one_expression.
}
Fields
Union field one_expression. Specify one type of filter expression for FilterExpression. one_expression can be only one of the following:
andGroup

object (AccessFilterExpressionList)

Each of the FilterExpressions in the andGroup has an AND relationship.

orGroup

object (AccessFilterExpressionList)

Each of the FilterExpressions in the orGroup has an OR relationship.

notExpression

object (AccessFilterExpression)

The FilterExpression is NOT of notExpression.

accessFilter

object (AccessFilter)

A primitive filter. In the same FilterExpression, all of the filter's field names need to be either all dimensions or all metrics.

AccessFilterExpressionList

A list of filter expressions.

JSON representation
{
  "expressions": [
    {
      object (AccessFilterExpression)
    }
  ]
}
Fields
expressions[]

object (AccessFilterExpression)

A list of filter expressions.

AccessFilter

An expression to filter dimension or metric values.

JSON representation
{
  "fieldName": string,

  // Union field one_filter can be only one of the following:
  "stringFilter": {
    object (AccessStringFilter)
  },
  "inListFilter": {
    object (AccessInListFilter)
  },
  "numericFilter": {
    object (AccessNumericFilter)
  },
  "betweenFilter": {
    object (AccessBetweenFilter)
  }
  // End of list of possible types for union field one_filter.
}
Fields
fieldName

string

The dimension name or metric name.

Union field one_filter. Specify one type of filter for Filter. one_filter can be only one of the following:
stringFilter

object (AccessStringFilter)

Strings related filter.

inListFilter

object (AccessInListFilter)

A filter for in list values.

numericFilter

object (AccessNumericFilter)

A filter for numeric or date values.

betweenFilter

object (AccessBetweenFilter)

A filter for two values.

AccessStringFilter

The filter for strings.

JSON representation
{
  "matchType": enum (MatchType),
  "value": string,
  "caseSensitive": boolean
}
Fields
matchType

enum (MatchType)

The match type for this filter.

value

string

The string value used for the matching.

caseSensitive

boolean

If true, the string value is case sensitive.

MatchType

The match type of a string filter.

Enums
MATCH_TYPE_UNSPECIFIED Unspecified
EXACT Exact match of the string value.
BEGINS_WITH Begins with the string value.
ENDS_WITH Ends with the string value.
CONTAINS Contains the string value.
FULL_REGEXP Full match for the regular expression with the string value.
PARTIAL_REGEXP Partial match for the regular expression with the string value.

AccessInListFilter

The result needs to be in a list of string values.

JSON representation
{
  "values": [
    string
  ],
  "caseSensitive": boolean
}
Fields
values[]

string

The list of string values. Must be non-empty.

caseSensitive

boolean

If true, the string value is case sensitive.

AccessNumericFilter

Filters for numeric or date values.

JSON representation
{
  "operation": enum (Operation),
  "value": {
    object (NumericValue)
  }
}
Fields
operation

enum (Operation)

The operation type for this filter.

value

object (NumericValue)

A numeric value or a date value.

Operation

The operation applied to a numeric filter.

Enums
OPERATION_UNSPECIFIED Unspecified.
EQUAL Equal
LESS_THAN Less than
LESS_THAN_OR_EQUAL Less than or equal
GREATER_THAN Greater than
GREATER_THAN_OR_EQUAL Greater than or equal

NumericValue

To represent a number.

JSON representation
{

  // Union field one_value can be only one of the following:
  "int64Value": string,
  "doubleValue": number
  // End of list of possible types for union field one_value.
}
Fields
Union field one_value. One of a numeric value one_value can be only one of the following:
int64Value

string (int64 format)

Integer value

doubleValue

number

Double value

AccessBetweenFilter

To express that the result needs to be between two numbers (inclusive).

JSON representation
{
  "fromValue": {
    object (NumericValue)
  },
  "toValue": {
    object (NumericValue)
  }
}
Fields
fromValue

object (NumericValue)

Begins with this number.

toValue

object (NumericValue)

Ends with this number.

AccessOrderBy

Order bys define how rows will be sorted in the response. For example, ordering rows by descending access count is one ordering, and ordering rows by the country string is a different ordering.

JSON representation
{
  "desc": boolean,

  // Union field one_order_by can be only one of the following:
  "metric": {
    object (MetricOrderBy)
  },
  "dimension": {
    object (DimensionOrderBy)
  }
  // End of list of possible types for union field one_order_by.
}
Fields
desc

boolean

If true, sorts by descending order. If false or unspecified, sorts in ascending order.

Union field one_order_by. Specify one type of order by for OrderBy. one_order_by can be only one of the following:
metric

object (MetricOrderBy)

Sorts results by a metric's values.

dimension

object (DimensionOrderBy)

Sorts results by a dimension's values.

MetricOrderBy

Sorts by metric values.

JSON representation
{
  "metricName": string
}
Fields
metricName

string

A metric name in the request to order by.

DimensionOrderBy

Sorts by dimension values.

JSON representation
{
  "dimensionName": string,
  "orderType": enum (OrderType)
}
Fields
dimensionName

string

A dimension name in the request to order by.

orderType

enum (OrderType)

Controls the rule for dimension value ordering.

OrderType

Rule to order the string dimension values by.

Enums
ORDER_TYPE_UNSPECIFIED Unspecified.
ALPHANUMERIC Alphanumeric sort by Unicode code point. For example, "2" < "A" < "X" < "b" < "z".
CASE_INSENSITIVE_ALPHANUMERIC Case insensitive alphanumeric sort by lower case Unicode code point. For example, "2" < "A" < "b" < "X" < "z".
NUMERIC Dimension values are converted to numbers before sorting. For example in NUMERIC sort, "25" < "100", and in ALPHANUMERIC sort, "100" < "25". Non-numeric dimension values all have equal ordering value below all numeric values.

AccessDimensionHeader

Describes a dimension column in the report. Dimensions requested in a report produce column entries within rows and DimensionHeaders. However, dimensions used exclusively within filters or expressions do not produce columns in a report; correspondingly, those dimensions do not produce headers.

JSON representation
{
  "dimensionName": string
}
Fields
dimensionName

string

The dimension's name; for example 'userEmail'.

AccessMetricHeader

Describes a metric column in the report. Visible metrics requested in a report produce column entries within rows and MetricHeaders. However, metrics used exclusively within filters or expressions do not produce columns in a report; correspondingly, those metrics do not produce headers.

JSON representation
{
  "metricName": string
}
Fields
metricName

string

The metric's name; for example 'accessCount'.

AccessRow

Access report data for each row.

JSON representation
{
  "dimensionValues": [
    {
      object (AccessDimensionValue)
    }
  ],
  "metricValues": [
    {
      object (AccessMetricValue)
    }
  ]
}
Fields
dimensionValues[]

object (AccessDimensionValue)

List of dimension values. These values are in the same order as specified in the request.

metricValues[]

object (AccessMetricValue)

List of metric values. These values are in the same order as specified in the request.

AccessDimensionValue

The value of a dimension.

JSON representation
{
  "value": string
}
Fields
value

string

The dimension value. For example, this value may be 'France' for the 'country' dimension.

AccessMetricValue

The value of a metric.

JSON representation
{
  "value": string
}
Fields
value

string

The measurement value. For example, this value may be '13'.

AccessQuota

Current state of all quotas for this Analytics property. If any quota for a property is exhausted, all requests to that property will return Resource Exhausted errors.

JSON representation
{
  "tokensPerDay": {
    object (AccessQuotaStatus)
  },
  "tokensPerHour": {
    object (AccessQuotaStatus)
  },
  "concurrentRequests": {
    object (AccessQuotaStatus)
  },
  "serverErrorsPerProjectPerHour": {
    object (AccessQuotaStatus)
  },
  "tokensPerProjectPerHour": {
    object (AccessQuotaStatus)
  }
}
Fields
tokensPerDay

object (AccessQuotaStatus)

Properties can use 250,000 tokens per day. Most requests consume fewer than 10 tokens.

tokensPerHour

object (AccessQuotaStatus)

Properties can use 50,000 tokens per hour. An API request consumes a single number of tokens, and that number is deducted from all of the hourly, daily, and per project hourly quotas.

concurrentRequests

object (AccessQuotaStatus)

Properties can use up to 50 concurrent requests.

serverErrorsPerProjectPerHour

object (AccessQuotaStatus)

Properties and cloud project pairs can have up to 50 server errors per hour.

tokensPerProjectPerHour

object (AccessQuotaStatus)

Properties can use up to 25% of their tokens per project per hour. This amounts to Analytics 360 Properties can use 12,500 tokens per project per hour. An API request consumes a single number of tokens, and that number is deducted from all of the hourly, daily, and per project hourly quotas.

AccessQuotaStatus

Current state for a particular quota group.

JSON representation
{
  "consumed": integer,
  "remaining": integer
}
Fields
consumed

integer

Quota consumed by this request.

remaining

integer

Quota remaining after this request.