/google-ads-scripts

name: google-ads-scripts
description: Google Ads Scripts Reference — JavaScript automation, AdsApp object model, selectors, GAQL queries, 10+ working script patterns, MCC parallel processing, Sheets integration
version: "1.1.1"
author: Cogny AI
platforms: []
user-invocable: true
argument-hint: "<script pattern or topic>"
allowed-tools:
  - WebSearch
  - Read
  - Write
  - Bash
  # Google Ads tools (when connected via Cogny MCP)
  - mcp__cogny__list_integrations
  - mcp__cogny__refresh_mcp_discovery
  - mcp__cogny__mcp__Google_Ads__tool_execute_gaql
  - mcp__cogny__mcp__Google_Ads__tool_get_gaql_doc
  - mcp__cogny__mcp__Google_Ads__tool_get_reporting_view_doc
  - mcp__cogny__mcp__Google_Ads__tool_list_accessible_accounts
  - mcp__cogny__get_script_sdk_reference
  - mcp__cogny__mcp__Bing_Ads__tool_get_report

Google Ads Scripts Reference

Complete reference for Google Ads Scripts: JavaScript automation within Google Ads, AdsApp object model, selectors and iterators, GAQL queries, common script patterns with working code, Google Sheets integration, MCC parallel processing, and best practices.

Full docs: https://cogny.com/docs/google-ads-scripts

Usage

/google-ads-scripts                          # Full overview
/google-ads-scripts budget pacing            # Budget pacing monitor script
/google-ads-scripts negative keywords        # Search term negative keyword miner
/google-ads-scripts quality score tracker    # Quality score logging to Sheets
/google-ads-scripts MCC parallel             # MCC parallel processing pattern
/google-ads-scripts selectors                # Selector and iterator patterns
/google-ads-scripts GAQL                     # GAQL queries in scripts
/google-ads-scripts anomaly detection        # Anomaly alerting script

Instructions

You are a Google Ads Scripts expert. Use this reference to help users write, debug, and optimize Google Ads Scripts. Provide complete, working code with proper error handling and best practices.

When the user asks a question, find the relevant section below and provide precise, actionable answers with ready-to-use JavaScript code.

If the user provides a specific topic as an argument, focus on that area. Otherwise, provide an overview of capabilities and common patterns.

Key principles:

• Always include a `DRY_RUN` flag in scripts that modify the account
• Log changes before making them
• Use `try/catch` for error handling
• Prefer GAQL (`AdsApp.search()`) for complex queries
• Batch Google Sheets writes for performance
• Remind users about the 30-minute execution limit (60 min for MCC)

Run it live

If Cogny isn't connected, skip this and note what connecting adds.

• **Test the query first.** With Google Ads connected, run a script's GAQL through

`mcp__cogny__mcp__Google_Ads__tool_execute_gaql` before pasting it into the Scripts UI.

• **Schedule it in Cogny instead (Cloud, when the workspace flag is on).** Read

`mcp__cogny__get_script_sdk_reference`, then `mcp__cogny__create_script` / `mcp__cogny__create_automation` (writes: not pre-approved, ask first). Anything that writes to the account asks first.

• **Microsoft Ads** has its own Scripts product with a similar `AdsApp` model but no GAQL;

check its API before porting. For reads, `mcp__cogny__mcp__Bing_Ads__tool_get_report` covers the same campaign, keyword and search-query data.

---

Overview

Google Ads Scripts let you programmatically control Google Ads using JavaScript. Scripts run directly inside the Google Ads web interface — no external server, API keys, or OAuth needed.

**Key capabilities:**

• Read and modify campaigns, ad groups, ads, keywords, extensions
• Query performance data using GAQL (Google Ads Query Language)
• Integrate with Google Sheets for dashboards and logging
• Send email alerts via MailApp
• Make HTTP requests via UrlFetchApp
• Run on a schedule (hourly, daily, weekly, monthly)

**Single-account vs MCC scripts:**

| Feature | Single-Account | MCC Script | |---------|---------------|------------| | Scope | One account | All accounts under MCC | | Entry point | `main()` | `main()` with `AdsManagerApp` | | Execution limit | 30 minutes | 60 minutes | | Parallel execution | No | Yes, `executeInParallel()` |

**Language:** Scripts run on the V8 runtime (ECMAScript 6+), so modern JavaScript works: `let`/`const`, arrow functions, template literals, destructuring, `class`. No `import`/`export` or npm modules, and Ads services (`AdsApp`, `UrlFetchApp`, `SpreadsheetApp`) are synchronous, so `async`/`await` buys nothing. The examples below use ES5-style `var`, which also runs fine.

**Dates:** `Utilities.formatDate()` doesn't use the account's time zone by default. Always pass `AdsApp.currentAccount().getTimeZone()`, or "today" and "yesterday" can be off by a day versus the account's reporting.

AdsApp Object Model

The `AdsApp` object is the root of all single-account operations.

Entity Hierarchy

AdsApp
  +-- campaigns()
  |     +-- adGroups()
  |     |     +-- ads()
  |     |     +-- keywords()
  |     |     +-- audiences()
  |     +-- extensions()
  +-- adGroups()        (account-level shortcut)
  +-- ads()             (account-level shortcut)
  +-- keywords()        (account-level shortcut)
  +-- negativeKeywords()
  +-- shoppingCampaigns()
  +-- videoCampaigns()
  +-- labels()
  +-- budgets()
  +-- biddingStrategies()

Common Entity Methods

// Status
entity.isEnabled()
entity.isPaused()
entity.isRemoved()
entity.enable()
entity.pause()
entity.remove()

// Naming
entity.getName()
entity.setName('New Name')

// Stats (requires date range)
entity.getStatsFor('LAST_30_DAYS')
entity.getStatsFor('20250101', '20250131')

// Stats object methods
var stats = entity.getStatsFor('LAST_30_DAYS');
stats.getImpressions()
stats.getClicks()
stats.getCtr()
stats.getAverageCpc()
stats.getCost()
stats.getConversions()
stats.getConversionRate()

Selectors and Iterators

Every entity collection uses the