{ "openapi": "3.1.0", "info": { "title": "Google Analytics MCP Server", "description": "Google Analytics 4 Admin and Data API for property configuration and reporting", "version": "1.0.0", "contact": { "name": "Hopkin", "url": "https://hopkin.ai" } }, "servers": [ { "url": "https://ga4.mcp.hopkin.ai", "description": "Production MCP endpoint" } ], "paths": { "/tools": { "get": { "operationId": "listTools", "summary": "List available tools", "description": "Returns all tools registered on this server with their names, descriptions, and input schemas.", "tags": [ "discovery" ], "responses": { "200": { "description": "Tool list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolList" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } } } } }, "/tools/ga4_list_account_summaries": { "post": { "operationId": "ga4_list_account_summaries", "summary": "List GA4 Accounts & Properties", "description": "List every GA4 account and property visible to the connected Google account (Admin API accountSummaries).\n\nUse this tool first to discover which properties are available before calling other GA4 tools.\nResults are cached; pass refresh=true only when you need the latest list.\n\nArgs:\n limit (number, optional): Max accounts per page (default 20, max 200).\n cursor (string, optional): Opaque pagination cursor from a previous response's top-level nextCursor.\n refresh (bool, optional): Force a fresh fetch from the API, bypassing cache. Default: false.\n\nReturns:\n data: accounts (each with account resource name, display_name, and properties[] of { property_id, display_name, property_type, parent }).\n data (the accounts), count (total accounts), property_count (total properties), cached, synced_at, and nextCursor — present only when another page exists.", "tags": [ "-account-summaries" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Max accounts per page (default 20)." }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response's pagination.nextCursor. Do not construct by hand." }, "refresh": { "type": "boolean", "description": "Force a fresh fetch from the Admin API, bypassing the cache. Default: false." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-accounts-properties": { "summary": "List accounts & properties", "value": { "reason": "Discover which GA4 properties are available" } }, "next-page": { "summary": "Next page", "value": { "limit": 20, "cursor": "eyJvZmZzZXQiOjIwfQ==", "reason": "Fetch the next page of accounts" } }, "force-refresh": { "summary": "Force refresh", "value": { "refresh": true, "reason": "Need the latest account/property list" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_check_auth_status": { "post": { "operationId": "ga4_check_auth_status", "summary": "Check GA4 Auth Status", "description": "Troubleshoot authentication issues. Only use this when another tool fails with a permission or auth error — do NOT call proactively.\n\nReturns: authenticated status, user_id, email, and a human-readable message.", "tags": [ "k-auth-status" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "check-auth": { "summary": "Check auth", "value": { "reason": "Another tool returned an auth error, checking connection status" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_list_connections": { "post": { "operationId": "ga4_list_connections", "summary": "List Google Analytics Connections", "description": "List the Google Analytics connections available to you — both ones you own and ones shared with you via an organization. Only Google connections with Google Analytics (analytics.readonly) scope are returned. Use this to discover connection IDs for set_default / share / rename / revoke.", "tags": [ "-connections" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-connections": { "summary": "List connections", "value": { "reason": "User asked which Google Analytics accounts they have connected" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_set_default_connection": { "post": { "operationId": "ga4_set_default_connection", "summary": "Set Default Google Analytics Connection", "description": "Set the Google Analytics connection that should be used by default for subsequent GA4 tool calls. The default is scoped to the calling actor (your user account, or the API key being used).", "tags": [ "default-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to mark as the actor's default Google Analytics connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "set-default": { "summary": "Set default", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User picked their primary Google Analytics workspace" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_share_connection": { "post": { "operationId": "ga4_share_connection", "summary": "Share Google Analytics Connection With Organization", "description": "Share an owned Google Analytics connection with all members of your organization, so teammates can use it without having to reconnect Google themselves. You must be the owner of the connection.", "tags": [ "e-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to mark as the actor's default Google Analytics connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "share-with-org": { "summary": "Share with org", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User asked to share this Google Analytics connection with their teammates" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_unshare_connection": { "post": { "operationId": "ga4_unshare_connection", "summary": "Unshare Google Analytics Connection From Organization", "description": "Stop sharing an owned Google Analytics connection with your organization. Teammates lose access immediately. You must be the owner.", "tags": [ "are-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to mark as the actor's default Google Analytics connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "stop-sharing": { "summary": "Stop sharing", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User no longer wants the team to access this Google Analytics connection" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_rename_connection": { "post": { "operationId": "ga4_rename_connection", "summary": "Rename Google Analytics Connection", "description": "Rename the display name of an owned Google Analytics connection. The OAuth grant and underlying account are unaffected — this only changes the human-readable label. You must be the owner.", "tags": [ "me-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to mark as the actor's default Google Analytics connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "rename": { "summary": "Rename", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "display_name": "Acme — Production", "reason": "User wanted a clearer label for this Google Analytics connection" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_revoke_connection": { "post": { "operationId": "ga4_revoke_connection", "summary": "Revoke Google Analytics Connection", "description": "Revoke (soft-delete) an owned Google Analytics connection. Any defaults pointing to it are invalidated and shared org members lose access. The OAuth grant at Google is NOT revoked by this tool — the user must disconnect via the dashboard if they want to fully revoke at Google. You must be the owner.", "tags": [ "ke-connection" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid", "description": "UUID of the connection to mark as the actor's default Google Analytics connection." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "connection_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "revoke": { "summary": "Revoke", "value": { "connection_id": "00000000-0000-0000-0000-000000000001", "reason": "User asked to disconnect this Google Analytics account" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_developer_feedback": { "post": { "operationId": "ga4_developer_feedback", "summary": "Submit Developer Feedback", "description": "Submit feedback about missing tools, improvements, bugs, or workflow gaps in the GA4 MCP toolset. Not for user-facing issues (auth errors, API errors).\n\nArgs:\n feedback_type: new_tool, improvement, bug, workflow_gap\n title: Short description (5-200 chars)\n description: What is needed and why (20-2000 chars)\n current_workaround (optional): How you're working around the gap\n priority (optional): low, medium (default), high\n\nReturns: confirmation that feedback was recorded.", "tags": [ "loper-feedback" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback_type": { "type": "string", "enum": [ "new_tool", "improvement", "bug", "workflow_gap" ], "description": "Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow)" }, "title": { "type": "string", "minLength": 5, "maxLength": 200, "description": "Concise title summarizing the feedback" }, "description": { "type": "string", "minLength": 20, "maxLength": 2000, "description": "What is needed and why" }, "current_workaround": { "type": "string", "maxLength": 1000, "description": "Current workaround, if any" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue)" }, "interface": { "type": "string", "enum": [ "MCP", "CLI" ], "default": "MCP", "description": "Interface the feedback originated from: MCP (default) or CLI" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "feedback_type", "title", "description", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "missing-tool": { "summary": "Missing tool", "value": { "feedback_type": "new_tool", "title": "Audience export", "description": "Need ability to list GA4 audiences and their definitions", "priority": "medium", "reason": "User asked to audit audience setup" } }, "workflow-gap": { "summary": "Workflow gap", "value": { "feedback_type": "workflow_gap", "title": "Multi-property reports", "description": "Cannot run one report across several GA4 properties at once", "current_workaround": "Call ga4_run_report per property and merge results", "reason": "User manages 12 properties" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_run_funnel_report": { "post": { "operationId": "ga4_run_funnel_report", "summary": "Run GA4 Funnel Report", "description": "Run an ordered, multi-step funnel (Data API v1alpha runFunnelReport) — the only way to measure step sequence, \"no intervening events\", and time-bounded steps. For non-sequential dimension x metric reporting use ga4_run_report instead.\n\nEach step matches either an event or a dimension value, or a depth-1 and_group/or_group of both — e.g. \"a page_view AND hostName = app.example.com\". Cross-domain journeys are expressed by filtering hostName per step.\n\nArgs:\n property_id (string, required): GA4 property ID (numeric) or full resource name.\n date_ranges (array, required): 1-4 ranges of { start_date, end_date, name? }. Use several to compare periods (e.g. week over week) in ONE call — this is the cheapest way to do it.\n steps (array, required): 2-10 ordered steps. Each is { name?, filter_expression, is_directly_followed_by?, within_duration_seconds? }.\n filter_expression is exactly one of:\n { funnel_event_filter: { event_name } }\n { funnel_field_filter: { field_name, string_filter | in_list_filter | numeric_filter | between_filter } }\n { and_group: { expressions: [...] } } | { or_group: { expressions: [...] } }\n { not_expression: }\n is_directly_followed_by: true means NO intervening events at all, not merely ordering.\n within_duration_seconds: complete this step within N seconds of the previous one.\n is_open_funnel (bool, optional): false (default) = users must enter at step 1; true = users may enter at any step. This changes the numbers a lot — the value actually used is echoed back as is_open_funnel.\n visualization_type (string, optional): STANDARD_FUNNEL (default) or TRENDED_FUNNEL. TRENDED_FUNNEL adds a date dimension to funnel_visualization, which carries activeUsers ONLY — completion and abandonment rates live in funnel_table.\n funnel_breakdown (object, optional): { breakdown_dimension, limit? } splits each step by a dimension. limit caps at 15. Adds a RESERVED_TOTAL row per step which is the across-all-values total, NOT a data row.\n funnel_next_action (object, optional): { next_action_dimension, limit? } — what users did next; appears in funnel_visualization. limit caps at 5.\n limit (number, optional): caps rows returned. There is no pagination and no total row count, so if you get back exactly that many rows the result may be silently truncated — raise the limit or narrow the funnel rather than assuming that is all the data. Defaults to 250; GA4 itself would return up to 10,000. Row count multiplies across steps x breakdown values x date ranges.\n return_property_quota (bool, optional).\n\nField names: funnel steps validate against GA4's exploration schema, which is NOT the same list ga4_get_metadata returns. Common valid dimensions include hostName, pagePath, sessionSource, sessionMedium, deviceCategory, country.\n\nReturns:\n property_id and date_ranges — echoed back, so multi-range rows (which GA4 labels date_range_0, date_range_1, ...) can be mapped to the windows you asked for.\n is_open_funnel — which semantics produced these numbers.\n funnel_table — { returned_rows, data } with funnelStepName, any breakdown dimension, activeUsers, funnelStepCompletionRate, funnelStepAbandonments, funnelStepAbandonmentRate.\n funnel_visualization — { returned_rows, data } with activeUsers only. Always present; for a STANDARD_FUNNEL with no next-action it is a subset of funnel_table, so read funnel_table for rates, plus date under TRENDED_FUNNEL.\n warnings — present when the funnel spans hostnames (GA4 stitches identity across domains only if cross-domain measurement was configured at collection time; it cannot be fixed at query time).\n\nNotes: steps no user reached are omitted entirely, so rows may be fewer than steps. There is no pagination — runFunnelReport has no offset.", "tags": [ "funnel-report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "property_id": { "type": "string", "minLength": 1, "description": "GA4 property ID (numeric) or full resource name." }, "date_ranges": { "type": "array", "items": { "type": "object", "properties": { "start_date": { "type": "string", "minLength": 1, "description": "YYYY-MM-DD or relative (e.g. 30daysAgo, yesterday)." }, "end_date": { "type": "string", "minLength": 1, "description": "YYYY-MM-DD or relative (e.g. today, yesterday)." }, "name": { "type": "string", "minLength": 1, "description": "Optional label; appears as a dimension value when multiple ranges are used." } }, "required": [ "start_date", "end_date" ], "additionalProperties": false }, "minItems": 1, "maxItems": 4, "description": "One to 4 date ranges. Use several to compare periods (e.g. week over week) in a single call." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Step label. Defaults to a 1-based index name." }, "is_directly_followed_by": { "type": "boolean", "description": "If true, this step must follow the previous one with NO intervening events at all (not merely in order). Default false." }, "within_duration_seconds": { "type": "number", "exclusiveMinimum": 0, "description": "Complete this step within N seconds of the prior step. Pass a number of seconds, not a duration string." }, "filter_expression": { "type": "object", "properties": { "and_group": { "type": "object", "properties": { "expressions": { "type": "array", "items": { "type": "object", "properties": { "funnel_event_filter": { "type": "object", "properties": { "event_name": { "type": "string", "minLength": 1, "description": "Event name, e.g. page_view, session_start, purchase." } }, "required": [ "event_name" ], "additionalProperties": false }, "funnel_field_filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "GA4 dimension API name, verbatim — e.g. hostName, pagePath, sessionSource. Funnel steps validate against the exploration schema, which is NOT the same list ga4_get_metadata returns." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "expressions" ], "additionalProperties": false, "description": "All of these conditions must hold." }, "or_group": { "type": "object", "properties": { "expressions": { "type": "array", "items": { "type": "object", "properties": { "funnel_event_filter": { "type": "object", "properties": { "event_name": { "type": "string", "minLength": 1, "description": "Event name, e.g. page_view, session_start, purchase." } }, "required": [ "event_name" ], "additionalProperties": false }, "funnel_field_filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "GA4 dimension API name, verbatim — e.g. hostName, pagePath, sessionSource. Funnel steps validate against the exploration schema, which is NOT the same list ga4_get_metadata returns." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "expressions" ], "additionalProperties": false, "description": "Any of these conditions must hold." }, "funnel_event_filter": { "type": "object", "properties": { "event_name": { "type": "string", "minLength": 1, "description": "Event name, e.g. page_view, session_start, purchase." } }, "required": [ "event_name" ], "additionalProperties": false }, "funnel_field_filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "GA4 dimension API name, verbatim — e.g. hostName, pagePath, sessionSource. Funnel steps validate against the exploration schema, which is NOT the same list ga4_get_metadata returns." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false }, "not_expression": { "type": "object", "properties": { "funnel_event_filter": { "type": "object", "properties": { "event_name": { "type": "string", "minLength": 1, "description": "Event name, e.g. page_view, session_start, purchase." } }, "required": [ "event_name" ], "additionalProperties": false }, "funnel_field_filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "GA4 dimension API name, verbatim — e.g. hostName, pagePath, sessionSource. Funnel steps validate against the exploration schema, which is NOT the same list ga4_get_metadata returns." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Negate a single condition." } }, "additionalProperties": false, "description": "What must match for a user to reach this step." } }, "required": [ "filter_expression" ], "additionalProperties": false }, "minItems": 2, "maxItems": 10, "description": "Ordered funnel steps (2-10)." }, "is_open_funnel": { "type": "boolean", "description": "Open funnel: users may enter at any step. Closed (default): users must enter at step 1. This changes the numbers substantially; the resolved value is echoed in the response." }, "visualization_type": { "type": "string", "enum": [ "STANDARD_FUNNEL", "TRENDED_FUNNEL" ], "description": "TRENDED_FUNNEL adds a date dimension to funnel_visualization (activeUsers only)." }, "funnel_breakdown": { "type": "object", "properties": { "breakdown_dimension": { "type": "string", "minLength": 1, "description": "Dimension to split each step by, verbatim — e.g. hostName, deviceCategory." }, "limit": { "type": "integer", "minimum": 1, "maximum": 15, "description": "Max distinct values (GA4 default 5, hard cap 15)." } }, "required": [ "breakdown_dimension" ], "additionalProperties": false }, "funnel_next_action": { "type": "object", "properties": { "next_action_dimension": { "type": "string", "minLength": 1, "description": "Dimension value the user attained after completing a step." }, "limit": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Max distinct next-action values (GA4 hard cap 5)." } }, "required": [ "next_action_dimension" ], "additionalProperties": false }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Max rows returned." }, "return_property_quota": { "type": "boolean", "description": "Include the property quota state in the response." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." } }, "required": [ "property_id", "date_ranges", "steps", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "three-step-signup-funnel": { "summary": "Three-step signup funnel", "value": { "property_id": "123456789", "date_ranges": [ { "start_date": "28daysAgo", "end_date": "yesterday" } ], "steps": [ { "name": "Visited site", "filter_expression": { "funnel_event_filter": { "event_name": "page_view" } } }, { "name": "Started signup", "filter_expression": { "funnel_event_filter": { "event_name": "sign_up_start" } } }, { "name": "Completed signup", "filter_expression": { "funnel_event_filter": { "event_name": "sign_up" } } } ], "reason": "Find which signup step loses the most users" } }, "cross-domain-funnel-with-per-step-hostnames": { "summary": "Cross-domain funnel with per-step hostnames", "value": { "property_id": "123456789", "date_ranges": [ { "start_date": "28daysAgo", "end_date": "yesterday" } ], "steps": [ { "name": "Marketing site", "filter_expression": { "and_group": { "expressions": [ { "funnel_event_filter": { "event_name": "page_view" } }, { "funnel_field_filter": { "field_name": "hostName", "string_filter": { "value": "example.com" } } } ] } } }, { "name": "App subdomain", "filter_expression": { "and_group": { "expressions": [ { "funnel_event_filter": { "event_name": "page_view" } }, { "funnel_field_filter": { "field_name": "hostName", "string_filter": { "value": "app.example.com" } } } ] } } } ], "funnel_breakdown": { "breakdown_dimension": "hostName", "limit": 5 }, "reason": "Measure the marketing-site to app hand-off" } }, "week-over-week-comparison-in-one-call": { "summary": "Week-over-week comparison in one call", "value": { "property_id": "123456789", "date_ranges": [ { "start_date": "14daysAgo", "end_date": "8daysAgo", "name": "prior_week" }, { "start_date": "7daysAgo", "end_date": "yesterday", "name": "last_week" } ], "steps": [ { "name": "Session", "filter_expression": { "funnel_event_filter": { "event_name": "session_start" } } }, { "name": "Purchase", "filter_expression": { "funnel_event_filter": { "event_name": "purchase" } } } ], "reason": "Compare purchase funnel across the last two weeks" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_get_metadata": { "post": { "operationId": "ga4_get_metadata", "summary": "Get GA4 Dimensions & Metrics", "description": "List the dimensions and metrics available on a GA4 property (including custom definitions), so ga4_run_report calls use valid API names instead of guessing.\n\nArgs:\n property_id (string, required): GA4 property ID (numeric) or full resource name.\n search (string, optional): Case-insensitive substring filter on API name / UI name (e.g. 'channel', 'revenue'). Omit to list everything.\n\nReturns:\n dimension_count, metric_count, and matching dimensions/metrics with api_name, ui_name, category, type (metrics), and custom flag.", "tags": [ "metadata" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "property_id": { "type": "string", "minLength": 1, "description": "GA4 property ID (numeric) or full resource name." }, "search": { "type": "string", "description": "Case-insensitive substring filter on API name / UI name (e.g. 'channel', 'revenue'). Omit to list everything." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." } }, "required": [ "property_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "search-revenue-metrics": { "summary": "Search revenue metrics", "value": { "property_id": "123456789", "search": "revenue", "reason": "Find valid revenue metric API names" } }, "list-everything": { "summary": "List everything", "value": { "property_id": "123456789", "reason": "Full dimension/metric inventory including custom definitions" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_ping": { "post": { "operationId": "ga4_ping", "summary": "Ping GA4 MCP Server", "description": "Health check. Returns server status, version, and timestamp.", "tags": [ "" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 100, "description": "Optional message to echo back" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "health-check": { "summary": "Health check", "value": { "reason": "Verify server is running" } }, "with-message": { "summary": "With message", "value": { "message": "hello", "reason": "Test connectivity" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_get_property_details": { "post": { "operationId": "ga4_get_property_details", "summary": "Get GA4 Property Details", "description": "Setup-health snapshot for one GA4 property: property info, data streams (with enhanced measurement settings for web streams), key events, Google Ads links, attribution settings, and data retention settings.\n\nSections that fail to load are returned with an error string instead of failing the whole call.\n\nArgs:\n property_id (string, required): GA4 property ID (numeric, e.g. '123456789') or full resource name ('properties/123456789').\n\nReturns:\n property, data_streams, key_events, google_ads_links, attribution_settings, data_retention_settings — each either the API payload or { error }.", "tags": [ "property-details" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "property_id": { "type": "string", "minLength": 1, "description": "GA4 property ID (numeric, e.g. '123456789') or full resource name ('properties/123456789')." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." } }, "required": [ "property_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "audit-property-setup": { "summary": "Audit property setup", "value": { "property_id": "123456789", "reason": "Check tracking and attribution configuration" } }, "full-resource-name": { "summary": "Full resource name", "value": { "property_id": "properties/123456789", "reason": "Verify key events on the property" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_run_report": { "post": { "operationId": "ga4_run_report", "summary": "Run GA4 Report", "description": "Run a GA4 report (Data API runReport): arbitrary dimensions × metrics over one or more date ranges, with filtering, ordering and acquisition cohorts.\n\nUse ga4_get_metadata first to look up valid dimension/metric API names. For ORDERED, step-by-step funnels use ga4_run_funnel_report instead — runReport cannot express sequence.\n\nArgs:\n property_id (string, required): GA4 property ID (numeric) or full resource name.\n dimensions (string[], optional): Up to 9 dimension API names (e.g. sessionDefaultChannelGroup, date).\n metrics (string[], required): 1-10 metric API names (e.g. sessions, totalUsers, keyEvents, purchaseRevenue).\n date_ranges (array, required unless cohort_spec is used): 1-4 ranges of { start_date, end_date, name? }. Dates are YYYY-MM-DD or relative (30daysAgo, yesterday, today).\n dimension_filter (object, optional): A filter expression — exactly one of:\n { filter: { field_name, string_filter | in_list_filter | numeric_filter | between_filter } }\n { and_group: { expressions: [ , ... ] } } // all must hold\n { or_group: { expressions: [ , ... ] } } // any must hold\n { not_expression: }\n where is { filter: {...} } or { not_expression: { filter: {...} } }.\n string_filter: { value, match_type?: EXACT|BEGINS_WITH|ENDS_WITH|CONTAINS|FULL_REGEXP|PARTIAL_REGEXP, case_sensitive? }\n Groups do not nest — one level of and/or over leaves.\n metric_filter (object, optional): Same shape, applied to metric values after aggregation (use numeric_filter / between_filter).\n cohort_spec (object, optional): Acquisition cohorts.\n { cohorts: [{ name?, date_range: { start_date, end_date } }], cohorts_range: { granularity: DAILY|WEEKLY|MONTHLY, start_offset?, end_offset } }\n Cohort reports REQUIRE the \"cohort\" dimension and must OMIT date_ranges — the cohort's own date_range defines the window. Pair with cohortNthDay/cohortNthWeek/cohortNthMonth and a metric such as cohortActiveUsers.\n order_by (object, optional): { type: 'metric'|'dimension', name, desc? }.\n limit (number, optional): Max rows, default 100, max 10000.\n offset (number, optional): Row offset for pagination.\n\nReturns:\n data — the rows, flattened as { dimension: value, metric: value } objects. Plus row_count (total rows before pagination) and returned_rows.\n For a single date range: metric_totals ({ metric: total }). For multiple date ranges: metric_totals_by_range ({ \"date_range_0\": { metric: total }, ... }) keyed by the dateRange dimension value (or the range's name).", "tags": [ "report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "property_id": { "type": "string", "minLength": 1, "description": "GA4 property ID (numeric) or full resource name." }, "dimensions": { "type": "array", "items": { "type": "string" }, "maxItems": 9, "description": "GA4 dimension API names, e.g. sessionDefaultChannelGroup, landingPagePlusQueryString, date. Use ga4_get_metadata for valid names. Cohort reports must include \"cohort\"." }, "metrics": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 10, "description": "GA4 metric API names, e.g. sessions, totalUsers, keyEvents, purchaseRevenue." }, "date_ranges": { "type": "array", "items": { "type": "object", "properties": { "start_date": { "type": "string", "minLength": 1, "description": "YYYY-MM-DD or relative (e.g. 30daysAgo, yesterday)." }, "end_date": { "type": "string", "minLength": 1, "description": "YYYY-MM-DD or relative (e.g. today, yesterday)." }, "name": { "type": "string", "description": "Optional label; appears as dateRange dimension when multiple ranges are used." } }, "required": [ "start_date", "end_date" ], "additionalProperties": false }, "minItems": 1, "maxItems": 4, "description": "One to 4 date ranges. Omit only for cohort reports, where cohort_spec defines the window." }, "dimension_filter": { "type": "object", "properties": { "and_group": { "type": "object", "properties": { "expressions": { "type": "array", "items": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false }, "not_expression": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "required": [ "filter" ], "additionalProperties": false } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "expressions" ], "additionalProperties": false, "description": "All of these conditions must hold." }, "or_group": { "type": "object", "properties": { "expressions": { "type": "array", "items": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false }, "not_expression": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "required": [ "filter" ], "additionalProperties": false } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "expressions" ], "additionalProperties": false, "description": "Any of these conditions must hold." }, "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false, "description": "A single condition." }, "not_expression": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false }, "not_expression": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "required": [ "filter" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Negate a single condition." } }, "additionalProperties": false, "description": "Filter on dimension values. One of and_group / or_group / filter / not_expression." }, "metric_filter": { "type": "object", "properties": { "and_group": { "type": "object", "properties": { "expressions": { "type": "array", "items": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false }, "not_expression": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "required": [ "filter" ], "additionalProperties": false } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "expressions" ], "additionalProperties": false, "description": "All of these conditions must hold." }, "or_group": { "type": "object", "properties": { "expressions": { "type": "array", "items": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false }, "not_expression": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "required": [ "filter" ], "additionalProperties": false } }, "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "expressions" ], "additionalProperties": false, "description": "Any of these conditions must hold." }, "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false, "description": "A single condition." }, "not_expression": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false }, "not_expression": { "type": "object", "properties": { "filter": { "type": "object", "properties": { "field_name": { "type": "string", "minLength": 1, "description": "Dimension or metric API name, verbatim (e.g. hostName, pagePath, sessions)." }, "string_filter": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "description": "Value to match." }, "match_type": { "type": "string", "enum": [ "EXACT", "BEGINS_WITH", "ENDS_WITH", "CONTAINS", "FULL_REGEXP", "PARTIAL_REGEXP" ], "description": "Match type (default EXACT)." }, "case_sensitive": { "type": "boolean", "description": "Case-sensitive matching (GA4 default is false)." } }, "required": [ "value" ], "additionalProperties": false }, "in_list_filter": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Match any of these values." }, "case_sensitive": { "type": "boolean" } }, "required": [ "values" ], "additionalProperties": false }, "numeric_filter": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "EQUAL", "LESS_THAN", "LESS_THAN_OR_EQUAL", "GREATER_THAN", "GREATER_THAN_OR_EQUAL" ] }, "value": { "type": "number", "description": "Numeric value to compare against." } }, "required": [ "operation", "value" ], "additionalProperties": false }, "between_filter": { "type": "object", "properties": { "from_value": { "type": "number" }, "to_value": { "type": "number" } }, "required": [ "from_value", "to_value" ], "additionalProperties": false } }, "required": [ "field_name" ], "additionalProperties": false } }, "required": [ "filter" ], "additionalProperties": false } }, "additionalProperties": false, "description": "Negate a single condition." } }, "additionalProperties": false, "description": "Filter on metric values (applied after aggregation). Same shape as dimension_filter; use numeric_filter or between_filter." }, "cohort_spec": { "type": "object", "properties": { "cohorts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Cohort label, returned as the `cohort` dimension value." }, "dimension": { "type": "string", "const": "firstSessionDate", "default": "firstSessionDate", "description": "Only firstSessionDate is supported by GA4." }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "minLength": 1 }, "end_date": { "type": "string", "minLength": 1 } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "The acquisition window that defines this cohort." } }, "required": [ "date_range" ], "additionalProperties": false }, "minItems": 1, "maxItems": 4 }, "cohorts_range": { "type": "object", "properties": { "granularity": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ] }, "start_offset": { "type": "integer", "description": "First period to report, relative to the cohort (default 0)." }, "end_offset": { "type": "integer", "description": "Last period to report, relative to the cohort." } }, "required": [ "granularity", "end_offset" ], "additionalProperties": false, "description": "How far forward to follow each cohort." } }, "required": [ "cohorts", "cohorts_range" ], "additionalProperties": false, "description": "Acquisition-cohort report. Requires the \"cohort\" dimension; pair with cohortActiveUsers or cohortTotalUsers, and cohortNthDay/Week/Month to see periods." }, "order_by": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "metric", "dimension" ] }, "name": { "type": "string", "minLength": 1, "description": "Metric or dimension API name to order by." }, "desc": { "type": "boolean", "description": "Descending (default true for metrics, false for dimensions)." } }, "required": [ "type", "name" ], "additionalProperties": false }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Max rows (default 100). Range: 1-10000." }, "offset": { "type": "integer", "minimum": 0, "description": "Row offset for pagination." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." } }, "required": [ "property_id", "metrics", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "sessions-by-channel-30-days": { "summary": "Sessions by channel (30 days)", "value": { "property_id": "123456789", "dimensions": [ "sessionDefaultChannelGroup" ], "metrics": [ "sessions", "totalUsers", "keyEvents" ], "date_ranges": [ { "start_date": "30daysAgo", "end_date": "yesterday" } ], "reason": "Channel mix overview for the last 30 days" } }, "landing-page-revenue-filtered": { "summary": "Landing page revenue, filtered", "value": { "property_id": "123456789", "dimensions": [ "landingPagePlusQueryString" ], "metrics": [ "sessions", "purchaseRevenue" ], "date_ranges": [ { "start_date": "2024-01-01", "end_date": "2024-01-31" } ], "dimension_filter": { "filter": { "field_name": "sessionDefaultChannelGroup", "string_filter": { "value": "Paid Search" } } }, "order_by": { "type": "metric", "name": "purchaseRevenue" }, "limit": 25, "reason": "Top paid-search landing pages by revenue" } }, "weekly-acquisition-cohorts": { "summary": "Weekly acquisition cohorts", "value": { "property_id": "123456789", "dimensions": [ "cohort", "cohortNthWeek" ], "metrics": [ "cohortActiveUsers" ], "cohort_spec": { "cohorts": [ { "name": "week_of_jul_6", "date_range": { "start_date": "2026-07-06", "end_date": "2026-07-12" } } ], "cohorts_range": { "granularity": "WEEKLY", "start_offset": 0, "end_offset": 3 } }, "reason": "Retention of the users acquired in the week of Jul 6" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/ga4_run_realtime_report": { "post": { "operationId": "ga4_run_realtime_report", "summary": "Run GA4 Realtime Report", "description": "Run a GA4 realtime report (last 30 minutes of events). Primary use: verifying tags and key events fire after a tracking change, without waiting for standard processing lag.\n\nArgs:\n property_id (string, required): GA4 property ID (numeric) or full resource name.\n dimensions (string[], optional): Up to 9 realtime dimension API names (e.g. eventName, unifiedScreenName, country, deviceCategory).\n metrics (string[], required): 1-10 realtime metric API names (e.g. activeUsers, eventCount, keyEvents).\n limit (number, optional): Max rows, default 50.\n\nReturns:\n data — the rows, flattened as { dimension: value, metric: value } objects — plus row_count.", "tags": [ "realtime-report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "property_id": { "type": "string", "minLength": 1, "description": "GA4 property ID (numeric) or full resource name." }, "dimensions": { "type": "array", "items": { "type": "string" }, "maxItems": 9, "description": "Realtime dimension API names, e.g. eventName, unifiedScreenName, country, deviceCategory." }, "metrics": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 10, "description": "Realtime metric API names, e.g. activeUsers, eventCount, keyEvents." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Max rows (default 50)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" }, "connection_id": { "type": "string", "format": "uuid", "description": "Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call _list_connections to discover available connection IDs." } }, "required": [ "property_id", "metrics", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "verify-events-firing": { "summary": "Verify events firing", "value": { "property_id": "123456789", "dimensions": [ "eventName" ], "metrics": [ "eventCount" ], "reason": "Confirm tags fire after a tracking change" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase JWT or hpk_live_... API key" } }, "schemas": { "McpToolResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "resource_link" ] }, "text": { "type": "string" } } } }, "structuredContent": { "type": "object", "additionalProperties": true }, "isError": { "type": "boolean" } } }, "McpError": { "type": "object", "properties": { "isError": { "type": "boolean", "const": true }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } }, "RestError": { "type": "object", "description": "Error response from REST tool endpoints (mapped from JSON-RPC error codes)", "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "integer", "description": "JSON-RPC error code" }, "data": { "description": "Additional error context" } }, "required": [ "error", "code" ] }, "ToolList": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true } } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "discovery", "description": "Tool discovery and introspection" }, { "name": "", "description": " tools" }, { "name": "-account-summaries", "description": "-account-summaries tools" }, { "name": "-connections", "description": "-connections tools" }, { "name": "are-connection", "description": "Are-connection tools" }, { "name": "default-connection", "description": "Default-connection tools" }, { "name": "e-connection", "description": "E-connection tools" }, { "name": "funnel-report", "description": "Funnel-report tools" }, { "name": "k-auth-status", "description": "K-auth-status tools" }, { "name": "ke-connection", "description": "Ke-connection tools" }, { "name": "loper-feedback", "description": "Loper-feedback tools" }, { "name": "me-connection", "description": "Me-connection tools" }, { "name": "metadata", "description": "Metadata tools" }, { "name": "property-details", "description": "Property-details tools" }, { "name": "realtime-report", "description": "Realtime-report tools" }, { "name": "report", "description": "Report tools" } ] }