--- title: Google Analytics (GA4) connector tools slug: agent-platform/docs/google-analytics-ga4-connector-tools docTags: createdAt: 2026-08-12T15:37:06.000Z --- The Google Analytics 4 (GA4) connector tools in Agent Platform let you query and visualize the web traffic data tracked in GA4 directly from Mark. Use them to monitor live visitors, compare conversion funnels, or break down traffic sources without leaving Mark. To enable the tools, an Optimizely Connect Platform (OCP) administrator installs the app, authenticates it against GA4, and registers it with Mark. When registration is complete, you authenticate to Mark individually so the GA4 connector tools return only the data your Google account is permitted to view. :::hint{type="warning"} **Important** If you previously used a service account or Application Default Credentials (ADC), your existing installation continues to work. To migrate, uninstall the Google Analytics 4 Mark app in the OCP **App Directory** and complete the steps in this article. The new flow uses Google OAuth and supports multiple GA4 properties. ::: ## Install Google Analytics 4 Mark In the OCP **App Directory**, complete the following steps: 1. Click **Google Analytics 4 Mark**. ![Screenshot of the OCP App Directory where Google Analytics is entered in the search field and two apps display in the results](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/4NCtJrH7NUmrrkTCGpaZ5_mark-connector-google-analytics-app-directory0.png) 2. Click **Install App**. ## Configure the Google Analytics settings After installing the GA4 app, configure it in OCP. The configuration has three main parts that most organizations follow: add the GA4 properties Mark queries, optionally set a default domain filter, and register the connector tools with your Mark instance. Only follow the [Override the OAuth provider](docId:7fZ7-gpdPyJMT0jSx2cPh) section if your organization requires it. ### Override the OAuth provider (optional) This section is to manage your own OAuth provider and is not common. Most administrators can skip this section. If your organization manages its own OAuth provider, see [Configure instance-level Mark OAuth](docId:7fZ7-gpdPyJMT0jSx2cPh). ### Configure GA4 properties Add the GA4 properties you want Mark to access. You can add multiple properties and assign nicknames for easy identification. 1. Go to the **Settings** tab. 2. Expand the **GA4 Properties** section. 3. (Optional) Enter a **Nickname** for the property. This makes it easier to find the property later. 4. Enter the **GA4 Property ID**. 5. Click **Add Property**. ![Screenshot of the GA4 app settings where the Google Analytics for Mark section is expanded and the GA4 property settings include an Add property option](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/gVjcqDPMpPFJAkS78dFK0_mark-connector-google-analytics-ga4-property-settings0.png) 6. Repeat steps 3–5 for each property you want to add. ### Add a default filter (optional) After adding your GA4 properties, you can optionally limit the data Mark queries to a single domain. Designate a default domain for queries when your GA4 property tracks multiple hostnames. Mark applies the default to every query that does not name a domain explicitly, and you can still target other domains from a prompt. Leave the field empty to query all tracked hostnames. To set a default, complete the following: 1. Click **Settings > Default Filter**. 2. Enter only the hostname in the **Hostname Filter** field. Do not include a protocol (for example, omit `https://`). For example, enter *www\.optimizely.com.* 3. Click **Save Filter**. ![Screenshot of the GA4 app settings where the Global filter settings section is expanded and Save filter stores the filter](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/BZTeBcwsVuSrKV4OE9y3w_mark-connector-google-analytics-save-global-filter-settings0.png) Next, [register the GA4 connector tools in OCP](docId:7fZ7-gpdPyJMT0jSx2cPh). ### Register the GA4 connector tools in OCP After you [install Google Analytics 4 Mark](docId:7fZ7-gpdPyJMT0jSx2cPh) and [configure the Google Analytics settings](docId:7fZ7-gpdPyJMT0jSx2cPh), complete the following steps in OCP to register it with your Mark instance: 1. Click **Settings > Add to Mark**. 2. Click **Add to Mark** for the Mark account where you want to host the GA4 connector tools. ![Screenshot of the GA4 app settings where the Add to Mark section is expanded and Add to Mark is in the Actions column](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/RNFCseknPdP8c2IG0E_yn_mark-connector-google-analytics-add-to-mark0.png) Click **Remove from Mark** to disconnect the tools from your Mark account. ## Authenticate with Google After an OCP administrator [installs the Google Analytics 4 Mark app in OCP](docId:7fZ7-gpdPyJMT0jSx2cPh) and [registers the GA4 connector tools](docId:7fZ7-gpdPyJMT0jSx2cPh), log in to Google from Mark to access your GA4 data. The connector tools authenticate each Mark user individually, so you only see GA4 data your Google account is already permitted to view. To authenticate, complete the following steps in Mark: 1. Go to **Connectors > Connectors**. 2. Click **Connect** on the **Google Analytics 4** tile. 3. Log in to Google. After you authenticate, the GA4 connector tools become available in [Mark chat](docId\:dtNBEttEGVvkhNkwNypLM), [agents](docId\:w7MSVijPnuFqu4nXDo_bq), and [workflows](docId:2HD0fUsIsfdek516VtN9l). ## GA4 connector tools After an OCP administrator installs and registers the GA4 connector tools and you [authenticate with Google in Mark](docId:7fZ7-gpdPyJMT0jSx2cPh), you can call the following tools in Mark. The GA4 connector tools are Mark-native tools that translate your prompts into GA4 Data API queries. Use them in chat, agents, and workflows to monitor live traffic, build funnel reports, look up dimensions and metrics, and generate historical reports without leaving Mark. Click a tool's name to expand it and learn when to use it, its required and optional parameters, and example prompts for calling the tool. If you do not provide a required parameter, Mark prompts you for it. :::ExpandableHeading ### `get_custom_dimensions_and_metrics` – Lists custom dimensions and metrics configured in GA4. These user-defined data points expand the standard GA4 offerings, letting you tailor your analysis. See [\[GA4\] About custom dimensions and metrics](https://support.google.com/analytics/answer/14240153?hl=en) in the Google documentation. - **When to use** - See a comprehensive list of all custom dimensions and metrics available in GA4. - Understand what specific custom data points you can use for reporting and analysis. - Prepare to build custom reports or queries that involve your unique analytics data. - **Parameters** - None - **Example prompts** - *What custom dimensions and metrics do I have in Google Analytics?* - *List all available custom dimensions and metrics.* - *Show me my custom analytics fields.* ::: :::ExpandableHeading ### `get_dimensions` – Lists standard GA4 dimensions available for reporting. Dimensions are descriptive attributes of user activity (for example, `country`, `deviceCategory`, `browser`, `pagePath`, and `trafficSource`) that you can use to categorize and segment your data in reports. See [Analytics dimensions and metrics](https://support.google.com/analytics/table/13948007?hl=en) in the Google documentation. - **When to use** - See a list of all standard dimensions available in Google Analytics. - Understand what attributes you can use to segment or filter your analytics data. - Prepare to build reports or queries that require standard dimensions. - **Parameters** - None - **Example prompts** - *What are the available dimensions in Google Analytics?* - *List all standard dimensions I can use for reporting.* - *Show me the different ways I can break down my user data.* ::: :::ExpandableHeading ### `get_metrics` – Lists standard GA4 metrics available for reporting. Metrics are quantitative measurements (for example, `activeUsers`, `eventCount`, `conversions`, and `revenue`) representing the numerical values you want to analyze and aggregate in your reports. See [Analytics dimensions and metrics](https://support.google.com/analytics/table/13948007?hl=en) in the Google documentation. - **When to use** - See a list of all standard metrics available in Google Analytics. - Understand what quantitative data points you can use for analysis and reporting. - Prepare to build reports or queries that require standard metrics. - **Parameters** - None - **Example prompts** - *What metrics can I use in Google Analytics?* - *List all standard metrics for my reports.* - *Show me the quantitative data I can analyze.* ::: :::ExpandableHeading ### `run_funnel_report` – Runs a funnel report to visualize user journey steps and conversion rates. Use this tool to analyze how users progress through a defined sequence of steps and identify where they exit the flow. - **When to use** - Analyze how users move through a specific sequence of actions, such as a checkout or sign-up flow. - Identify drop-off points between steps in a user journey. - Compare funnel performance across devices, traffic sources, or other dimensions. - Measure conversion rates between key events, such as page views to purchases. - Understand what users do after completing or abandoning a funnel step. - **Parameters** - `dateRanges` – The time periods for the report. Accepts up to four date ranges. Supports relative values such as `30daysAgo` or absolute dates such as `2025-01-01`. - `funnel` – Defines the funnel steps. Each step requires a `name` and a `filterExpression`. Supports event filters (`funnelEventFilter`) and field filters (`funnelFieldFilter`), along with `orGroup`, `andGroup`, and `notExpression` combinations. Optional step properties include `isDirectlyFollowedBy` and `withinDurationFromPriorStep`. - (Optional) `funnelBreakdown` – Breaks down funnel results by a dimension, such as `deviceCategory` or `country`. Accepts an optional `limit` value (default is 5). - (Optional) `funnelNextAction` – Analyzes what users do after completing or abandoning a funnel step. Accepts a dimension such as `eventName` or `pagePath`, and an optional `limit`. - (Optional) `segments` – Defines user segments to compare funnel performance, such as mobile versus desktop users. - (Optional) `dimensionFilter` – Filters the entire funnel by a dimension value, such as country or device category. - (Optional) `limit` – Maximum number of rows to return. Accepts values between 1 and 100,000. Defaults to 10. - (Optional) `returnPropertyQuota` – Set to `true` to include Google Analytics property quota usage in the response. - **Example prompts** - *Show me a funnel from page view to purchase over the last 30 days.* - *Analyze the checkout funnel (add to cart, begin checkout, and purchase) broken down by device type.* - *Where are users dropping off in the sign-up flow this month?* - *Compare the purchase funnel between mobile and desktop users.* - *Show me a funnel for organic visitors from first visit to session start to purchase.* - *What do users do after abandoning the checkout step?* ::: :::ExpandableHeading ### `run_realtime_report` – Returns immediate, up-to-the-minute GA4 insights into user activity for the past 30 minutes. Use this tool to monitor live traffic, validate analytics configurations, and observe immediate impacts. See [\[GA4\] Realtime report](https://support.google.com/analytics/answer/9271392) in the Google documentation. - **When to use** - See who is on your site right now, where they are coming from, and what they are doing. - Check if new events or tracking configurations are working correctly. - Query active users, events, traffic sources, device breakdowns, and conversions as they happen. - **Parameters** - `dimensions` – The attributes of user activity you want to see in your report (for example, `country`, `deviceCategory`, or `eventName`). You can find available standard dimensions using the `get_dimensions` tool. - `metrics` – The quantitative measurements you want to analyze (for example, `activeUsers`, `eventCount`, or `sessions`). You can find available standard metrics using the `get_metrics` tool. - (Optional) `dimensionFilter` – Filters the report by dimension values (for example, a specific country or device category). - (Optional) `metricsFilter` – Filters the report by metric value (for example, sessions greater than 100). - (Optional) `limit` – The maximum number of rows to return in your report. Defaults to 10,000 when not specified. - (Optional) `offset` – The starting row for your report. Use it with `limit` to paginate through large reports. - (Optional) `currencyCode` – The currency code to use for currency values in the report (for example, `USD`, `EUR`). When this field is empty, the report uses the property's default currency. - (Optional) `returnPropertyQuota` – Set to `true` to include Google Analytics property quota usage in the response. - (Optional) `orderBys` – A list of objects that sort the report by dimensions or metrics in ascending or descending order. - **Example prompts** - *Show me the current active users on my site.* - *What countries are my active users coming from right now?* - *How many sessions are active in the last 30 minutes, broken down by device type?* - *Are there any conversions happening in real-time?* - *Show me active users and their device categories, but only for users from the United States.* ::: ::::ExpandableHeading ### `run_report` – Generates historical GA4 reports across properties, including user demographics, traffic sources, engagement, conversions, ecommerce performance, and time-based trends. - **When to use** - Examine user demographics, where they come from, and how they interact with your content. - Monitor conversions, revenue, event counts, and other important metrics. - Break down your reports by various dimensions like country, device, or traffic source. - See how your metrics and dimensions change over time. - **Parameters** - `dateRanges` (list of objects) – The time periods for your report. Each range needs a `startDate` and `endDate`, plus an optional `name`. Dates can be absolute (for example, `2025-01-01`) or relative (for example, `yesterday`, `30daysAgo`, `today`). :::hint{type="info"} **Note** If you use multiple date ranges, do not include `dateRange` in your `dimensions` list because Google Analytics handles this automatically. ::: :::Paragraph{listStyleType="disc" indent="2"} `dimensions` – List of attributes you want to include in your report to break down your data (for example, `country`, `deviceCategory`, or `eventName`). You can find available standard dimensions using the `get_dimensions` tool, and custom dimensions using `get_custom_dimensions_and_metrics`. ::: :::Paragraph{listStyleType="disc" indent="2"} `metrics` – List of the quantitative measurements you want to analyze (for example, `activeUsers`, `sessions`, `conversions`, or `totalRevenue`). You can find available standard metrics using the `get_metrics` tool, and custom metrics using `get_custom_dimensions_and_metrics`. ::: :::Paragraph{listStyleType="disc" indent="2"} (Optional) `dimensionFilter` – Filters the report by dimension value using a structured filter expression (for example, a specific country, device, or event). ::: :::Paragraph{listStyleType="disc" indent="2"} (Optional) `metricsFilter` – Filters the report by metric value using a structured filter expression (for example, sessions greater than 100 or revenue in a range). ::: :::Paragraph{listStyleType="disc" indent="2"} (Optional) `limit` – The maximum number of rows you want to see in your report. Use it to manage large datasets. ::: :::Paragraph{listStyleType="disc" indent="2"} (Optional) `offset` – The starting row for your report. Use it with `limit` to paginate through large reports. ::: :::Paragraph{listStyleType="disc" indent="2"} (Optional) `currencyCode` – The currency code (for example, `USD` or `EUR`) to use for any currency values in the report. If you leave this empty, the report uses your property's default currency. ::: :::Paragraph{listStyleType="disc" indent="2"} (Optional) `returnPropertyQuota` – Set to `true` to include Google Analytics property quota usage in the response. ::: :::Paragraph{listStyleType="disc" indent="2"} (Optional) `orderBys` – Sorts the report by dimensions or metrics in ascending or descending order (for example, sort by `sessions` descending). ::: - **Example prompts** - *Show me the active users and sessions for the last 30 days.* - *What were the top 5 countries for conversions last month?* - *How many purchases did we have in Q3 2024, broken down by device category?* - *Compare the bounce rate and average session duration between July and August 2025.* - *Give me a report on event counts for* `add_to_cart` *and* `purchase` *events, but only for users coming from* `google / cpc`*.* :::: ## Configure instance-level Mark OAuth :::hint{type="info"} **Note** Configure this *only* if your organization manages its own OAuth provider. Most administrators can skip this section. ::: In the OCP **App Directory**, complete the following steps: 1. Click the **Settings** tab of the Google Analytics 4 Mark tool. 2. Expand the **Google Analytics Settings** section. 3. Toggle **Instance level Mark OAuth** on if you want to use a custom Google Analytics authentication provider connection. 4. Enter your **Google Analytics Auth Provider ID**. 5. Click **Save Settings**. ![Screenshot of the GA4 app settings where the Google Analytics Settings section is expanded and Save Settings stores the settings](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/sF8_o55_Edzz3EPccR5qK_mark-connector-google-analytics-settings0.png) ## Troubleshoot registration configuration issues `Already registered from another OCP account` **error in Mark when registering the GA4 connector tools.** Mark returns this error when the GA4 tools are already registered from another OCP instance, or when the previous registration was not removed before the OCP app was uninstalled. - If the tools were registered from another OCP instance, an OCP administrator opens that OCP instance, goes to **Google Analytics 4 Mark > Settings > Add to Mark**, and clicks **Remove from Mark**. ![Screenshot of the GA4 app settings where the Add to Mark section is expanded and Remove from Mark is in the Actions column](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/azny1urV3gGThm9ZDlQlV_mark-connector-google-analytics-remove-from-mark0.png) - If the previous registration was not removed, a Mark administrator goes to **Opal > Tools > Registries > GA4**, clicks **More** (**…**) for the GA4 entry, and clicks **Delete**. ![Screenshot of Connectors where the Actions menu of the Google Analytics connector is open and Delete is an option](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/UzPYQxap4eWA9T62W1fvM_mark-connector-google-analytics-registries-ga40.png) :::hint{type="info"} **Note** If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See [Turn generative AI off across Optimizely applications](docId\:X5U0kKD2azV5cIdNqwGNj). :::