RunReportRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-analytics/json-schema/google-analytics-run-report-request-schema.json",
  "title": "RunReportRequest",
  "description": "The request to generate a report.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/google-analytics-properties-api-openapi.yml#/components/schemas/RunReportRequest",
  "properties": {
    "cohortSpec": {
      "$ref": "#/$defs/CohortSpec",
      "description": "Cohort group associated with this request. If there is a cohort group in the request the 'cohort' dimension must be present."
    },
    "currencyCode": {
      "description": "A currency code in ISO4217 format, such as \"AED\", \"USD\", \"JPY\". If the field is empty, the report uses the property's default currency.",
      "type": "string"
    },
    "dateRanges": {
      "description": "Date ranges of data 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 event data for the overlapping days is included in the response rows for both date ranges. In a cohort request, this `dateRanges` must be unspecified.",
      "items": {
        "$ref": "#/$defs/DateRange"
      },
      "type": "array"
    },
    "dimensionFilter": {
      "$ref": "#/$defs/FilterExpression",
      "description": "Dimension filters let you ask for only specific dimension values in the report. To learn more, see [Fundamentals of Dimension Filters](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#dimension_filters) for examples. Metrics cannot be used in this filter."
    },
    "dimensions": {
      "description": "The dimensions requested and displayed.",
      "items": {
        "$ref": "#/$defs/Dimension"
      },
      "type": "array"
    },
    "keepEmptyRows": {
      "description": "If false or unspecified, each row with all metrics equal to 0 will not be returned. If true, these rows will be returned if they are not separately removed by a filter. Regardless of this `keep_empty_rows` setting, only data recorded by the Google Analytics (GA4) property can be displayed in a report. For example if a property never logs a `purchase` event, then a query for the `eventName` dimension and `eventCount` metric will not have a row eventName: \"purchase\" and eventCount: 0.",
      "type": "boolean"
    },
    "limit": {
      "description": "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. To learn more about this pagination parameter, see [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).",
      "format": "int64",
      "type": "string"
    },
    "metricAggregations": {
      "description": "Aggregation of metrics. Aggregated metric values will be shown in rows where the dimension_values are set to \"RESERVED_(MetricAggregation)\".",
      "items": {
        "enum": [
          "METRIC_AGGREGATION_UNSPECIFIED",
          "TOTAL",
          "MINIMUM",
          "MAXIMUM",
          "COUNT"
        ],
        "type": "string"
      },
      "type": "array"
    },
    "metricFilter": {
      "$ref": "#/$defs/FilterExpression",
      "description": "The filter clause of metrics. Applied after aggregating the report's rows, similar to SQL having-clause. Dimensions cannot be used in this filter."
    },
    "metrics": {
      "description": "The metrics requested and displayed.",
      "items": {
        "$ref": "#/$defs/Metric"
      },
      "type": "array"
    },
    "offset": {
      "description": "The row count of the start row. The first row is counted as row 0. When paging, the first request does not specify offset; or equivalently, sets offset to 0; the first request returns the first `limit` of rows. The second request sets offset to the `limit` of the first request; the second request returns the second `limit` of rows. To learn more about this pagination parameter, see [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).",
      "format": "int64",
      "type": "string"
    },
    "orderBys": {
      "description": "Specifies how rows are ordered in the response.",
      "items": {
        "$ref": "#/$defs/OrderBy"
      },
      "type": "array"
    },
    "property": {
      "description": "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](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id). Within a batch request, this property should either be unspecified or consistent with the batch-level property. Example: properties/1234",
      "type": "string"
    },
    "returnPropertyQuota": {
      "description": "Toggles whether to return the current state of this Analytics Property's quota. Quota is returned in [PropertyQuota](#PropertyQuota).",
      "type": "boolean"
    }
  },
  "type": "object",
  "$defs": {
    "BetweenFilter": {
      "description": "To express that the result needs to be between two numbers (inclusive).",
      "properties": {
        "fromValue": {
          "$ref": "#/$defs/NumericValue",
          "description": "Begins with this number."
        },
        "toValue": {
          "$ref": "#/$defs/NumericValue",
          "description": "Ends with this number."
        }
      },
      "type": "object"
    },
    "CaseExpression": {
      "description": "Used to convert a dimension value to a single case.",
      "properties": {
        "dimensionName": {
          "description": "Name of a dimension. The name must refer back to a name in dimensions field of the request.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "Cohort": {
      "description": "Defines a cohort selection criteria. A cohort is a group of users who share a common characteristic. For example, users with the same `firstSessionDate` belong to the same cohort.",
      "properties": {
        "dateRange": {
          "$ref": "#/$defs/DateRange",
          "description": "The cohort selects users whose first touch date is between start date and end date defined in the `dateRange`. This `dateRange` does not specify the full date range of event data that is present in a cohort report. In a cohort report, this `dateRange` is extended by the granularity and offset present in the `cohortsRange`; event data for the extended reporting date range is present in a cohort report. In a cohort request, this `dateRange` is required and the `dateRanges` in the `RunReportRequest` or `RunPivotReportRequest` must be unspecified. This `dateRange` should generally be aligned with the cohort's granularity. If `CohortsRange` uses daily granularity, this `dateRange` can be a single day. If `CohortsRange` uses weekly granularity, this `dateRange` can be aligned to a week boundary, starting at Sunday and ending Saturday. If `CohortsRange` uses monthly granularity, this `dateRange` can be aligned to a month, starting at the first and ending on the last day of the month."
        },
        "dimension": {
          "description": "Dimension used by the cohort. Required and only supports `firstSessionDate`.",
          "type": "string"
        },
        "name": {
          "description": "Assigns a name to this cohort. The dimension `cohort` is valued to this name in a report response. If set, cannot begin with `cohort_` or `RESERVED_`. If not set, cohorts are named by their zero based index `cohort_0`, `cohort_1`, etc.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "CohortReportSettings": {
      "description": "Optional settings of a cohort report.",
      "properties": {
        "accumulate": {
          "description": "If true, accumulates the result from first touch day to the end day. Not supported in `RunReportRequest`.",
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "CohortSpec": {
      "description": "The specification of cohorts for a cohort report. Cohort reports create a time series of user retention for the cohort. For example, you could select the cohort of users that were acquired in the first week of September and follow that cohort for the next six weeks. Selecting the users acquired in the first week of September cohort is specified in the `cohort` object. Following that cohort for the next six weeks is specified in the `cohortsRange` object. For examples, see [Cohort Report Examples](https://developers.google.com/analytics/devguides/reporting/data/v1/advanced#cohort_report_examples). The report response could show a weekly time series where say your app has retained 60% of this cohort after three weeks and 25% of this cohort after six weeks. These two percentages can be calculated by the metric `cohortActiveUsers/cohortTotalUsers` and will be separate rows in the report.",
      "properties": {
        "cohortReportSettings": {
          "$ref": "#/$defs/CohortReportSettings",
          "description": "Optional settings for a cohort report."
        },
        "cohorts": {
          "description": "Defines the selection criteria to group users into cohorts. Most cohort reports define only a single cohort. If multiple cohorts are specified, each cohort can be recognized in the report by their name.",
          "items": {
            "$ref": "#/$defs/Cohort"
          },
          "type": "array"
        },
        "cohortsRange": {
          "$ref": "#/$defs/CohortsRange",
          "description": "Cohort reports follow cohorts over an extended reporting date range. This range specifies an offset duration to follow the cohorts over."
        }
      },
      "type": "object"
    },
    "CohortsRange": {
      "description": "Configures the extended reporting date range for a cohort report. Specifies an offset duration to follow the cohorts over.",
      "properties": {
        "endOffset": {
          "description": "Required. `endOffset` specifies the end date of the extended reporting date range for a cohort report. `endOffset` can be any positive integer but is commonly set to 5 to 10 so that reports contain data on the cohort for the next several granularity time periods. If `granularity` is `DAILY`, the `endDate` of the extended reporting date range is `endDate` of the cohort plus `endOffset` days. If `granularity` is `WEEKLY`, the `endDate` of the extended reporting date range is `endDate` of the cohort plus `endOffset * 7` days. If `granularity` is `MONTHLY`, the `endDate` of the extended reporting date range is `endDate` of the cohort plus `endOffset * 30` days.",
          "format": "int32",
          "type": "integer"
        },
        "granularity": {
          "description": "Required. The granularity used to interpret the `startOffset` and `endOffset` for the extended reporting date range for a cohort report.",
          "enum": [
            "GRANULARITY_UNSPECIFIED",
            "DAILY",
            "WEEKLY",
            "MONTHLY"
          ],
          "type": "string"
        },
        "startOffset": {
          "description": "`startOffset` specifies the start date of the extended reporting date range for a cohort report. `startOffset` is commonly set to 0 so that reports contain data from the acquisition of the cohort forward. If `granularity` is `DAILY`, the `startDate` of the extended reporting date range is `startDate` of the cohort plus `startOffset` days. If `granularity` is `WEEKLY`, the `startDate` of the extended reporting date range is `startDate` of the cohort plus `startOffset * 7` days. If `granularity` is `MONTHLY`, the `startDate` of the extended reporting date range is `startDate` of the cohort plus `startOffset * 30` days.",
          "format": "int32",
          "type": "integer"
        }
      },
      "type": "object"
    },
    "ConcatenateExpression": {
      "description": "Used to combine dimension values to a single dimension.",
      "properties": {
        "delimiter": {
          "description": "The delimiter placed between dimension names. Delimiters are often single characters such as \"|\" or \",\" but can be longer strings. If a dimension value contains the delimiter, both will be present in response with no distinction. For example if dimension 1 value = \"US,FR\", dimension 2 value = \"JP\", and delimiter = \",\", then the response will contain \"US,FR,JP\".",
          "type": "string"
        },
        "dimensionNames": {
          "description": "Names of dimensions. The names must refer back to names in the dimensions field of the request.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "DateRange": {
      "description": "A contiguous set of days: `startDate`, `startDate + 1`, ..., `endDate`. Requests are allowed up to 4 date ranges.",
      "properties": {
        "endDate": {
          "description": "The inclusive end date for the query in the format `YYYY-MM-DD`. Cannot be before `start_date`. The format `NdaysAgo`, `yesterday`, or `today` is also accepted, and in that case, the date is inferred based on the property's reporting time zone.",
          "type": "string"
        },
        "name": {
          "description": "Assigns a name to this date 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, date ranges are named by their zero based index in the request: `date_range_0`, `date_range_1`, etc.",
          "type": "string"
        },
        "startDate": {
          "description": "The inclusive start date for the query in the format `YYYY-MM-DD`. Cannot be after `end_date`. The format `NdaysAgo`, `yesterday`, or `today` is also accepted, and in that case, the date is inferred based on the property's reporting time zone.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "Dimension": {
      "description": "Dimensions are attributes of your data. For example, the dimension city indicates the city from which an event originates. Dimension values in report responses are strings; for example, the city could be \"Paris\" or \"New York\". Requests are allowed up to 9 dimensions.",
      "properties": {
        "dimensionExpression": {
          "$ref": "#/$defs/DimensionExpression",
          "description": "One dimension can be the result of an expression of multiple dimensions. For example, dimension \"country, city\": concatenate(country, \", \", city)."
        },
        "name": {
          "description": "The name of the dimension. See the [API Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions) for the list of dimension names supported by core reporting methods such as `runReport` and `batchRunReports`. See [Realtime Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#dimensions) for the list of dimension names supported by the `runRealtimeReport` method. See [Funnel Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/exploration-api-schema#dimensions) for the list of dimension names supported by the `runFunnelReport` method. If `dimensionExpression` is specified, `name` can be any string that you would like within the allowed character set. For example if a `dimensionExpression` concatenates `country` and `city`, you could call that dimension `countryAndCity`. Dimension names that you choose must match the regular expression `^[a-zA-Z0-9_]$`. Dimensions are referenced by `name` in `dimensionFilter`, `orderBys`, `dimensionExpression`, and `pivots`.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "DimensionExpression": {
      "description": "Used to express a dimension which is the result of a formula of multiple dimensions. Example usages: 1) lower_case(dimension) 2) concatenate(dimension1, symbol, dimension2).",
      "properties": {
        "concatenate": {
          "$ref": "#/$defs/ConcatenateExpression",
          "description": "Used to combine dimension values to a single dimension. For example, dimension \"country, city\": concatenate(country, \", \", city)."
        },
        "lowerCase": {
          "$ref": "#/$defs/CaseExpression",
          "description": "Used to convert a dimension value to lower case."
        },
        "upperCase": {
          "$ref": "#/$defs/CaseExpression",
          "description": "Used to convert a dimension value to upper case."
        }
      },
      "type": "object"
    },
    "DimensionOrderBy": {
      "description": "Sorts by dimension values.",
      "properties": {
        "dimensionName": {
          "description": "A dimension name in the request to order by.",
          "type": "string"
        },
        "orderType": {
          "description": "Controls the rule for dimension value ordering.",
          "enum": [
            "ORDER_TYPE_UNSPECIFIED",
            "ALPHANUMERIC",
            "CASE_INSENSITIVE_ALPHANUMERIC",
            "NUMERIC"
          ],
          "type": "string"
        }
      },
      "type": "object"
    },
    "Filter": {
      "description": "An expression to filter dimension or metric values.",
      "properties": {
        "betweenFilter": {
          "$ref": "#/$defs/BetweenFilter",
          "description": "A filter for two values."
        },
        "fieldName": {
          "description": "The dimension name or metric name. In most methods, dimensions & metrics can be used for the first time in this field. However in a RunPivotReportRequest, this field must be additionally specified by name in the RunPivotReportRequest's dimensions or metrics.",
          "type": "string"
        },
        "inListFilter": {
          "$ref": "#/$defs/InListFilter",
          "description": "A filter for in list values."
        },
        "numericFilter": {
          "$ref": "#/$defs/NumericFilter",
          "description": "A filter for numeric or date values."
        },
        "stringFilter": {
          "$ref": "#/$defs/StringFilter",
          "description": "Strings related filter."
        }
      },
      "type": "object"
    },
    "FilterExpression": {
      "description": "To express dimension or metric filters. The fields in the same FilterExpression need to be either all dimensions or all metrics.",
      "properties": {
        "andGroup": {
          "$ref": "#/$defs/FilterExpressionList",
          "description": "The FilterExpressions in and_group have an AND relationship."
        },
        "filter": {
          "$ref": "#/$defs/Filter",
          "description": "A primitive filter. In the same FilterExpression, all of the filter's field names need to be either all dimensions or all metrics."
        },
        "notExpression": {
          "$ref": "#/$defs/FilterExpression",
          "description": "The FilterExpression is NOT of not_expression."
        },
        "orGroup": {
          "$ref": "#/$defs/FilterExpressionList",
          "description": "The FilterExpressions in or_group have an OR relationship."
        }
      },
      "type": "object"
    },
    "FilterExpressionList": {
      "description": "A list of filter expressions.",
      "properties": {
        "expressions": {
          "description": "A list of filter expressions.",
          "items": {
            "$ref": "#/$defs/FilterExpression"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "InListFilter": {
      "description": "The result needs to be in a list of string values.",
      "properties": {
        "caseSensitive": {
          "description": "If true, the string value is case sensitive.",
          "type": "boolean"
        },
        "values": {
          "description": "The list of string values. Must be non-empty.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "Metric": {
      "description": "The quantitative measurements of a report. For example, the metric `eventCount` is the total number of events. Requests are allowed up to 10 metrics.",
      "properties": {
        "expression": {
          "description": "A mathematical expression for derived metrics. For example, the metric Event count per user is `eventCount/totalUsers`.",
          "type": "string"
        },
        "invisible": {
          "description": "Indicates if a metric is invisible in the report response. If a metric is invisible, the metric will not produce a column in the response, but can be used in `metricFilter`, `orderBys`, or a metric `expression`.",
          "type": "boolean"
        },
        "name": {
          "description": "The name of the metric. See the [API Metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics) for the list of metric names supported by core reporting methods such as `runReport` and `batchRunReports`. See [Realtime Metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#metrics) for the list of metric names supported by the `runRealtimeReport` method. See [Funnel Metrics](https://developers.google.com/analytics/devguides/reporting/data/v1/exploration-api-schema#metrics) for the list of metric names supported by the `runFunnelReport` method. If `expression` is specified, `name` can be any string that you would like within the allowed character set. For example if `expression` is `screenPageViews/sessions`, you could call that metric's name = `viewsPerSession`. Metric names that you choose must match the regular expression `^[a-zA-Z0-9_]$`. Metrics are referenced by `name` in `metricFilter`, `orderBys`, and metric `expression`.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "MetricOrderBy": {
      "description": "Sorts by metric values.",
      "properties": {
        "metricName": {
          "description": "A metric name in the request to order by.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "NumericFilter": {
      "description": "Filters for numeric or date values.",
      "properties": {
        "operation": {
          "description": "The operation type for this filter.",
          "enum": [
            "OPERATION_UNSPECIFIED",
            "EQUAL",
            "LESS_THAN",
            "LESS_THAN_OR_EQUAL",
            "GREATER_THAN",
            "GREATER_THAN_OR_EQUAL"
          ],
          "type": "string"
        },
        "value": {
          "$ref": "#/$defs/NumericValue",
          "description": "A numeric value or a date value."
        }
      },
      "type": "object"
    },
    "NumericValue": {
      "description": "To represent a number.",
      "properties": {
        "doubleValue": {
          "description": "Double value",
          "format": "double",
          "type": "number"
        },
        "int64Value": {
          "description": "Integer value",
          "format": "int64",
          "type": "string"
        }
      },
      "type": "object"
    },
    "OrderBy": {
      "description": "Order bys define how rows will be sorted in the response. For example, ordering rows by descending event count is one ordering, and ordering rows by the event name string is a different ordering.",
      "properties": {
        "desc": {
          "description": "If true, sorts by descending order.",
          "type": "boolean"
        },
        "dimension": {
          "$ref": "#/$defs/DimensionOrderBy",
          "description": "Sorts results by a dimension's values."
        },
        "metric": {
          "$ref": "#/$defs/MetricOrderBy",
          "description": "Sorts results by a metric's values."
        },
        "pivot": {
          "$ref": "#/$defs/PivotOrderBy",
          "description": "Sorts results by a metric's values within a pivot column group."
        }
      },
      "type": "object"
    },
    "PivotOrderBy": {
      "description": "Sorts by a pivot column group.",
      "properties": {
        "metricName": {
          "description": "In the response to order by, order rows by this column. Must be a metric name from the request.",
          "type": "string"
        },
        "pivotSelections": {
          "description": "Used to select a dimension name and value pivot. If multiple pivot selections are given, the sort occurs on rows where all pivot selection dimension name and value pairs match the row's dimension name and value pair.",
          "items": {
            "$ref": "#/$defs/PivotSelection"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "PivotSelection": {
      "description": "A pair of dimension names and values. Rows with this dimension pivot pair are ordered by the metric's value. For example if pivots = {{\"browser\", \"Chrome\"}} and metric_name = \"Sessions\", then the rows will be sorted based on Sessions in Chrome. ---------|----------|----------------|----------|---------------- | Chrome | Chrome | Safari | Safari ---------|----------|----------------|----------|---------------- Country | Sessions | Pages/Sessions | Sessions | Pages/Sessions ---------|----------|----------------|----------|---------------- US | 2 | 2 | 3 | 1 ---------|----------|----------------|----------|---------------- Canada | 3 | 1 | 4 | 1 ---------|----------|----------------|----------|----------------",
      "properties": {
        "dimensionName": {
          "description": "Must be a dimension name from the request.",
          "type": "string"
        },
        "dimensionValue": {
          "description": "Order by only when the named dimension is this value.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "StringFilter": {
      "description": "The filter for string",
      "properties": {
        "caseSensitive": {
          "description": "If true, the string value is case sensitive.",
          "type": "boolean"
        },
        "matchType": {
          "description": "The match type for this filter.",
          "enum": [
            "MATCH_TYPE_UNSPECIFIED",
            "EXACT",
            "BEGINS_WITH",
            "ENDS_WITH",
            "CONTAINS",
            "FULL_REGEXP",
            "PARTIAL_REGEXP"
          ],
          "type": "string"
        },
        "value": {
          "description": "The string value used for the matching.",
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}