- HTTP request
- Path parameters
- Request body
- Response body
- Authorization Scopes
- AccessDimension
- AccessMetric
- AccessDateRange
- AccessFilterExpression
- AccessFilterExpressionList
- AccessFilter
- AccessStringFilter
- MatchType
- AccessInListFilter
- AccessNumericFilter
- Operation
- NumericValue
- AccessBetweenFilter
- AccessOrderBy
- MetricOrderBy
- DimensionOrderBy
- OrderType
- AccessDimensionHeader
- AccessMetricHeader
- AccessRow
- AccessDimensionValue
- AccessMetricValue
- AccessQuota
- AccessQuotaStatus
- Try it!
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 |
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 ( |
Fields | |
---|---|
dimensions[] |
The dimensions requested and displayed in the response. Requests are allowed up to 9 dimensions. |
metrics[] |
The metrics requested and displayed in the response. Requests are allowed up to 10 metrics. |
dateRanges[] |
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 |
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 |
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 |
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 To learn more about this pagination parameter, see Pagination. |
limit |
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. The API may return fewer rows than the requested To learn more about this pagination parameter, see Pagination. |
timeZone |
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[] |
Specifies how rows are ordered in the response. |
returnEntityQuota |
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 ( |
Fields | |
---|---|
dimensionHeaders[] |
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[] |
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[] |
Rows of dimension value combinations and metric values in the report. |
rowCount |
The total number of rows in the query result. To learn more about this pagination parameter, see Pagination. |
quota |
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 |
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 |
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 |
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 |
AccessDateRange
A contiguous range of days: startDate, startDate + 1, ..., endDate.
JSON representation |
---|
{ "startDate": string, "endDate": string } |
Fields | |
---|---|
startDate |
The inclusive start date for the query in the format |
endDate |
The inclusive end date for the query in the format |
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 |
Fields | |
---|---|
Union field one_expression . Specify one type of filter expression for FilterExpression . one_expression can be only one of the following: |
|
andGroup |
Each of the FilterExpressions in the andGroup has an AND relationship. |
orGroup |
Each of the FilterExpressions in the orGroup has an OR relationship. |
notExpression |
The FilterExpression is NOT of notExpression. |
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 ( |
Fields | |
---|---|
expressions[] |
A list of filter expressions. |
AccessFilter
An expression to filter dimension or metric values.
JSON representation |
---|
{ "fieldName": string, // Union field |
Fields | |
---|---|
fieldName |
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 |
Strings related filter. |
inListFilter |
A filter for in list values. |
numericFilter |
A filter for numeric or date values. |
betweenFilter |
A filter for two values. |
AccessStringFilter
The filter for strings.
JSON representation |
---|
{
"matchType": enum ( |
Fields | |
---|---|
matchType |
The match type for this filter. |
value |
The string value used for the matching. |
caseSensitive |
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[] |
The list of string values. Must be non-empty. |
caseSensitive |
If true, the string value is case sensitive. |
AccessNumericFilter
Filters for numeric or date values.
JSON representation |
---|
{ "operation": enum ( |
Fields | |
---|---|
operation |
The operation type for this filter. |
value |
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 |
Fields | |
---|---|
Union field one_value . One of a numeric value one_value can be only one of the following: |
|
int64Value |
Integer value |
doubleValue |
Double value |
AccessBetweenFilter
To express that the result needs to be between two numbers (inclusive).
JSON representation |
---|
{ "fromValue": { object ( |
Fields | |
---|---|
fromValue |
Begins with this number. |
toValue |
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 |
Fields | |
---|---|
desc |
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 |
Sorts results by a metric's values. |
dimension |
Sorts results by a dimension's values. |
MetricOrderBy
Sorts by metric values.
JSON representation |
---|
{ "metricName": string } |
Fields | |
---|---|
metricName |
A metric name in the request to order by. |
DimensionOrderBy
Sorts by dimension values.
JSON representation |
---|
{
"dimensionName": string,
"orderType": enum ( |
Fields | |
---|---|
dimensionName |
A dimension name in the request to order by. |
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 |
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 |
The metric's name; for example 'accessCount'. |
AccessRow
Access report data for each row.
JSON representation |
---|
{ "dimensionValues": [ { object ( |
Fields | |
---|---|
dimensionValues[] |
List of dimension values. These values are in the same order as specified in the request. |
metricValues[] |
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 |
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 |
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 ( |
Fields | |
---|---|
tokensPerDay |
Properties can use 250,000 tokens per day. Most requests consume fewer than 10 tokens. |
tokensPerHour |
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 |
Properties can use up to 50 concurrent requests. |
serverErrorsPerProjectPerHour |
Properties and cloud project pairs can have up to 50 server errors per hour. |
tokensPerProjectPerHour |
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 |
Quota consumed by this request. |
remaining |
Quota remaining after this request. |