Input schema (JSON)
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"dateRanges",
"metrics"
],
"properties": {
"app": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Stream display name when the user refers to the app or stream by name."
},
"streamId": {
"type": "string",
"minLength": 1,
"description": "GA4 data stream ID for an app or web stream."
},
"firebaseAppId": {
"type": "string",
"minLength": 1,
"description": "Firebase app ID for GA4 app analytics."
},
"measurementId": {
"type": "string",
"minLength": 1,
"description": "GA4 web stream measurement ID such as G-XXXXXXX."
}
},
"description": "Optional app or web stream selector. Use this when the user identifies the GA4 source by stream ID, measurement ID, Firebase app ID, or stream name.",
"additionalProperties": false
},
"site": {
"type": "string",
"minLength": 1
},
"limit": {
"type": "integer",
"default": 1000,
"maximum": 100000,
"minimum": 1
},
"offset": {
"type": "integer",
"minimum": 0
},
"source": {
"enum": [
"ga4",
"search_console",
"bing_webmaster"
],
"type": "string"
},
"maxRows": {
"type": "integer",
"maximum": 1000000,
"minimum": 1
},
"metrics": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[-a-zA-Z0-9_:]+$"
},
"minItems": 1,
"description": "GA4 metric API names such as sessions, activeUsers, conversions, eventCount, totalRevenue, or engagedSessions. Include explicit numerator and denominator metrics when requesting significance context."
},
"siteUrl": {
"type": "string",
"minLength": 1
},
"sources": {
"type": "array",
"items": {
"$ref": "#/properties/source"
},
"minItems": 1
},
"orderBys": {
"type": "array",
"items": {
"type": "object",
"required": [
"fieldName"
],
"properties": {
"desc": {
"type": "boolean",
"default": false
},
"type": {
"enum": [
"dimension",
"metric"
],
"type": "string"
},
"fieldName": {
"$ref": "#/properties/metrics/items"
}
},
"additionalProperties": false
},
"description": "Optional sort order. Each entry requires fieldName (a GA4 API name like sessions or date) and optional desc (true for descending). Example: [{ fieldName: \"sessions\", desc: true }]."
},
"pageSize": {
"type": "integer",
"maximum": 250000,
"minimum": 1
},
"property": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "integer",
"exclusiveMinimum": 0
}
],
"description": "Google Analytics property identifier. Accepts a numeric GA4 property ID like 481373915 or a resource name like properties/481373915."
},
"surfaceId": {
"type": "string",
"minLength": 1,
"description": "Optional analysis surface ID. When omitted, the default surface is used if no explicit selector is provided."
},
"dateRanges": {
"type": "array",
"items": {
"type": "object",
"required": [
"startDate",
"endDate"
],
"properties": {
"endDate": {
"type": "string",
"minLength": 1
},
"startDate": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"minItems": 1,
"description": "One or more GA4 date ranges. Use two date ranges for period-over-period comparisons or significance checks."
},
"dimensions": {
"type": "array",
"items": {
"$ref": "#/properties/metrics/items"
},
"description": "Optional GA4 dimensions such as date, country, deviceCategory, landingPagePlusQueryString, or dateRange. Omit entirely for aggregate totals (renders as KPI widget). Only include when the user asks for a breakdown or trend."
},
"metricMode": {
"enum": [
"canonical",
"source_native"
],
"type": "string",
"default": "canonical"
},
"propertyId": {
"anyOf": [
{
"type": "string",
"pattern": "^\\d+$"
},
{
"type": "integer",
"exclusiveMinimum": 0
}
],
"description": "Numeric Google Analytics 4 property ID for website analytics or app analytics. Use this when the user references a GA4 property directly."
},
"sourceMode": {
"enum": [
"auto",
"single"
],
"type": "string",
"default": "auto"
},
"appStreamId": {
"type": "string",
"minLength": 1,
"description": "GA4 app or web data stream ID when the request targets a specific app stream or website stream."
},
"significance": {
"type": "object",
"required": [
"numeratorMetric",
"denominatorMetric"
],
"properties": {
"alpha": {
"type": "number",
"default": 0.05,
"maximum": 0.2,
"minimum": 0.001,
"description": "Optional significance threshold. Defaults to 0.05."
},
"comparison": {
"type": "object",
"properties": {
"type": {
"enum": [
"auto",
"date_ranges",
"dimension_rows"
],
"type": "string",
"default": "auto",
"description": "How to resolve the two comparison groups. auto infers from the report shape."
},
"variant": {
"type": "string",
"description": "Optional comparison row label when the report returns two named rows."
},
"baseline": {
"type": "string",
"description": "Optional baseline row label when the report returns two named rows."
}
},
"description": "Optional override for how the two report rows should be interpreted.",
"additionalProperties": false
},
"alternative": {
"enum": [
"two-sided",
"greater",
"less"
],
"type": "string",
"default": "two-sided",
"description": "Optional test direction. Defaults to two-sided."
},
"numeratorMetric": {
"type": "string",
"minLength": 1,
"description": "Explicit numerator metric for the rate test, such as conversions or engagedSessions."
},
"denominatorMetric": {
"type": "string",
"minLength": 1,
"description": "Explicit denominator metric for the rate test, such as sessions or totalUsers."
}
},
"description": "Optional significance context for GA4 rate comparisons. Use this only when the user asks whether a change is statistically significant or meaningful.",
"additionalProperties": false
},
"keepEmptyRows": {
"type": "boolean"
},
"metricFilters": {
"type": "array",
"items": {
"type": "object",
"required": [
"fieldName",
"operator",
"values"
],
"properties": {
"values": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"operator": {
"enum": [
"EQUAL",
"LESS_THAN",
"GREATER_THAN",
"BETWEEN"
],
"type": "string"
},
"fieldName": {
"$ref": "#/properties/metrics/items"
}
},
"additionalProperties": false
}
},
"returnAllRows": {
"type": "boolean"
},
"sourceOptions": {
"type": "object",
"properties": {
"searchConsole": {
"type": "object",
"properties": {
"type": {
"enum": [
"web",
"image",
"video",
"news",
"discover",
"googleNews"
],
"type": "string"
},
"rowLimit": {
"type": "integer",
"maximum": 25000,
"minimum": 1
},
"startRow": {
"type": "integer",
"minimum": 0
},
"dataState": {
"enum": [
"final",
"all",
"hourly_all"
],
"type": "string"
},
"aggregationType": {
"enum": [
"auto",
"byPage",
"byProperty"
],
"type": "string"
},
"dimensionFilterGroups": {
"type": "array",
"items": {
"type": "object",
"required": [
"filters"
],
"properties": {
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"dimension",
"operator",
"expression"
],
"properties": {
"operator": {
"enum": [
"contains",
"equals",
"notContains",
"notEquals",
"includingRegex",
"excludingRegex"
],
"type": "string"
},
"dimension": {
"type": "string",
"minLength": 1
},
"expression": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"minItems": 1
},
"groupType": {
"enum": [
"and",
"or"
],
"type": "string"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"dimensionFilters": {
"type": "array",
"items": {
"type": "object",
"required": [
"fieldName",
"operator",
"values"
],
"properties": {
"values": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"operator": {
"enum": [
"EXACT",
"CONTAINS",
"BEGINS_WITH",
"ENDS_WITH",
"REGEXP",
"IN_LIST"
],
"type": "string"
},
"fieldName": {
"$ref": "#/properties/metrics/items"
},
"caseSensitive": {
"type": "boolean"
}
},
"additionalProperties": false
}
},
"metricFilterExpression": {
"$ref": "#/properties/dimensionFilterExpression"
},
"dimensionFilterExpression": {
"type": "object",
"properties": {
"filter": {
"type": "object",
"required": [
"fieldName"
],
"properties": {
"fieldName": {
"$ref": "#/properties/metrics/items"
},
"inListFilter": {
"type": "object",
"required": [
"values"
],
"properties": {
"values": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"caseSensitive": {
"$ref": "#/properties/dimensionFilters/items/properties/caseSensitive"
}
},
"additionalProperties": false
},
"stringFilter": {
"type": "object",
"required": [
"matchType",
"value"
],
"properties": {
"value": {
"type": "string"
},
"matchType": {
"enum": [
"EXACT",
"CONTAINS",
"BEGINS_WITH",
"ENDS_WITH",
"REGEXP",
"FULL_REGEXP",
"PARTIAL_REGEXP"
],
"type": "string"
},
"caseSensitive": {
"$ref": "#/properties/dimensionFilters/items/properties/caseSensitive"
}
},
"additionalProperties": false
},
"betweenFilter": {
"type": "object",
"required": [
"fromValue",
"toValue"
],
"properties": {
"toValue": {
"$ref": "#/properties/dimensionFilterExpression/properties/filter/properties/numericFilter/properties/value"
},
"fromValue": {
"$ref": "#/properties/dimensionFilterExpression/properties/filter/properties/numericFilter/properties/value"
}
},
"additionalProperties": false
},
"numericFilter": {
"type": "object",
"required": [
"operation",
"value"
],
"properties": {
"value": {
"anyOf": [
{
"type": "number"
},
{
"type": "string",
"minLength": 1
}
]
},
"operation": {
"enum": [
"EQUAL",
"LESS_THAN",
"GREATER_THAN",
"LESS_THAN_OR_EQUAL",
"GREATER_THAN_OR_EQUAL"
],
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
"orGroup": {
"type": "object",
"required": [
"expressions"
],
"properties": {
"expressions": {
"type": "array",
"items": {
"$ref": "#/properties/dimensionFilterExpression"
},
"minItems": 1
}
},
"additionalProperties": false
},
"andGroup": {
"type": "object",
"required": [
"expressions"
],
"properties": {
"expressions": {
"type": "array",
"items": {
"$ref": "#/properties/dimensionFilterExpression"
},
"minItems": 1
}
},
"additionalProperties": false
},
"notExpression": {
"$ref": "#/properties/dimensionFilterExpression"
}
},
"additionalProperties": false
}
},
"additionalProperties": true
}