Test AdLoop connectivity — checks OAuth token, GA4 API, Google Ads API, and (when configured) the Reddit Ads and Microsoft Advertising APIs.

Returns the status of each service and actionable guidance when something is broken, which makes it the diagnostic for failures in other tools.

Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/

List all GA4 accounts and properties accessible by the authenticated user.

Serves as the discovery step for which GA4 properties are available. Returns account names, property names, and property IDs.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Run a custom GA4 report with optional filters, ordering, paging and a comparison period.

Returns the property, the date range, the dimension and metric headers, one row per dimension combination (values as strings), row_count and total_row_count (plus next_offset while more rows remain). At least one dimension or metric is required. With compare_start/compare_end the comparison period is a second date range: every row then carries a dateRange value of "current" or "comparison", and date_ranges maps both labels to their dates. Invalid filters or ordering return "Validation failed" with details, before anything is sent. insights[] says when GA4 thresholded or sampled the data, grouped rows into "(other)", or the property is close to its API quota, because each makes numbers differ from the GA4 interface. Reports over time (a date-type dimension) or comparing periods also return the property's annotations in those dates, which often explain a jump in the rows.

Queries the GA4 Data API. Dimensions and metrics: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema

Run a GA4 realtime report showing current active users and events.

Useful for checking if tracking is firing correctly after code changes: filter on the event that just shipped, or compare the last few minutes with the minutes before. Returns the dimension and metric headers and one row per dimension combination over the realtime window (the last 30 minutes unless minute_ranges says otherwise). When a filter matches nothing, insights[] lists the usual causes.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Show a GA4 property's configuration in one call: details, linked Google Ads accounts, data streams and data retention.

Returns the property's display name, time zone, currency, industry, service level (standard or 360), type and create time; every linked Google Ads account (customer ID, whether it is a manager account, personalized advertising); every data stream with its measurement ID or app ID; how many months event and user data are kept; and the number of key events. insights[] flags settings that cost data: two-month retention, no Google Ads link while key events exist, the configured Ads account not being linked, a property in the trash. A part the user may not read is listed under unavailable instead of failing the call. Reads the GA4 Admin API (properties.get, googleAdsLinks.list, dataStreams.list, getDataRetentionSettings, keyEvents.list).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

List all GA4 events and their volume for the given date range.

Returns every distinct event name with its total event count, sorted by count (highest first). Shows what tracking is configured and active.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

List the key events (conversions) configured on a GA4 property.

Returns each key event's event name, counting method (ONCE_PER_EVENT or ONCE_PER_SESSION), create time, whether GA4 allows deleting it, whether it is a custom event, and its resource name, sorted by event name, plus the total. Reads the GA4 Admin API (keyEvents.list).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

List the dimensions and metrics a GA4 property can report on, including custom ones.

Returns the exact API names valid in run_ga4_report for this property: each with its UI name, category, whether it is a custom definition (customEvent:..., customUser:...), and deprecated API names; metrics also carry their type and, for calculated metrics, the expression. Reads the GA4 Data API metadata (properties.getMetadata), which uses no report quota.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Run a GA4 funnel report: how many users go from one step to the next, and where they drop off.

Steps are event names or pages, in order. Returns per step the users, completion rate to the next step, abandonments and abandonment rate, plus how many started and finished, the overall completion rate and the biggest drop (after which step most users leave). With breakdown, the same per value of a dimension (e.g. deviceCategory); with next_action, the most common next event or page after each step, i.e. what users do instead. Uses the GA4 Data API v1alpha (runFunnelReport), the endpoint behind GA4's funnel explorations; data reaches back as far as the property's data retention.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Show which channels, campaigns or sources get the credit for conversions under GA4's attribution models, or compare data-driven with last click.

The view of GA4's Advertising workspace: conversions, revenue, ad cost and ROAS per channel (or campaign, source, country, device) attributed by the model, not by session. attribution_model COMPARE runs data-driven and last click side by side and returns each row's share of the credit under both and the shift in percentage points, with insights naming the channels that gain or lose most. Conversions can be named by key event name; empty means all. Uses the GA4 Data API v1alpha (runReport with a conversion spec), which Google is still rolling out: a property without it gets an explanation and the fallback. Ad cost and ROAS need Google Ads linked to the property.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Audit a GA4 property's setup in one call: the settings that quietly cost data or conversions.

Checks data retention (two months is GA4's default and cuts explorations short), the Google Ads link (and whether the configured Ads account is linked), each data stream's activity in the last 7 days, key events that never fired in 28 days or no key events at all, enhanced measurement per web stream, Google signals (and the thresholding they cause), the custom dimension and metric limits, and a property in the trash. Returns checks with status warn, info or ok (warnings first), a summary count, and the warnings as insights[]; a check the user may not read is listed under unavailable. Reads GA4 only (Admin API, part v1alpha, and two small Data API reports); for whether Google Ads imports the key events, run check_key_event_imports.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

List a GA4 property's annotations, the notes GA4 shows on a date or date range in its charts.

Returns each annotation's ID (resource name), title, description, color, and its date or start and end date, newest first; Google's own annotations are marked system_generated. With a date range, only the annotations that overlap it. The first stop for "what happened on that day?" next to get_change_history in Google Ads. Reads the GA4 Admin API v1alpha (reportingDataAnnotations.list).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

List a GA4 property's custom dimensions and custom metrics, with how many slots are left.

Returns each custom dimension's resource name, parameter name, display name, scope (EVENT, USER or ITEM) and description, and each custom metric's resource name, parameter name, display name, measurement unit and description, plus usage per kind against the property's limit (standard: 50 event, 25 user, 10 item dimensions, 50 metrics; 360: 125, 100, 25, 125). Use it before draft_ga4_custom_dimension or draft_ga4_custom_metric. For the field names to use in reports, see list_ga4_dimensions_and_metrics. Reads the GA4 Admin API (customDimensions.list, customMetrics.list).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

List all Google Search Console properties the authenticated user can access.

Serves as the discovery step for the site URLs that search analytics reports (run_gsc_report) take. Returns the site URL and permission level for each property.

Search Console API: https://developers.google.com/webmaster-tools

Run a Google Search Console search analytics report.

Returns clicks, impressions, CTR, and average position broken down by the requested dimensions. Useful for diagnosing organic traffic drops, finding keyword opportunities, and cross-referencing with GA4 and Ads data. One request returns at most 25,000 rows; a full page carries next_start_row for the following request. With data_state "all" the response metadata names the first date whose data is still incomplete.

Queries the Search Console API: https://developers.google.com/webmaster-tools/v1/searchanalytics/query

Run PageSpeed Insights for a landing page — Lighthouse + real-user data.

Returns the performance score (0-100), lab Core Web Vitals (LCP, CLS, TBT, FCP), CrUX field data from real Chrome users where available (p75 LCP/INP/CLS/FCP/TTFB + FAST/AVERAGE/SLOW ratings), and the top improvement opportunities with estimated savings. When the page itself has too little traffic for field data, the origin-wide field data is returned instead, marked field.scope="origin".

Typical input is an ad final_url: slow landing pages depress Quality Score and waste paid clicks. Takes 10-30s; that is normal for a Lighthouse run.

PageSpeed Insights API: https://developers.google.com/speed/docs/insights/v5/about

List Google Merchant Center accounts the connected user can access.

Returns each account's numeric ID, name and whether it is a test account. Provides the account_id used by get_merchant_feed_health; not needed when merchant.account_id is set in the config.

Merchant API: https://developers.google.com/merchant/api/overview

Merchant Center feed health — disapproved products + account issues.

Disapproved feed items silently starve Shopping and Performance Max campaigns; this reports approved/pending/disapproved counts per reporting context (Shopping ads, free listings, ...), the top product issues by affected products (with documentation links), and account-level issues — CRITICAL ones stop offers serving entirely. Product-status data lags reality by ~30 minutes.

Merchant API: https://developers.google.com/merchant/api/overview

The products behind the feed-health counts, each with its issues.

Lists products by status with offer id, title, brand, click potential and every item issue: its code, the attribute it concerns, severity per reporting context with the affected countries, and whether the merchant has to act or Google is still processing. Products with high click potential come first, because fixing them recovers the most traffic. issues_by_code counts the products per issue. Data lags feed changes by about 30 minutes.

Merchant API: https://developers.google.com/merchant/api/overview

List accessible Google Ads accounts.

Returns account names, IDs, status, and whether each is a manager account. When more accounts exist than limit, the response has 'truncated: true'; a much higher limit (e.g. list_accounts(limit=1000)) returns the full list. Workflows that target a specific account need no enumeration at all: get_campaign_performance, run_gaql, etc. take customer_id directly.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Get campaign-level performance metrics for a date range.

Returns campaign name, status, type, impressions, clicks, cost, conversions, CPA, ROAS, CTR for each campaign, plus Search impression share and the share lost to budget and to ad rank (fractions with matching *_pct percentages; null for campaigns that do not serve on Search or had no impressions). Insights flag converting campaigns that lose a significant share of impressions to budget.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Get ad-level performance data including headlines, descriptions, and metrics.

Returns ad type, headlines, descriptions, final URL, impressions, clicks, CTR, conversions, cost for each ad, plus its policy approval status, review status and policy topic names. Disapproved and limited-by-policy ads are listed under policy_issues with their spend.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Get keyword metrics including quality scores and competitive data.

Returns keyword text, match type, quality score, impressions, clicks, CTR, CPC, conversions for each keyword.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Get search terms report — what users actually typed before clicking your ads.

Critical for finding negative keyword opportunities and understanding user intent. Returns search term, campaign, ad group, impressions, clicks, conversions.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List existing negative keywords for a campaign or all campaigns.

Shows the existing negatives, which reveals duplicates before new negative keywords are added. Returns each negative's campaign, keyword text, match type, and a resource_id ("campaignId~criterionId") as taken by remove_entity, plus the total count.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List all shared negative keyword lists (SharedSets) in the account.

Returns each list's ID, name, status, and keyword count. Useful before propose_negative_keyword_list: a suitable list may already exist and just need attaching to a campaign.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List the keywords inside a shared negative keyword list.

Returns each negative keyword's text, match type, and a resource_id ("sharedSetId~criterionId"), with the total keyword count.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List which campaigns a shared negative keyword list is attached to.

Returns each list-to-campaign attachment with the list and campaign IDs and names.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Retrieve Google's auto-generated recommendations with estimated impact.

Returns each recommendation's ID, type, associated campaign/ad group, current (base) and projected (potential) metrics, and the estimated improvement. Includes insights that flag budget-increase recommendations (their projected gain comes from spending more) and highlight high-impact suggestions. The recommendation.id is what draft_dismiss_recommendations takes.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Dismiss Google Ads recommendations — returns a PREVIEW.

Turns down recommendations you will not take (e.g. "add broad match" on a deliberately narrow account) so they stop reappearing in get_recommendations. Nothing in the account changes, and Google can show a dismissed recommendation again later, so a single confirmation is enough.

Each ID must be an active recommendation: unknown or already dismissed IDs are refused by name. The preview lists each one's type, campaign and estimated improvement, so the user sees what they are turning down.

DismissRecommendation has no validate-only mode: the dry run re-reads the account and checks every recommendation is still active instead of sending the call to Google. The returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List the recommendation types Google applies automatically (auto-apply).

A subscription makes Google apply every new recommendation of its type without asking, so changes reach the account with no preview. Returns each subscription's type, status (ENABLED or PAUSED), create_date_time and modify_date_time. A type that is not listed is not auto-applied. insights[] names every ENABLED type and flags one modified in the last 30 days, so a recurring audit can catch auto-apply being switched on.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Pause auto-apply for recommendation types — returns a PREVIEW.

Pausing is the only change this tool can make: it sets each type's subscription to PAUSED, so Google stops applying those recommendations on its own. Their recommendations still appear in get_recommendations. Re-enabling auto-apply is deliberately not supported; it lets Google change the account without a preview, so it stays a decision for the Google Ads UI. Pausing reduces automation, so a single confirmation is enough.

Each type must have an ENABLED subscription (see get_recommendation_subscriptions); a type with none, or one already paused, is refused by name. The dry run sends the request to Google with validate_only. The returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Get Performance Max campaign and asset group performance.

Returns two result sets. campaigns: PMax campaign metrics broken down by ad_network_type (SEARCH, CONTENT, YOUTUBE_SEARCH, YOUTUBE_WATCH, MIXED). MIXED is a catch-all that Google uses for most PMax traffic — full channel splits are not available via the API. asset_groups: per-asset-group metrics including ad_strength (EXCELLENT, GOOD, AVERAGE, POOR).

Includes insights flagging weak ad strength, zero-conversion asset groups, and network type distribution.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List the assets of Performance Max campaigns with type, status and content.

Returns each asset's field_type (HEADLINE, DESCRIPTION, MARKETING_IMAGE, YOUTUBE_VIDEO, etc.), primary_status (ELIGIBLE, NOT_ELIGIBLE, PAUSED, PENDING), and content (text or image URL), plus by_status and by_field_type summaries.

Per-asset performance labels (BEST/GOOD/LOW) are not available for PMax assets in the Google Ads API. get_detailed_asset_performance reports which asset combinations Google selects most — the closest proxy for individual asset quality.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Get top-performing asset combinations for Performance Max campaigns.

Shows which headline + description + image combinations Google selects most often. Returns each combination with the assets used and their field types. This data helps identify which creative elements work well together.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Get audience segment performance metrics.

Returns performance by audience type — remarketing lists (USER_LIST), in-market segments (USER_INTEREST), affinity, demographics (AGE_RANGE, GENDER), etc. Shows display_name, impressions, clicks, cost, conversions, CTR, and CPC for each audience.

Works for campaigns with explicit audience targeting (Search, Display). PMax audience targeting is automatic and may not appear in this report.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List demographic targeting criteria (age, gender, parental status, income).

Takes exactly one of ad_group_id or campaign_id. Returns each criterion's value, whether it's negative (excluded) or positive (narrowing), status, and a remove_id (composite resource ID) that can be passed directly to remove_entity with entity_type='ad_group_criterion' or 'campaign_criterion'.

By default, Google Ads serves ads to ALL demographic segments — a criterion only appears here once a segment has been actively excluded or narrowed.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List recent account changes: who changed what, when, and through which tool.

Answers "what changed before the drop?". Returns each change newest first with its time, the user's email, the client it came through (Google Ads UI, API, Google Ads scripts, Editor, automated rules, auto-applied recommendations, ...), the changed resource type, the operation (CREATE, UPDATE, REMOVE), the changed field paths, and the campaign and ad group names. Also returns counts by resource type, client, user and day, plus insights on auto-applied recommendations and budget or bidding changes. Google Ads keeps change history for 30 days, so older start dates are moved to the earliest available day.

Reads the change_event resource: https://developers.google.com/google-ads/api/docs/change-event

Campaign clicks → GA4 conversions mapping — the real cost-per-conversion.

Combines Google Ads campaign metrics with GA4 session/conversion data to reveal click-to-session ratios (GDPR indicator), compare Ads-reported vs GA4-reported conversions, and compute cost-per-GA4-conversion. Also returns non-paid channel conversion rates for comparison context. GA4 conversions are the property's key events (GA4 metric keyEvents).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start

Analyze which landing pages convert and which don't.

Combines ad final URLs with GA4 page-level data. Returns paid traffic sessions, conversion rates, bounce rates, and engagement per landing page, and identifies pages that get ad clicks but zero conversions and orphaned URLs.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start

Compare Ads-reported conversions vs GA4 — find tracking discrepancies.

Checks whether conversions reported by Google Ads match what GA4 records, diagnoses GDPR consent gaps, attribution model differences, and missing conversion event configuration. Returns both sides' totals with the discrepancy and diagnostic insights. GA4 conversions are the property's key events (GA4 metric keyEvents).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start

Set up conversion tracking from GA4 into Google Ads in one approved plan, returning a PREVIEW of only the missing steps.

Use it when the user wants their conversions (sign-ups, purchases, leads) tracked and used for bidding, or after audit_ga4_property or check_key_event_imports found a gap. It reads both products and plans what is missing, in order: link the GA4 property to the Google Ads account, mark the events as GA4 key events, turn on auto-tagging, import the conversion actions Google Ads created for the key events (they start hidden and record nothing), make them primary, and use their goal for bidding. Steps already in place are listed under already_done. Google Ads creates the conversion action for a newly linked property or new key event by itself, not instantly: such events come back as "After this" warnings, and running the tool again later imports them. NO_CHANGE when everything is set up. The website must send the events; this tool cannot add tracking code (see generate_tracking_code). Nothing changes until confirm_and_apply applies it: the dry run validates the Google Ads steps with validate_only and re-reads the GA4 ones, and every step skips itself if already done, so confirming again after a failed step continues where it stopped.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start

Check that every GA4 key event reaches Google Ads: imported, used for bidding, and actually receiving conversions.

Matches the property's key events with the Google Ads conversion actions that import them (by GA4 property and event name), and compares GA4's key events from Google Ads traffic (google / cpc) with the conversions Google Ads recorded for each import. insights[] names key events no conversion action imports, imports that are only secondary (reported, not bid on), imports that stay at zero while GA4 counts Google Ads conversions (a broken link or auto-tagging), and imports of events that are no longer key events. Imports from other GA4 properties are listed separately.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start

Three-way audit: codebase events ↔ GTM tags ↔ GA4 actual fires.

Fetches the LIVE GTM container, joins it against GA4 event counts for the date range, and returns a per-event matrix with one of these statuses: ok — tag active and event firing ok_auto_collected — GA4 Enhanced Measurement event, no tag needed no_tag_no_fire — codebase event, no GTM tag, never fires tag_paused — GTM tag exists but is paused tag_active_but_not_firing — tag is active but no GA4 hits gtm_only_firing — GA4 event from a tag, not in codebase gtm_paused_but_firing — only paused tag(s), not in codebase, yet GA4 still fires (event comes from elsewhere) gtm_only_not_firing — tag exists, not in codebase, no fires ga4_only — fires in GA4, no tag, no codebase ref ga4_fires_no_tag — codebase event firing without a GTM tag auto_event_only — Enhanced Measurement event with no codebase ref

The result also lists dynamic-event tags ({{Event}} variables) and Custom HTML tags that the audit cannot interpret automatically.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

List all GTM accounts the AdLoop service account / OAuth user can read.

The first-time discovery step: provides the account_id that audit_event_coverage takes. Returns each account's ID and name. An empty list means the service account hasn't been added to any GTM container with at least Read permission.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

List all containers under a GTM account.

Returns container_id (the numeric ID needed by audit_event_coverage), public_id (the GTM-XXXXXXX string shown in the UI), name, and usage context (web / iOS / Android / amp / server).

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

List every tag in the LIVE GTM container, or in one workspace.

Each tag includes type, status, parsed parameters, the GA4 event name (for GA4 event tags), and resolved firing/blocking trigger names. Complements audit_event_coverage for inspecting specific tags. With workspace_id the list shows that workspace's unpublished state, so a just-drafted tag is visible; source says which state was read.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Get the full RAW configuration for a single GTM tag.

Includes every parameter, firing/blocking triggers (with their filter conditions resolved to text), priority, pause status, sampling, and monitoring metadata. Suited to inspecting a tag flagged by audit_event_coverage. An unknown tag_id returns an error with the available tag IDs. Reads the live container, or a workspace's unpublished state when workspace_id is set.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

List every trigger in the LIVE GTM container, or in one workspace.

Each trigger has its filter conditions parsed to readable text (e.g. "{{Page Path}} matches RegExp ^/service-promotions/"). Helps diagnose why a tag fires or doesn't fire on specific pages. With workspace_id the list shows that workspace's unpublished state.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Get the full RAW configuration for a single GTM trigger.

Includes filters, auto-event filters, custom-event filters, validation settings, and a list of every tag that uses this trigger. Helps diagnose why a tag with a specific trigger ID does or doesn't fire. An unknown trigger_id returns an error with the available trigger IDs. Reads the live container, or a workspace's unpublished state when workspace_id is set.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

List GTM variables — both custom and enabled built-in.

Without workspace_id both come from the live container version (the Default Workspace supplies the built-ins only when the live version lists none; built_in_source names where they came from). With workspace_id both come from that workspace's unpublished state. Variables matter because triggers reference them: if a trigger uses {{Form ID}} but Form ID isn't enabled, the trigger never matches.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

List workspaces (drafts) under a GTM container.

Returns each workspace's ID, name and description; the IDs are what get_gtm_workspace_diff takes. Most containers have a single Default Workspace; multiple workspaces appear when the team uses parallel drafts.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Show drafted-but-not-published changes in a GTM workspace.

Returns the list of entities (tags, triggers, variables) added, modified, or deleted relative to the live published version, plus any merge conflicts. Common cause of "I edited a tag but nothing happened" — the workspace was never published. is_clean=true means no pending changes and no conflicts.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

List GTM container version headers (newest first).

Version headers include version_id, name, archived flag and entity counts. The Tag Manager API returns no creation or publish time and no author for a version, and does not mark which versions were published; get_gtm_version returns a version's notes and get_gtm_version_diff what changed between two versions.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Get metadata + entity counts for a single GTM container version.

Returns name, description (the version notes), fingerprint, and lists of tag/trigger/variable names at that point in time. The API returns no timestamps or author for a version.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Compare two GTM container versions: what a publish changed.

Returns added, removed and changed tags, triggers and variables (with names, types and the changed fields; parameters and trigger conditions are diffed key by key), plus built-in variables enabled or disabled. By default compares the live version with the version created before it. The Tag Manager API does not mark which versions were published, so that default "before" version may never have been live. Makes two or three Tag Manager API calls.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Draft creating or updating a Tag Manager tag — returns a PREVIEW.

Without tag_id this creates a tag in a workspace; with tag_id it updates the existing tag. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set, and Custom HTML (html) is refused as well unless gtm.allow_custom_html is set. Returns the resolved workspace, the tag type, the fields that would change and a plan_id.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Draft creating or updating a Tag Manager trigger — returns a PREVIEW.

Without trigger_id this creates a trigger in a workspace; with trigger_id it updates the existing one. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set. Returns the resolved workspace, the trigger fields that would change and a plan_id.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Draft creating or updating a Tag Manager variable: returns a PREVIEW.

Without variable_id this creates a variable in a workspace; with variable_id it updates the existing one. Data Layer Variables, the usual source for GA4 ecommerce values, take data_layer_key (e.g. "ecommerce.value") instead of raw parameters. Tags and triggers use a variable as {{name}}; renaming one they reference is refused, because the references would break (the GTM UI renames safely). Custom JavaScript variables run code on the site and are refused unless gtm.allow_custom_html is set. The edit lands in the workspace and changes nothing on the site until the workspace is published. Refused unless gtm.write_enabled is set.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Draft deleting a Tag Manager tag, trigger or variable — returns a PREVIEW.

The entity is removed from a workspace and stays on the site until the workspace is published. A trigger that any tag still references, or a variable that a tag, trigger or other variable uses as {{name}}, is refused up front, with the references named. Refused unless gtm.write_enabled is set. Returns the entity that would be deleted, the resolved workspace and a plan_id.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Draft publishing a Tag Manager workspace LIVE — returns a PREVIEW.

Every pending change in the workspace goes live, including changes other people made in the GTM UI; the preview lists them all. Apply refuses when the workspace changed after the preview, has merge conflicts, or reports compiler errors in a quick preview, and it refuses a Custom HTML tag being added or changed while gtm.allow_custom_html is off. Refused unless gtm.write_enabled is set. Returns the pending changes, the version that is live now (for a one-step rollback), the version name that would be created and a plan_id. That gate matches the tag type html; a Custom JavaScript variable or a custom template tag (cvt_…), which can inject a script, is not covered and needs review in the GTM UI.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Draft republishing an older Tag Manager version LIVE; returns a PREVIEW.

A rollback publishes an existing container version again. The preview diffs the live version against the target, so it lists every tag, trigger and variable that changes on the site, and it pins the live version: apply refuses when another version went live after the preview, or when the target was modified or archived. Workspaces are not changed. Refused unless gtm.write_enabled is set, and refused when the target adds or changes a Custom HTML tag while gtm.allow_custom_html is off. Returns the diff, previous_live_version_id (the version that restores today's state), the target version and a plan_id.

Tag Manager API: https://developers.google.com/tag-platform/tag-manager/api/v2

Execute an arbitrary GAQL (Google Ads Query Language) query.

For queries beyond the dedicated report tools. Returns the result rows in the requested format with the query echoed back; cost fields stay in raw micros (cost_micros / 1,000,000 = account currency). A failing query returns an error with a hint.

Queries the Google Ads API. GAQL syntax and fields: https://developers.google.com/google-ads/api/docs/query/overview

The account's own audiences: remarketing and customer lists, custom segments, combined segments.

Each user list comes with its type, membership status (OPEN or CLOSED), size for Search and Display, eligibility and membership duration; custom and combined segments with their id and description. Insights flag lists below the 1,000 users Search needs and closed lists. Use the ids with draft_audience_attachment; for Google's in-market and affinity segments use search_audience_segments.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Find Google's in-market and affinity segments by name, with the segment_id to attach.

In-market segments are people actively researching a purchase; affinity segments are long-term interests. Matching is on the segment name, in English, e.g. "running", "insurance", "travel".

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Audiences attached to one campaign or ad group, its exclusions, and the audience mode.

audience_mode is "observation" (audiences only adjust bids and report), "targeting" (ads only reach the audiences) or "not set". Every audience and exclusion carries a remove_id for remove_entity (entity_type "campaign_criterion" or "ad_group_criterion").

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft attaching audiences to a campaign or ad group as observation, targeting or exclusion: returns a PREVIEW.

Observation (the default) keeps the reach: the audiences adjust bids and show up in reports. Targeting narrows delivery to the audiences and needs a double confirmation. Exclusions keep the people out and leave the mode alone. The draft refuses combinations Google does not allow (custom segments on Search, combined segments outside Search, audiences at both campaign and ad group level) and lists that cannot serve; Performance Max is refused with a pointer to draft_asset_group_signals. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Spend, clicks, conversions, CPA and ROAS per product across Shopping and Performance Max.

Each product (item id) is summed over the campaigns it ran in. Returns the account totals, the top products by spend, and the products that spent without a conversion, with insights on what to do with them.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Search themes and the audience signal of a Performance Max asset group, plus the account's audiences.

Returns each search theme and audience signal with its signal_id and approval status, the enabled audiences of the account that can become the group's audience signal (audience_id, name), and insights when a group has no themes or no audience signal.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft adding search themes or an audience signal to a Performance Max asset group, or removing signals — PREVIEW.

Signals are hints that steer Performance Max, not targeting. A group has at most one audience signal and up to 50 search themes; replacing the audience means removing the current one in the same draft. Themes already on the group are skipped. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft which products a retail Performance Max asset group excludes — returns a PREVIEW.

Sets the full list of excluded values on one product dimension (item id, brand or a custom label); everything else stays included. Pass the complete list each time: values left out are included again, and an empty list includes all products. Works on asset groups that advertise all products or are already split on that one dimension; more complex product filters are refused and stay a job for Google Ads. The filter is rebuilt in one atomic request. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft adding and/or removing assets of a Performance Max asset group — returns a PREVIEW.

Adds new text, image and YouTube assets and unlinks existing ones in one atomic request, so an asset is replaced without the group dropping below Google's minimums (3 headlines, 1 long headline, 2 descriptions, one of them at most 60 characters). Texts already in the group are skipped. Images are checked and sorted by aspect ratio; removed assets stay in the account's asset library. The preview lists the asset counts per type after the change. Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a Standard Shopping campaign that advertises a Merchant Center feed — returns a PREVIEW.

Creates the budget, the campaign (PAUSED), a product ad group with its Shopping ad, and one "All products" product group, in one atomic request. The Merchant Center account must be linked to the Google Ads account; the draft checks that. Shopping campaigns take no keywords and no language targeting (the feed's language applies). Nothing changes until confirm_and_apply applies the plan_id; a dry run has Google validate it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a full campaign structure — returns a PREVIEW, does NOT create anything.

Creates: CampaignBudget + Campaign (PAUSED) + AdGroup + optional Keywords

• geo targeting + language targeting. Ads are NOT included — draft_responsive_search_ad adds them once the campaign exists. Only SEARCH campaigns can be created: Performance Max needs an asset group with all its assets in one request, and DISPLAY, SHOPPING and VIDEO need channel-specific settings and ad group types, so the draft refuses them.

Returns a preview with a plan_id plus any warnings (e.g. a daily budget below 5x target CPA, MANUAL_CPC); nothing changes until confirm_and_apply applies the returned plan_id.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a new ad group within an existing campaign — returns a PREVIEW, does NOT create.

Creates an ad group (ENABLED, type SEARCH_STANDARD) in the specified campaign, optionally with keywords in the same atomic operation. Only SEARCH campaigns are supported. Ads are not included, so the ad group cannot serve until one of its ads is created and enabled.

Returns a preview with a plan_id plus warnings (BROAD keywords on a non-Smart-Bidding campaign, a duplicate ad group name, a CPC bid that Smart Bidding ignores); nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft an update to an existing campaign — returns a PREVIEW, does NOT apply.

Only the parameters passed are changed; omitted ones stay as they are, and at least one change is required. Replacing geo targets keeps the campaign's negative geo exclusions (the preview lists them). A budget change shows the current amount; when the budget is shared with other campaigns, the preview names them and needs a double confirmation, because the new amount covers all of them. A bidding change on a campaign in a portfolio bid strategy takes it out of the portfolio, also with a double confirmation.

Returns a preview with a plan_id plus any warnings; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a Responsive Search Ad — returns a PREVIEW, does NOT create the ad.

The preview shows exactly what will be created; confirm_and_apply executes the returned plan_id. The ad is created PAUSED. final_url is checked for reachability first and an unreachable URL is refused. Several headlines may pin to the same position (Google rotates them there) as long as every position stays fillable, by an asset pinned to it or by a distinct unpinned one. Mixed plain-string and dict entries are allowed within a single call (e.g. brand pinned to HEADLINE_1, the rest unpinned). Warnings note fewer than 8 headlines or 3 descriptions.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Update mutable fields on an existing RSA in place — returns a PREVIEW.

Edits an existing RSA without creating a new ad; the ad keeps its ID. Google Ads API v23 (AdService.MutateAds) permits in-place mutation of final_urls, path1, path2, headlines, and descriptions. At least one mutation must be requested.

IMPORTANT: replacing headlines or descriptions is NOT a free in-place edit. Even though the ad ID is preserved, swapping the creative text RESETS the ad's asset-combination learning and performance history and sends the ad BACK THROUGH Google policy review — Google treats the creative as new for optimization. URL-only and path-only edits do not incur this. When headlines/descriptions change, the returned preview includes a warnings entry stating this trade-off before anything is applied.

Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft keyword additions — returns a PREVIEW, does NOT add keywords.

Returns a preview with a plan_id, plus a warning when BROAD keywords go into a campaign without Smart Bidding; nothing changes until confirm_and_apply applies the returned plan_id.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Read the custom conversion goals and the campaign goal configuration.

Returns every custom goal with its name, status and conversion actions, plus — optionally for one campaign — the goal config the campaign uses (goal_config_level CUSTOMER or CAMPAIGN and the assigned custom goal).

A custom conversion goal bundles conversion actions into a named set that a campaign can be pointed at. Ahead of drafting, this shows which goals exist, which actions they contain and what a campaign currently uses.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Create a custom conversion goal — returns a PREVIEW.

The goal bundles conversion actions into a named set that campaigns can then be pointed at with draft_assign_custom_conversion_goal. Only the goal is created: conversion actions are read for validation and never modified. It is always created ENABLED — a goal created as REMOVED would be invisible to every other tool, so there is nothing to plan.

If a goal with the same name and exactly the same conversion actions already exists, nothing is planned and the result says already_exists with that goal's ID (REMOVED goals do not count). A name that exists with different actions is changed with draft_update_custom_conversion_goal.

The returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Rename and/or re-scope an existing custom conversion goal — PREVIEW.

conversion_action_ids REPLACES the whole action list, it does not append. An empty parameter stays unchanged. The preview shows the action list before and after.

The returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Point a campaign at a custom conversion goal — returns a PREVIEW.

Sets goal_config_level=CAMPAIGN and the goal on that campaign's conversion goal config. Nothing else changes: conversion actions, bidding, budgets and the account-level goals stay as they are.

A campaign must have at least one goal configured when it switches to campaign level — Google answers EMPTY_CONVERSION_GOALS otherwise. That is why this tool assigns a goal instead of clearing goals; draft_clear_custom_conversion_goal goes back to the account level.

If the campaign already uses exactly this goal, nothing is planned and the result says already_configured. The preview carries a note that changing what a campaign optimises for restarts its Smart Bidding learning period.

The returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Put a campaign back on the account-level goals — returns a PREVIEW.

Sets goal_config_level=CUSTOMER and clears the custom goal: the rollback for draft_assign_custom_conversion_goal. The account-level goals themselves are not touched.

The returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft negative keyword additions — returns a PREVIEW.

Negative keywords prevent your ads from showing for irrelevant searches. They are added at campaign level. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft negative geo location additions — returns a PREVIEW.

Excludes cities/regions from a campaign while keeping broader positive targets such as State of Sao Paulo. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a shared negative keyword list and attach it to a campaign — returns a PREVIEW.

Creates a reusable negative keyword list (shared set) that can later be applied to multiple campaigns, whereas add_negative_keywords adds negatives directly to one campaign. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Append keywords to an EXISTING shared negative keyword list — returns a PREVIEW.

Adds terms to a list that already exists (propose_negative_keyword_list creates a new list instead); get_negative_keyword_list_keywords shows the terms already in a list. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Attach an existing shared set to one or more campaigns — returns a PREVIEW.

Creates CampaignSharedSet linkages so the campaigns inherit the shared set's criteria (e.g. negative keywords). Most commonly used to attach a shared negative keyword list to newly-built campaigns; get_negative_keyword_list_campaigns lists existing attachments. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Detach a shared set from one or more campaigns — returns a PREVIEW.

Removes CampaignSharedSet linkages so the campaigns no longer inherit the shared set's criteria. The shared set itself is unchanged; only the per-campaign attachment is removed. get_negative_keyword_list_campaigns lists the existing attachments. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Read the AI Max controls of Search campaigns, per campaign and ad group.

Returns for every campaign: id, name, status, advertising channel type, campaign.ai_max_setting.enable_ai_max, campaign.ai_max_setting.bundling_required (output only) and the full campaign.asset_automation_settings list. Each campaign also carries its non-REMOVED ad groups with ad_group.ai_max_ad_group_setting.disable_search_term_matching.

Shows the current state ahead of draft_ai_max_settings, and what the account actually looks like after confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Read every setting that decides how far a Search campaign reaches, in one call.

Returns one flat record per campaign: status, bidding strategy and its target or CPC ceiling, daily budget and whether it is shared, the Google Search / search partner / Display network flags, the location option (positive_geo_target_type) and its negative counterpart, campaign-level broad match (keyword_match_type), the tracking template, final URL suffix and custom parameters, and the AI Max state get_ai_max_settings reports (enable_ai_max, asset automation per type). Money is in the account currency (currency).

Each campaign lists its widening_settings: search partners or Display on, a presence-or-interest location option, broad match on, AI Max on, an automation opted in. insights[] names the campaigns that have any. Made for recurring audits: the same call every week diffs cleanly.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft AI Max controls for a Search campaign — returns a PREVIEW.

AI Max is the container that makes brand exclusions usable in Search: Google rejects a brand list on a plain Search campaign ("For search advertising channel, brand lists can only be applied to exclusive targeting, broad match campaigns for inclusive targeting or PMax generated campaigns"). Turning AI Max on while leaving its automations running is the trap, so both belong to the same plan. An automation the caller never mentioned is refused outright (the plan says which switch to pass); one named explicitly (disable_search_term_matching=False, text_asset_automation="OPTED_IN") is planned with requires_double_confirm=True, because switching to AI Max with its automations is a real configuration some accounts want.

Reads the campaign and its ad groups first, so the preview names concrete ad groups and shows current values per knob. Returns a preview with a plan_id; nothing is written until confirm_and_apply runs.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft the safe standard state for brand exclusions — returns a PREVIEW.

Exactly one combination, nothing else: enable_ai_max = true, disable_search_term_matching = true (all non-removed ad groups), TEXT_ASSET_AUTOMATION = OPTED_OUT and FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION = OPTED_OUT.

No bidding, keyword, match type, ad, URL or budget change, and no brand list is attached — attaching stays a separate step with propose_brand_list / attach_brand_list_to_campaigns once this state is verified in the account.

Returns a preview with a plan_id (purpose brand_exclusions); nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft demographic targeting (age/gender/parental status/income) — returns a PREVIEW.

By default, Google Ads serves to all demographic segments. This tool adds criteria that EXCLUDE a segment (negative=True, default) or NARROW targeting to it (negative=False — uncommon). Takes exactly one of ad_group_id or campaign_id, and at least one of the four demographic lists must contain a value.

Returns a preview with a plan_id, plus warnings when the change narrows targeting, excludes 'undetermined' users, or excludes nearly a whole dimension; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft an ad group update for name and/or manual CPC bid — returns a PREVIEW.

A bid change applies only when the campaign uses MANUAL_CPC: automated bidding strategies ignore ad-group CPC bids, so such a change is refused (for Maximize Clicks the campaign cpc_bid_ceiling, set through update_campaign, is the active constraint). Bid increases above the configured safety.max_bid_increase_pct are refused. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft callout assets for an ad group, a campaign or the account — returns a PREVIEW.

Creates callout assets and links them where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking (every campaign without callouts of its own) needs scope="account" and no id. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft structured snippet assets for an ad group, a campaign or the account — returns a PREVIEW.

Creates structured snippet assets and links them where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a call asset (a phone number shown with the ads) — returns a PREVIEW.

Creates the call asset and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Google reviews the number before it serves. Returns a preview with a plan_id.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft changing a call asset in place — returns a PREVIEW.

Only the fields passed change. The asset keeps its ID and its links, so the change shows everywhere it is linked. The preview shows the current values and pins them; an edit in Google Ads before the apply stops it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft ad schedule windows for a campaign — returns a PREVIEW.

Adds the windows; existing ones stay. The preview lists the current windows (each with the remove_id that remove_entity takes as a campaign_criterion) and the account time zone the hours are in. Overlapping windows and more than six a day are refused. A campaign without any window serves at all hours, so its first windows restrict it to them: that preview needs a double confirmation.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a promotion asset ("20% off winter tyres") — returns a PREVIEW.

Creates the promotion and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. The final_url is checked for reachability. Returns a preview with a plan_id.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft changing a promotion asset in place — returns a PREVIEW.

Only the fields passed change; everything else stays as it is. The asset keeps its ID and history, and the change shows everywhere it is linked. Passing money_off replaces a percent_off (and the other way round); passing promotion_code replaces an orders_over_amount (and the other way round). The preview shows old and new values; an edit in Google Ads before the apply stops it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a price asset (the row of prices under an ad) — returns a PREVIEW.

Creates a price asset with 3-8 offerings and links it where the id points: ad_group_id links to that ad group, campaign_id to that campaign. Account-wide linking needs scope="account" and no id. Every offering URL is checked for reachability. Google disapproves prices that differ from the landing page. Returns a preview with a plan_id.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a business name asset for a campaign or the account — returns a PREVIEW.

Creates a text asset and links it as the business name shown with the ads. Google links business names at campaign or account level only. Account-wide needs scope="account" and no campaign_id. Returns a preview with a plan_id.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft linking existing assets at account level — returns a PREVIEW.

Account-level assets serve on every eligible campaign that has no asset of the same type linked at campaign or ad-group level. Each asset is checked to exist and to match its field type. Returns a preview with a plan_id.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft changing a callout asset's text in place — returns a PREVIEW.

The asset keeps its ID and performance history, and the new text shows everywhere it is linked. The preview pins the current text; if someone edits the asset in Google Ads before the apply, nothing is sent.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft changing a sitelink asset in place — returns a PREVIEW.

Only the fields passed change; empty fields stay as they are. The asset keeps its ID and performance history everywhere it is linked. A new final_url is checked for reachability. The preview pins the current values; an edit in Google Ads before the apply stops it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft changing a structured snippet asset in place — returns a PREVIEW.

Replaces the snippet's values (and header, if given). The asset keeps its ID and performance history everywhere it is linked. The preview pins the current header and values; an edit in Google Ads before the apply stops it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft image assets from local files, public image URLs or uploads — returns a PREVIEW.

At least one image in total is required across image_paths, image_urls and upload_ids. Images must be PNG, JPEG or GIF and at most 5120 KB (Google's limit). URL images are downloaded now and checked; applying re-downloads them and refuses if the image changed since the preview. Returns a preview with a plan_id and a per-image summary; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft pausing a campaign, ad group, ad, or keyword — returns a PREVIEW.

Pausing is reversible with enable_entity. Returns a preview with a plan_id (target status PAUSED); nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft enabling a paused campaign, ad group, ad, or keyword — returns a PREVIEW.

Returns a preview with a plan_id (target status ENABLED); nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft REMOVING an entity — returns a PREVIEW. This is IRREVERSIBLE.

Removed entities cannot be re-enabled; pause_entity is the reversible way to temporarily disable something. Returns a preview with a plan_id and requires_double_confirm=true; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft sitelink extensions for a campaign or the account — returns a PREVIEW.

Sitelinks appear as additional links below your ad, increasing click area and directing users to specific pages. Every final_url is fetched and an unreachable URL (HTTP 4xx/5xx) blocks the draft. Google recommends at least 4 sitelinks per campaign; fewer than 2 may not show. Returns a preview with a plan_id and any warnings; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Execute a previously previewed change.

IMPORTANT: Defaults to dry_run=True (validate only). Only an explicit dry_run=false applies the change to the ad account (Google Ads or Reddit Ads — the plan knows which platform it targets).

Forced dry runs: when real changes are switched off (live changes off for the workspace in AdLoop Cloud, or safety.require_dry_run in a self-hosted config), dry_run=false is IGNORED and the result is still DRY_RUN_SUCCESS, with 'dry_run_forced_by' and 'remediation' fields. 'remediation' says how the user switches that setting; until it is changed, repeated calls with dry_run=false change nothing.

Two-phase apply: if 'safety.two_phase_apply: true' is set (always on for AdLoop Cloud tenants), dry_run=false is REFUSED with status DRY_RUN_REQUIRED until this plan_id has completed one dry_run=true pass. The sequence is: dry run, review of its result, then the real apply.

Google Ads plans: the dry run sends the exact mutates to Google with validate_only=True, so Google checks the change and executes nothing (checks counts the validated calls). Steps that build on an object an earlier step would create cannot be validated and are counted as skipped.

Reddit plans: Reddit has no validate-only mode, so the dry run re-reads the target entity and re-checks the safety caps (returned as checks).

A DRY_RUN_FAILED result means the change does not go through as previewed. The real apply fails the same way, unless Google rejected only part of the request: then it carries out the rest and reports those operations again.

Returns a status with the plan_id and operation: DRY_RUN_SUCCESS, DRY_RUN_FAILED, DRY_RUN_REQUIRED, BLOCKED, APPLIED, PARTIAL_UPLOAD, PARTIAL_APPLY, UNKNOWN_OUTCOME or APPLY_IN_PROGRESS. BLOCKED means the operation was added to safety.blocked_operations after the draft: nothing ran and the plan stays pending. APPLIED results carry the created or changed resource names under 'result'. PARTIAL_UPLOAD belongs to the upload tools: the batches it lists are already in the account, so the plan is retired. 'sent_total', 'accepted_total', 'rejected_total' and 'resume_from_line' say how far the upload got and at which CSV line a new draft continues; when a batch's fate is unknown, 'unknown_status', 'uncertain_lines' and 'row_errors' name the rows whose outcome has to be checked first. PARTIAL_APPLY and UNKNOWN_OUTCOME come from platforms without transactional writes: part of the change is in the account ('created' names it), or a create was never answered. The plan is retired; read the account back and draft only what is missing. APPLY_IN_PROGRESS means an earlier call claimed this plan first, so this call executed nothing.

Approval cards: in AI apps that show AdLoop's approval card with the preview, dry_run=false is REFUSED with status APPROVE_ON_CARD, because only the user's click on the card applies the change. Dry runs still work. The workspace owner can allow approval in chat as well.

Confirmation dialogs: in apps that show dialogs instead, dry_run=false first asks the user in a dialog. A declined dialog returns NOT_CONFIRMED; an app that receives the dialog but never answers it gets CONFIRMATION_UNANSWERED on the next call, with the ways out.

Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/

Let the user upload images (PNG, JPEG, GIF up to 5 MB) for ad assets.

For images without a public URL, such as a file on the user's computer or an image attached in the chat. An attached image cannot reach a tool, so the user drops the same file on the card. Apps that show AdLoop's cards display an upload card where the user drops the files; the card then posts the upload ids into the chat. On AdLoop Cloud in other apps the result carries an upload link for the user (or a coding agent, with curl). Uploads expire after a day. The ids go into upload_ids of draft_image_assets, or as "upload:" into the image fields of draft_reddit_ad. Returns the current uploads and how to add more.

Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/

Let the user upload a conversion CSV for an offline conversion upload.

For the CSV behind draft_upload_call_conversions or draft_upload_enhanced_conversions_for_leads when the file is not on the machine running AdLoop, as on AdLoop Cloud. Apps that show AdLoop's cards display an upload card where the user drops the .csv file; the card then posts the upload id into the chat. Other apps on AdLoop Cloud get an upload link for the user (or a coding agent, with curl). The file holds personal data (phone numbers, emails), so it is kept for two hours at most and deleted as soon as a draft has read it. Returns the CSV uploads waiting to be used and how to add one.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List the files the user uploaded to AdLoop that have not expired.

Returns each upload's upload_id, kind (image or csv), name, type, size, dimensions (images) or lines (CSVs) and hours until it expires: images last a day, conversion CSVs two hours or until a draft reads them. The ids of files the user sent through an upload link show up here.

Google Ads API: https://developers.google.com/google-ads/api/docs/start, Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Reddit Ads API: https://ads-api.reddit.com/docs/v3/

Draft marking a GA4 event as a key event (conversion), or changing an existing one — returns a PREVIEW.

The fix for "the event fires but isn't tracked as a conversion": attribution_check / validate_tracking diagnose it, this closes the loop. When the event already is a key event, the plan changes its counting method or default value instead and the preview shows before and after; nothing to change returns NO_CHANGE. Applies to future data only. Returns a preview with a plan_id and warnings; nothing changes until confirm_and_apply applies it.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Draft removing a GA4 key event so the event no longer counts as a conversion, returning a PREVIEW.

The event itself keeps firing and stays in event reports; only its key-event status goes, for future data (key events already recorded are not reclassified). The draft resolves the event name against the property's key events (keyEvents.list), so the preview names the exact key event, its counting method and create time; an unknown name returns the existing key events, and one GA4 marks as not deletable is refused. Returns a preview with a plan_id and warnings; nothing changes until confirm_and_apply applies it (GA4 Admin API keyEvents.delete).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Draft creating, changing or deleting a GA4 annotation (a note on a date or date range in GA4's charts), returning a PREVIEW.

Use it to mark what explains a change in the data: a site relaunch, a price change, a campaign start, a tracking fix. Create needs title and date; update and delete need the annotation's ID from list_ga4_annotations, and an update changes only the fields passed (the preview shows before and after). Annotations Google created itself cannot be changed. Nothing changes until confirm_and_apply applies it; the dry run re-reads the annotation and refuses if it was changed in GA4 after the preview. GA4 Admin API v1alpha (reportingDataAnnotations).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Draft registering, changing or archiving a GA4 custom dimension, returning a PREVIEW.

Registering makes an event parameter (EVENT scope), a user property (USER) or an ecommerce item parameter (ITEM) reportable as a dimension. Before anything reaches Google the draft refuses a parameter that is already registered, a taken display name and a full property (see list_ga4_custom_definitions), and the preview warns that GA4 fills the dimension only from now on and that parameter_name and scope cannot change later. Update changes display_name, description or (USER scope) disallow_ads_personalization; archive removes it from reports and frees the slot, cannot be undone and needs a double confirmation. Nothing changes until confirm_and_apply applies it. GA4 Admin API (customDimensions).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Draft registering, changing or archiving a GA4 custom metric, returning a PREVIEW.

Registering makes a numeric event parameter reportable as a metric. The draft refuses a parameter that is already registered, a taken display name and a full property (see list_ga4_custom_definitions), and the preview warns that GA4 fills the metric only from now on. Update changes display_name, description, measurement_unit or restricted_metric_type; archive removes it from reports, cannot be undone and needs a double confirmation. Nothing changes until confirm_and_apply applies it. GA4 Admin API (customMetrics).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Draft a change to how long GA4 keeps event- and user-level data, returning a PREVIEW.

GA4 defaults to 2 months, which cuts explorations, funnels and other user-level reports short; standard properties allow 14 months, GA4 360 up to 50. Standard reports are aggregated and not affected. Lengthening applies from now on (data already deleted does not come back); shortening deletes older data for good and needs a double confirmation. The preview shows before and after and reminds the user that a privacy policy naming a retention period must match. NO_CHANGE when the settings already match. Nothing changes until confirm_and_apply applies it; the dry run re-reads the settings and refuses if they changed in GA4 after the preview.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Admin API: https://developers.google.com/analytics/devguides/config/admin/v1

Draft a new Google Ads ConversionAction — returns a PREVIEW.

Returns a preview with a plan_id (plus warnings where relevant); nothing changes until confirm_and_apply applies it. SMART_CAMPAIGN_* and GOOGLE_HOSTED types are auto-managed by Google and rejected with MUTATE_NOT_ALLOWED.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a partial UPDATE of an existing ConversionAction — returns PREVIEW.

Only parameters passed non-empty/non-default are sent to the API. Covers renaming, demoting a Primary to Secondary, changing value, adjusting the call-duration threshold, or changing attribution. SMART_CAMPAIGN_* and GOOGLE_HOSTED types reject mutations with MUTATE_NOT_ALLOWED at apply time. Returns a preview with a plan_id (plus warnings where relevant); nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a REMOVAL of a ConversionAction — returns a PREVIEW.

Removal stops counting and drops the action from goal lists; historical data is preserved but the action is irreversible. SMART_CAMPAIGN_* and GOOGLE_HOSTED types reject removal with MUTATE_NOT_ALLOWED. Returns a preview with a plan_id; nothing changes until confirm_and_apply applies it.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft an offline CALL-conversion upload from a CSV — returns a PREVIEW.

Uploads call conversions via ConversionUploadService.UploadCallConversions, matching the call against the ad click by the caller's phone number. The CSV must have columns: Caller's Phone Number, Call Start Time, Conversion Name, Conversion Time, Conversion Value, Conversion Currency. The Conversion Name must match an existing UPLOAD_CALLS-type conversion action — verified against the account while drafting, so a typo fails here rather than after the upload. Optional Ad User Data and Ad Personalization columns carry consent per row.

The CSV comes from csv_path (a file on the machine running AdLoop) or from upload_id (a file uploaded with upload_conversion_csv, the only way on AdLoop Cloud). An uploaded file is deleted once the draft has read it.

PII: the caller phone number is required RAW by Google (it cannot be hashed), so it lives in the plan's apply-only payload — the preview shows redacted ids and counts, the audit log and plan.changes show neither. Apply uploads exactly what you previewed (no CSV re-read).

Phone numbers are normalized with libphonenumber semantics: a number carries no country code needs default_region, an extension is dropped, and the German trunk marker in "+49 (0)89 …" is handled. Rows whose number stays unusable are skipped and reported in skipped_rows instead of being uploaded to no effect.

Rows that repeat inside one file are named in dedup_warnings. A call upload has no dedup key at Google, so each of them still goes out as its own conversion — the warning is the only place that says so.

Returns a preview with a plan_id, the row counts, the consent the rows actually carry (consent_summary) and the skipped rows; nothing is uploaded until that preview is confirmed.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft an Enhanced Conversions for LEADS upload from a CSV — PREVIEW.

Uploads lead conversions via ConversionUploadService.UploadClickConversions with user_identifiers, matching hashed customer PII back to the Google users who clicked the ads. The CSV holds RAW PII in columns: Email, Phone Number, First Name, Last Name (plus Conversion Name, Conversion Time, Conversion Value, Conversion Currency; optional Order ID dedup key, and optional Ad User Data / Ad Personalization consent columns).

PII is normalized and SHA-256-hashed AT PREVIEW TIME — only the hashes are stored in the plan. Raw email/phone/name never land in the plan or the audit log. A cell that already is a SHA-256 hex digest (a CRM export that hashes before writing) is used as it is. The target conversion action must be UPLOAD_CLICKS-type.

An Order ID column makes re-uploads dedup instead of double-counting.

Rows that repeat inside one file are named in dedup_warnings. Rows sharing an Order ID count once at Google; two rows with different Order IDs are two real orders and are not reported.

The CSV comes from csv_path (a file on the machine running AdLoop) or from upload_id (a file uploaded with upload_conversion_csv, the only way on AdLoop Cloud). An uploaded file is deleted once the draft has read it.

Returns a preview with a plan_id, the row counts, the consent the rows actually carry (consent_summary) and the skipped rows; nothing is uploaded until that preview is confirmed.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Compare tracking events found in the codebase against actual GA4 data.

Takes the event names found in the codebase's gtag('event', ...) or dataLayer.push calls and checks which ones actually fire in GA4.

Returns matched events with their GA4 counts, events missing from GA4, unexpected GA4 events, auto-collected events (page_view, session_start, etc.), insights on likely causes, and the date range.

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start

Generate a GA4 event tracking JavaScript snippet.

Produces ready-to-paste gtag code for the specified event. Includes recommended parameters for well-known GA4 events (sign_up, purchase, etc.). Optionally checks GA4 to warn if the event already fires. Returns the javascript snippet, already_exists / existing_count from GA4, and notes (duplicates, marking it as a key event, GDPR consent).

Google Analytics Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 and Google Ads API: https://developers.google.com/google-ads/api/docs/start

Forecast clicks, cost, and conversions for a set of keywords.

Uses Google Ads Keyword Planner to estimate campaign performance without creating anything. Essential for budget planning before launching campaigns. Per-keyword max_cpc values are collapsed to a campaign-level manual CPC cap (the highest one) — the Ads API forecast takes no per-keyword bids. Returns estimated clicks, cost, avg CPC, conversions and avg CPA for the forecast period, daily estimates, and insights.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Discover new keyword ideas using Google Ads Keyword Planner.

Mirrors the "Discover new keywords" UI in Keyword Planner: start with keywords (seed_keywords), start with a website (url), or both together for more targeted ideas. At least one of seed_keywords or url is required.

Returns keyword ideas sorted by avg monthly search volume, with competition level (LOW/MEDIUM/HIGH) and top-of-page bid range, plus the seeds used and insights.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Resolve a brand name to the brands Google recognizes for it.

Mirrors the brand picker in the Google Ads UI (BrandSuggestionService.SuggestBrands): takes a free-text name such as "EscapeGame München" or "NoWayOut" and returns the matching brands with their ID, display name, state, and associated URLs.

The returned brand ID is the Commercial Knowledge Graph ID. Brand criteria — brand lists, brand exclusions — target that ID, not a display name, so a name is resolved here before it can go into a brand list.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Check a list of brand names against Google's brand knowledge graph.

One SuggestBrands call per name, for the case where a shortlist has to be triaged instead of a single name resolved: which of these brands does Google know at all, and what is the ID of each?

Returns checked / matched / no_match counts and one result per name with status "matched" (with a best-match brand plus all candidates) or "no_match" (empty candidate list — a normal answer, not an error). exact_match marks a candidate whose name matches the query apart from case and punctuation; anything else is a Google suggestion, not a guarantee.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List all brand lists (SharedSets of type BRANDS) in the account.

Returns each list's ID, name, status, and member count, plus the total — the basis for reusing an existing list with add_to_brand_list instead of duplicating it with propose_brand_list.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List the brands inside a brand list.

Returns the brands and their total. Each entry carries brand.entity_id (the Commercial KG MID that suggest_brands returns as id), the display name, primary URL, status and a criterion_id — the latter is what remove_from_brand_list needs.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

List which campaigns a brand list is attached to.

Brand lists attach as CampaignCriterion rows of type BRAND_LIST (not as CampaignSharedSet like negative keyword lists). Returns each attachment's campaign ID, name and status, the criterion, and role: "excluded" when the criterion is negative, "targeted" when it restricts targeting to the list.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Draft a brand list and optionally attach it to campaigns — returns a PREVIEW.

Creates a SharedSet of type BRANDS, fills it with brands, and — when campaign_ids is given — attaches it to those campaigns.

Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Append brands to an EXISTING brand list — returns a PREVIEW.

For a list that already exists and only needs more brands (propose_brand_list creates a new list instead). The shared_set_id comes from get_brand_lists; get_brand_list_brands shows the brands already in the list, which makes a brand that would be added twice visible.

Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Remove brands from a brand list — returns a PREVIEW.

SharedCriteria have no status field, so removal is the only way to take a brand out of a list — there is nothing to pause. Removing a brand does not detach the list from any campaign.

Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Attach an existing brand list to one or more campaigns — returns a PREVIEW.

Creates a CampaignCriterion.brand_list per campaign. This is NOT the CampaignSharedSet linkage used for negative keyword lists — brand lists are criteria, and negative decides the role. The shared_set_id comes from get_brand_lists; get_brand_list_campaigns lists existing attachments.

Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start

Detach a brand list from one or more campaigns — returns a PREVIEW.

Removes the CampaignCriterion rows linking the list to those campaigns; the list itself and its brands are unchanged. get_brand_list_campaigns lists the existing attachments.

Returns a preview with a plan_id; nothing changes until the returned plan_id is applied with confirm_and_apply.

Google Ads API: https://developers.google.com/google-ads/api/docs/start