---
title: Google Tag Manager connector tools
slug: agent-platform/docs/google-tag-manager-connector-tools
createdAt: 2026-09-29T00:00:00.000Z
---

The Google Tag Manager connector tools in Mark (Optimizely Agent Platform) let you read and write your Tag Manager containers in plain English through the official Tag Manager API v2. Use them to list the accounts, containers, and workspaces you can access, audit and manage tags, triggers, and variables, and freeze and publish container versions, all without opening Google Tag Manager. Each Mark user authenticates with their own Google account, so every action is attributed to whoever is chatting rather than to a shared service account.

First, a [Mark administrator](https://docs.optimizely.com/agent-platform/docs/get-started-with-agent-platform-for-administrators) must configure the Google Tag Manager connector in Mark (Optimizely Agent Platform). On the **Connectors** page, click **Configure** on the Google Tag Manager tile and complete the steps. After the administrator configures the connector, individual Mark [users](https://docs.optimizely.com/agent-platform/docs/get-started-with-agent-platform-for-users) and [agent builders](https://docs.optimizely.com/agent-platform/docs/get-started-with-agent-platform-for-agent-builders) click **Connect** on the Google Tag Manager tile and log in to Google Tag Manager to access their information from Mark. Administrators only need to configure the Google Tag Manager connector once.

## Use cases

The following use cases show how you can use Google Tag Manager connector tools in Mark to audit, extend, and troubleshoot tag configurations without opening Google Tag Manager.

### Audit a container for dead weight

Containers accumulate paused tags, duplicate tag types, and orphaned configurations over time. Use `gtm_list_tags` and `gtm_list_triggers` to list every tag in a container and flag the ones that are paused, have no firing trigger, or duplicate another tag's type and configuration. This surfaces dead weight and double-firing tags that quietly inflate your GA4 numbers.

**Example** – *List every tag in my main container and flag the ones that are paused, have no firing trigger, or duplicate another tag's type and configuration.*

### Map conversion tags to their triggers

A conversion tag that fires on **All Pages** instead of a specific action is a common cause of an inflated conversion rate. Use `gtm_list_tags` and `gtm_list_triggers` to see every tag that fires a GA4 conversion event, which trigger fires it, and which ones fire on **All Pages** rather than a specific action. Review this before you trust a GA4 report.

**Example** – *Show me every tag that fires a GA4 conversion event and which trigger fires it. Tell me which ones fire on All Pages rather than a specific action.*

### Add scroll and engagement tracking

Scroll depth and engagement triggers give you visibility into content engagement that many containers do not track by default. Use `gtm_create_trigger` and `gtm_create_tag` to create scroll depth triggers and a GA4 event tag for each, and stage the changes in a workspace without publishing them.

**Example** – *Create a 50% and 90% scroll depth trigger for my blog pages only, and a GA4 event tag for each. Stage it in a workspace — don't publish.*

### Fix single-page app pageview tracking

A single-page app can silently undercount pageviews, because the full page load event that GA4 relies on never repeats after the initial load. Use `gtm_get_tag` to check whether a GA4 configuration tag fires on a pageview trigger, and use `gtm_create_trigger` and `gtm_update_tag` to switch it to a `historyChange` trigger so route changes get tracked.

**Example** – *My site is a single-page app. Check whether my GA4 config tag fires on a pageview trigger, and if so, create a historyChange trigger instead so route changes get tracked.*

### Review container release history

Reviewing what changed between container versions helps you confirm a rollout landed as expected or diagnose a regression after a publish. Use `gtm_list_versions` to list recent container versions with their tag counts, and compare the current live version against the one before it.

**Example** – *List the last 10 container versions with their tag counts, and tell me what changed between the current live version and the one before it.*

## Connect Mark with Google Tag Manager

Complete the following steps to enable the Google Tag Manager tools in Mark.

### Configure the Google Tag Manager connector

When you click **Configure**, Mark opens the **Configure Google Tag Manager** dialog. If the connector is not installed yet, an **Install** modal displays first. This connector needs no extra authentication details, so the dialog has a single **Tools** step, where you choose which tools to enable.

As a Mark administrator, complete the following steps:

1. Go to **Connectors**.
2. (Optional) Enter *Google Tag Manager* in the **Enter name** field, or use the **Provider**, **Active Status**, and **Provider Type** filters to find the connector.
3. Click **Configure** on the **Google Tag Manager** tile.

   :::hint{type="info"}
   **Note**
   The **Install** modal only displays if the connector is not installed yet. Installing adds the connector to your organization and makes its tools available. You install a connector once, for everyone.
   :::
4. On the **Tools** step, select the tools that users can use by default, and then click **Save**. Each tool displays its type, such as **Read**, **Create**, **Update**, or **Delete**. Use the search field to find a tool, or click **Deselect all** to clear the selection. Tools that you do not select still display on the connector's **Tools** tab, but remain disabled until you select them. The step lists the 17 available Google Tag Manager tools. Each tool has its own checkbox, so you can turn off a specific tool, such as a write tool like `gtm_delete_tag`, without disabling the rest of the connector.

After you configure the connector, the **Google Tag Manager** tile displays **Connect** for everyone in your organization.

After you complete the steps in this section, each Mark user in your account can follow the steps in [Authenticate with Google Tag Manager](https://docs.optimizely.com/agent-platform/docs/google-tag-manager-connector-tools#authenticate-with-google-tag-manager) to connect their own Google Tag Manager login.

## Authenticate with Google Tag Manager

After an administrator [connects Mark with Google Tag Manager](https://docs.optimizely.com/agent-platform/docs/google-tag-manager-connector-tools#connect-with-google-tag-manager), log in from Mark to access your data. The Google Tag Manager connector tools use per-user authentication, so you can only access data you have permission to view in Google Tag Manager.

If the tile displays **Contact Admin** instead of **Connect**, an administrator has not configured the connector yet. Click **Contact Admin** to send them a request, which displays in their **Notifications**.

To authenticate, complete the following steps in Mark:

1. Go to **Tools > Connectors**.
2. Click **Connect** on the **Google Tag Manager** connector tools.

   ![Screenshot of Connectors where the Google Tag Manager card shows a Connect option](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/P7k4J8ZJqEc6A8sstlSdt_mark-connector-google-tag-manager-connect0.png)
3. Log in to Google in the window Optimizely displays.

After you connect to Google, the Google Tag Manager connector tools become available in [Mark chat](https://docs.optimizely.com/agent-platform/docs/access-and-explore-mark-chat), [agents](https://docs.optimizely.com/agent-platform/docs/agent-overview), and [workflows](https://docs.optimizely.com/agent-platform/docs/workflow-agents-overview).

## Google Tag Manager connector tools

After an administrator configures the Google Tag Manager connector and you log in using [Authenticate with Google Tag Manager](https://docs.optimizely.com/agent-platform/docs/google-tag-manager-connector-tools#authenticate-with-google-tag-manager), you can call the following tools in Mark. Select a tool to expand it and review when to use it, its parameters, and example prompts. If you do not provide a required parameter, Mark prompts you for it.

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.

### Account, container, and workspace access

Use these tools to discover the accounts, containers, and workspaces your connected Google account can access. Run these first, because almost every other Google Tag Manager tool needs an ID one of these tools returns.

:::ExpandableHeading
### `gtm_list_accounts`

Lists the Google Tag Manager accounts the connected Google account can access.

- **When to use**
  - Start any Google Tag Manager request when you do not yet know the `account_id` to pass to other tools.
  - Confirm which Tag Manager accounts your Google account can access before you query a specific container.
  - Discover accounts you manage on behalf of a client or another team.
- **Parameters**
  - None
- **Example prompts**
  - *List the Google Tag Manager accounts I can access.*
  - *What Tag Manager accounts is my Google account connected to?*
  - *Show me the account ID for my Tag Manager account.*
:::

:::ExpandableHeading
### `gtm_list_containers`

Lists the containers in a Google Tag Manager account. A container is a single site or app property, and its public ID is the `GTM-XXXXXX` identifier you paste into a page.

- **When to use**
  - Find the `container_id` for a specific site or app before you list its workspaces, tags, or triggers.
  - Confirm the public `GTM-XXXXXX` ID for a container you are about to embed on a page.
  - Review every container registered under an account.
- **Parameters**
  - `account_id` – The Google Tag Manager account to list containers for. Get this from `gtm_list_accounts`.
- **Example prompts**
  - *List the containers in my main Tag Manager account.*
  - *What is the public container ID for my marketing site?*
  - *Show me every container under account 123456.*
:::

:::ExpandableHeading
### `gtm_list_workspaces`

Lists the workspaces in a container. Every edit to a tag, trigger, or variable happens inside a workspace, and the default workspace is usually named **Default Workspace**.

- **When to use**
  - Find the `workspace_id` you need before you create, read, update, or delete a tag, trigger, or variable.
  - Confirm which workspaces are open in a container before you stage new changes.
  - Check whether a colleague already created a workspace for a pending change.
- **Parameters**
  - `container_id` – The container to list workspaces for. Get this from `gtm_list_containers`.
- **Example prompts**
  - *List the workspaces in my main container.*
  - *What is the workspace ID for the Default Workspace in container 7654321?*
  - *Show me every open workspace in my container.*
:::

### Tags

Use these tools to list, read, create, update, and delete the tags that fire scripts and pixels on your site or app, such as GA4 event tags, custom HTML tags, and conversion linkers.

:::ExpandableHeading
### `gtm_list_tags`

Lists all tags in a workspace. Returns each tag's ID, name, type, firing triggers, and paused state.

- **When to use**
  - Audit a container for paused tags, tags with no firing trigger, or tags that duplicate another tag's type and configuration.
  - Get an overview of every tag configured in a workspace before you make a change.
  - Find the `tag_id` for a specific tag before you read or update it.
- **Parameters**
  - `workspace_id` – The workspace to list tags for. Get this from `gtm_list_workspaces`.
- **Example prompts**
  - *List every tag in my main container and flag the ones that are paused, have no firing trigger, or duplicate another tag's type and configuration.*
  - *Show me every tag that fires a GA4 conversion event and which trigger fires it.*
  - *Which tags in my workspace have no firing trigger?*
:::

:::ExpandableHeading
### `gtm_get_tag`

Gets one tag by ID, with its full configuration, including type, all parameters, firing and blocking triggers, and fingerprint. Use this before `gtm_update_tag` so you edit the exact resource.

- **When to use**
  - Review a tag's complete configuration before you change it.
  - Confirm which triggers fire or block a specific tag.
  - Retrieve the exact JSON structure to modify with `gtm_update_tag`.
- **Parameters**
  - `workspace_id` – The workspace that contains the tag.
  - `tag_id` – The ID of the tag to retrieve. Get this from `gtm_list_tags`.
- **Example prompts**
  - *Get the full configuration for tag 45.*
  - *Show me the firing and blocking triggers for my GA4 purchase tag.*
  - *What parameters are set on tag 12 in my main workspace?*
:::

:::ExpandableHeading
### `gtm_create_tag`

Creates a tag in a workspace. Pass `tag_json` as the full Tag resource, with `name`, `type`, and a parameter list as the minimum required fields.

- **When to use**
  - Add a new GA4 event tag, custom HTML tag, or conversion linker to a workspace.
  - Stage a new tag in a workspace without publishing it to the live container.
  - Create a tag as part of a larger tracking rollout, such as scroll depth or engagement tracking.
- **Parameters**
  - `workspace_id` – The workspace to create the tag in.
  - `tag_json` – The full Tag resource to create. Requires `name`, `type`, and a `parameter` list. For example, a GA4 event tag: `{"name":"GA4 - purchase","type":"gaawe","parameter":[...]}`.
- **Example prompts**
  - *Create a GA4 event tag named "GA4 - purchase" in my main workspace.*
  - *Create a 50% and 90% scroll depth trigger for my blog pages only, and a GA4 event tag for each. Stage it in a workspace — don't publish.*
  - *Add a custom HTML tag that fires a third-party pixel on the checkout confirmation page.*
:::

:::ExpandableHeading
### `gtm_update_tag`

Updates (replaces) an existing tag. Fetch it first with `gtm_get_tag`, modify the JSON, and pass the full resource as `tag_json`. This is a full replacement, so include every field you want to keep.

- **When to use**
  - Change a tag's firing triggers, parameters, or name after reviewing it with `gtm_get_tag`.
  - Correct a misconfigured tag, such as one firing on **All Pages** instead of a specific action.
  - Migrate a tag from a pageview trigger to a `historyChange` trigger for single-page app tracking.
- **Parameters**
  - `workspace_id` – The workspace that contains the tag.
  - `tag_id` – The ID of the tag to update.
  - `tag_json` – The full, updated Tag resource, including every field you want to keep. Field keys can be snake\_case or camelCase.
- **Example prompts**
  - *My GA4 config tag fires on a pageview trigger. Create a historyChange trigger instead and update the tag to fire on it, since my site is a single-page app.*
  - *Update tag 45 so it stops firing on All Pages and only fires on the checkout confirmation trigger.*
  - *Change the parameter list on my GA4 purchase tag to include the transaction ID variable.*
:::

:::ExpandableHeading
### `gtm_delete_tag`

Deletes a tag from a workspace. This is a workspace edit, so it only takes effect on the live site after you run `gtm_create_version` and `gtm_publish_version`.

- **When to use**
  - Remove a duplicate tag identified during a container audit.
  - Delete a tag you replaced with an updated version.
  - Clean up a paused tag that no team plans to reactivate.
- **Parameters**
  - `workspace_id` – The workspace that contains the tag.
  - `tag_id` – The ID of the tag to delete.
- **Example prompts**
  - *Delete the duplicate GA4 purchase tag in my main workspace.*
  - *Remove tag 78, since it has been paused for six months.*
  - *Delete the old Universal Analytics tag now that GA4 replaced it.*
:::

### Triggers

Use these tools to list, create, update, and delete the triggers that decide when a tag fires, such as page views, clicks, form submissions, custom events, and timers.

:::ExpandableHeading
### `gtm_list_triggers`

Lists all triggers in a workspace. Triggers decide when tags fire, such as on page views, clicks, form submissions, custom events, or timers.

- **When to use**
  - Find the `trigger_id` for a specific trigger before you read, update, or delete it.
  - Check which triggers exist before you create a tag that depends on one of them.
  - Audit a workspace for triggers that no tag references.
- **Parameters**
  - `workspace_id` – The workspace to list triggers for.
- **Example prompts**
  - *List every trigger in my main workspace.*
  - *Which triggers in my workspace have no tag attached to them?*
  - *Show me the trigger ID for my checkout confirmation page view trigger.*
:::

:::ExpandableHeading
### `gtm_create_trigger`

Creates a trigger in a workspace. Pass `trigger_json` as the full Trigger resource.

- **When to use**
  - Add a click trigger on a CSS selector, such as a **Buy** button.
  - Create scroll depth triggers, for example at 50% and 90%, to measure content engagement.
  - Create a `historyChange` trigger to track route changes on a single-page app.
- **Parameters**
  - `workspace_id` – The workspace to create the trigger in.
  - `trigger_json` – The full Trigger resource to create. For example, a click trigger on a CSS selector: `{"name":"Click - Buy button","type":"click","filter":[{"type":"cssSelector","parameter":[...]}]}`.
- **Example prompts**
  - *Create a 50% and 90% scroll depth trigger for my blog pages only.*
  - *Create a click trigger that fires when a visitor clicks the Buy button.*
  - *Create a historyChange trigger so route changes on my single-page app get tracked.*
:::

:::ExpandableHeading
### `gtm_update_trigger`

Updates (replaces) an existing trigger. Read it first with `gtm_list_triggers`, modify the JSON, and pass the full resource as `trigger_json`. This is a full replacement, so include every field you want to keep.

- **When to use**
  - Narrow or widen the pages a trigger fires on, such as restricting a scroll depth trigger to blog pages only.
  - Change the CSS selector or event name a trigger listens for.
  - Correct a trigger's filter conditions after reviewing it with `gtm_list_triggers`.
- **Parameters**
  - `workspace_id` – The workspace that contains the trigger.
  - `trigger_id` – The ID of the trigger to update.
  - `trigger_json` – The full, updated Trigger resource, including every field you want to keep. Field keys can be snake\_case or camelCase.
- **Example prompts**
  - *Restrict my scroll depth trigger to blog pages only.*
  - *Update trigger 33 so it fires on the new checkout confirmation URL.*
  - *Change the CSS selector on my Buy button click trigger.*
:::

:::ExpandableHeading
### `gtm_delete_trigger`

Deletes a trigger from a workspace. Check `gtm_list_tags` first, because any tag that fires on this trigger loses it. This is a workspace edit, so it only takes effect on the live site after you run `gtm_create_version` and `gtm_publish_version`.

- **When to use**
  - Remove a trigger after you confirm with `gtm_list_tags` that no tag depends on it.
  - Clean up a duplicate or unused trigger identified during a container audit.
  - Delete a trigger you replaced with a corrected version.
- **Parameters**
  - `workspace_id` – The workspace that contains the trigger.
  - `trigger_id` – The ID of the trigger to delete.
- **Example prompts**
  - *Check whether any tag uses trigger 33, and delete it if none does.*
  - *Delete the unused scroll depth trigger in my main workspace.*
  - *Remove the duplicate click trigger from my workspace.*
:::

### Variables

Use these tools to list and create the user-defined variables that tags and triggers reference, such as data-layer variables, constants, and lookup tables.

:::ExpandableHeading
### `gtm_list_variables`

Lists all user-defined variables in a workspace, such as constants, data-layer variables, lookup tables, and custom JavaScript variables.

- **When to use**
  - Review which variables a workspace already defines before you create a new one.
  - Find the variables a tag or trigger references.
  - Audit a workspace for unused or duplicate variables.
- **Parameters**
  - `workspace_id` – The workspace to list variables for.
- **Example prompts**
  - *List every variable in my main workspace.*
  - *Which data-layer variables are defined in my workspace?*
  - *Show me the lookup tables configured in my container.*
:::

:::ExpandableHeading
### `gtm_create_variable`

Creates a user-defined variable in a workspace. Pass `variable_json` as the full Variable resource.

- **When to use**
  - Add a data-layer variable to capture a value your site pushes to the data layer, such as a user ID.
  - Create a constant variable to reuse a fixed value, such as a measurement ID, across multiple tags.
  - Create a lookup table variable to map raw event values to friendly labels.
- **Parameters**
  - `workspace_id` – The workspace to create the variable in.
  - `variable_json` – The full Variable resource to create. For example, a data-layer variable: `{"name":"DLV - user_id","type":"v","parameter":[...]}`.
- **Example prompts**
  - *Create a data-layer variable named "DLV - user\_id" in my main workspace.*
  - *Add a constant variable that stores my GA4 measurement ID.*
  - *Create a lookup table variable that maps event names to friendly labels.*
:::

### Versions and publishing

Use these tools to freeze a workspace into a container version and publish it to your live site or app, or to review past versions before you publish or roll back.

:::ExpandableHeading
### `gtm_list_versions`

Lists the container versions for a container, including each version's ID, name, and how many tags, triggers, and variables it holds. Use this to find a `version_id` to publish.

- **When to use**
  - Review release history before you publish a new version.
  - Find the `version_id` for a version you want to publish or compare.
  - Check how many tags, triggers, and variables a past version held.
- **Parameters**
  - `container_id` – The container to list versions for.
- **Example prompts**
  - *List the last 10 container versions with their tag counts.*
  - *What version is currently live in my main container?*
  - *Show me every version created in my container this year.*
:::

:::ExpandableHeading
### `gtm_create_version`

Freezes the current state of a workspace into a new container version. Nothing goes live yet. Follow with `gtm_publish_version` to publish the returned version to the live container. Returns the new `container_version_id`, or a list of compiler errors if the workspace contains invalid configuration.

- **When to use**
  - Freeze a workspace after you finish staging new tags, triggers, or variables, before you publish them.
  - Create a version to review or share before it goes live.
  - Check for compiler errors in a workspace before you attempt to publish it.
- **Parameters**
  - `workspace_id` – The workspace to freeze into a new version.
- **Example prompts**
  - *Freeze my main workspace into a new container version.*
  - *Create a version from my current workspace so I can review it before publishing.*
  - *Check whether my workspace has any compiler errors before I create a version.*
:::

:::ExpandableHeading
### `gtm_publish_version`

Publishes a container version to the live container. This is what pushes your changes to the real site or app. Get a `version_id` from `gtm_create_version` or `gtm_list_versions`. Requires the `tagmanager.publish` scope on the connected Google account.

- **When to use**
  - Push a frozen version live after you review it.
  - Republish an older version to roll back a recent change.
  - Complete a tag, trigger, or variable change that only takes effect after publishing.
- **Parameters**
  - `version_id` – The container version to publish. Get this from `gtm_create_version` or `gtm_list_versions`.
- **Example prompts**
  - *Publish version 14 to my live container.*
  - *Roll back to the previous container version.*
  - *Publish the version I just created so my new scroll depth tags go live.*
:::

:::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](https://docs.optimizely.com/opti-id/docs/generative-ai-settings).
:::
