Google Ads API Python automation: beginner's guide

The Google Ads API supports 10,000 operations per day per client account in Basic Access and a max 1-hour timeout per query, vs 30 minutes CPU and 50 scripts max for Google Ads Scripts (official API quota documentation). On accounts observed in public Google Ads benchmarks, data teams that move from Scripts to API in Python recover 5 to 12 hours per week on reporting and audit pipelines, and unlock use cases impossible on the Scripts side (BigQuery sync, batch mutations of 5,000+ entities, bidirectional CRM integration).

This guide is a step-by-step Python setup for beginners. Here are the exact commands to paste, the OAuth snippet that works on the first try, the first GAQL query, and the public GitHub repo to fork to get started. No marketing theory, no "discover the infinite possibilities of the API" — just code that runs. Prerequisites: Python 3.9+, a Google Ads account, 30 minutes. If you're already comfortable with Google Ads Scripts, first read our guide to 10 ready-to-paste Google Ads Scripts which lays the automation foundations the API will extend. Our wasted ad spend calculator estimates the $ burned/month from broad without negatives or excessive LP bounce.

Why the Google Ads API when Scripts already exists?

Google Ads Scripts is powerful but constrained: 30 minutes CPU max per run, 50 active scripts max per account, JavaScript ES5 (no npm packages), no access to external scientific libs (numpy, pandas, scikit-learn). The Google Ads API is the level above: Python, Java, Go, .NET or Ruby of your choice, possible integration with any data stack (BigQuery, Snowflake, Airflow, dbt), batch operations, async, vertical and horizontal scaling without limit on Google's side.

The switch criterion is simple. Stay on Scripts if: you monitor 1 account or a restricted MCC, your automations fit in 30 minutes runtime, you don't need external Python libs, your team doesn't want to maintain infrastructure. Move to the API if: you manage 10+ accounts to steer in parallel, you sync with a data warehouse (BigQuery, Snowflake), you integrate a CRM (HubSpot, Salesforce) bidirectionally, or you expose Google Ads operations in an internal product (dashboard, automation tool).

The operational sweet spot: use Scripts for single-account monitoring and simple automations (budget alerts, auto negatives), move to the API for data pipelines, multi-account, CRM integration. On accounts observed in public Google Ads benchmarks, about 30 to 40% of mature structures (above $500k/year of spend) combine both: Scripts for daily tactical, API for weekly strategic and data syncs.

A frequent question in training: "I already have 4-5 Scripts running, do I have to migrate everything?" The pragmatic answer is no. Migration to the API is only profitable if you gain capability (multi-account, data warehouse, scientific libs) or you're losing time on Scripts limitations (30 min timeout, no pandas). For a mid-size account with Scripts running well, keeping the code in place and adding the API only on new use cases is the strategy that minimizes risk. Both pipelines coexist without conflict: Scripts runs on Google's side, your API runs on your infrastructure side, they don't step on each other.

The other often-forgotten trade-off concerns total cost of ownership. Scripts is free on the infrastructure side (Google hosts), but requires JavaScript in a limited sandbox — so dev hours to work around limitations. The API requires Python, infrastructure (Cloud Run, Lambda, EC2, or simple VPS cron), monitoring, secrets management, and dependencies to maintain. Over 12 months, an API Python setup for 3-5 scripts typically costs between $300 and $1,200 in cloud infrastructure, plus 20 to 60 hours of dev/maintenance. Beyond 10 scripts or 20 accounts to steer, the ROI clearly tips toward the API.

Python environment setup: OAuth2, credentials, library

The setup fits in 6 steps: create a GCP project, generate OAuth2 credentials, retrieve the Google Ads developer_token, install the library, generate the refresh_token, test with a GAQL query. Allow 30 minutes for everything. Here is the exact procedure.

Step 1 — GCP project and API activation

On console.cloud.google.com, create a new project (any name, e.g. google-ads-api-prod). In APIs and Services > Library, search "Google Ads API" and click Enable. The API is free, but requires explicit per-project GCP activation.

Step 2 — OAuth2 credentials (Desktop app type)

In APIs and Services > Credentials, click Create Credentials > OAuth client ID. Type: Desktop app. Give it an explicit name (e.g. google-ads-api-cli). Download the JSON, keep client_id and client_secret. These two values will feed google-ads.yaml.

Step 3 — Developer token on the Google Ads side

In Google Ads, Tools and Settings > API Center. If not already done, request a developer_token. The initial token is in Test mode (15,000 ops/day, test accounts only). To move to Basic Access (10,000 ops/day, prod accounts), submit a request with use case description — Google responds within 1 to 5 business days. For Standard Access (unlimited), allow 2 to 4 weeks of review.

Step 4 — Install library and generate refresh_token

Install the official library:

# Python 3.9+ required
pip install google-ads
# Verify version (24.0.0+ corresponds to API v17)
pip show google-ads

To generate the refresh_token, the simplest way is to use the official auth script provided by Google:

# Clone the official examples
git clone https://github.com/googleads/google-ads-python.git
cd google-ads-python/examples/authentication

# Run the generation script
python generate_user_credentials.py \
  --client_id YOUR_CLIENT_ID \
  --client_secret YOUR_CLIENT_SECRET

The script opens an OAuth page in your browser. Validate access to the Google Ads account. The script prints a refresh_token in the format 1//0g...XXXXX. Copy it immediately, it will only display once.

Step 5 — Configure google-ads.yaml

Create a google-ads.yaml file at the project root:

# google-ads.yaml — ADD TO .gitignore IMMEDIATELY
developer_token: "YOUR_DEVELOPER_TOKEN_22_CHARS"
client_id: "YOUR_CLIENT_ID.apps.googleusercontent.com"
client_secret: "GOCSPX-YOUR_CLIENT_SECRET"
refresh_token: "1//0gYOUR_REFRESH_TOKEN"
login_customer_id: "1234567890"  # parent MCC without dashes
use_proto_plus: true

The login_customer_id is the ID of your parent MCC without dashes (e.g. 123-456-7890 becomes 1234567890). It's the account under which the API authenticates each request. If you query a client account of this MCC, you'll specify the client account's customer_id in the request itself.

Step 6 — Test the setup with a simple query

# test_setup.py
from google.ads.googleads.client import GoogleAdsClient

CUSTOMER_ID = "1112223333"  # client account ID (not the MCC)

def test_connection():
    client = GoogleAdsClient.load_from_storage("google-ads.yaml")
    ga_service = client.get_service("GoogleAdsService")

    query = """
        SELECT campaign.id, campaign.name, campaign.status
        FROM campaign
        LIMIT 5
    """

    response = ga_service.search(customer_id=CUSTOMER_ID, query=query)
    for row in response:
        print(f"{row.campaign.id} | {row.campaign.name} | {row.campaign.status.name}")

if __name__ == "__main__":
    test_connection()

Run python test_setup.py. If you see 5 campaign names displayed, the setup is good. If INVALID_CUSTOMER_ID error, check the format (10 digits without dashes). If NOT_ADS_USER error, the refresh_token is tied to a Google account that doesn't have access to the specified customer_id.

First GAQL query: campaign performance

GAQL (Google Ads Query Language) is the query language of the Google Ads API. SQL-like syntax but with specifics: no explicit JOIN (resources are nested), hierarchized fields (campaign.id, metrics.clicks, segments.date), and a DURING for date ranges instead of WHERE date BETWEEN.

Here's a complete script that pulls performance of ENABLED campaigns over the last 30 days, with impressions, clicks, cost, conversions, CTR, CPC, CPA. Our 2-input CPA calculator returns the value + French median for your vertical.

# pull_campaign_performance.py
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

CUSTOMER_ID = "1112223333"

def pull_performance(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")

    query = """
        SELECT
            campaign.id,
            campaign.name,
            campaign.status,
            metrics.impressions,
            metrics.clicks,
            metrics.cost_micros,
            metrics.conversions,
            metrics.conversions_value,
            metrics.ctr,
            metrics.average_cpc
        FROM campaign
        WHERE campaign.status = 'ENABLED'
          AND segments.date DURING LAST_30_DAYS
        ORDER BY metrics.cost_micros DESC
        LIMIT 50
    """

    try:
        response = ga_service.search(customer_id=customer_id, query=query)

        results = []
        for row in response:
            cost_usd = row.metrics.cost_micros / 1_000_000  # micros -> USD
            cpa = cost_usd / row.metrics.conversions if row.metrics.conversions > 0 else None

            results.append({
                "id": row.campaign.id,
                "name": row.campaign.name,
                "impressions": row.metrics.impressions,
                "clicks": row.metrics.clicks,
                "cost_usd": round(cost_usd, 2),
                "conversions": row.metrics.conversions,
                "ctr_pct": round(row.metrics.ctr * 100, 2),
                "cpc_usd": round(row.metrics.average_cpc / 1_000_000, 2),
                "cpa_usd": round(cpa, 2) if cpa else None,
            })

        return results

    except GoogleAdsException as ex:
        print(f"Request failed: {ex.error.code().name}")
        for error in ex.failure.errors:
            print(f"  - {error.message}")
        raise

if __name__ == "__main__":
    client = GoogleAdsClient.load_from_storage("google-ads.yaml")
    perf = pull_performance(client, CUSTOMER_ID)

    for c in perf:
        print(f"{c['name'][:40]:40s} | "
              f"{c['impressions']:>8,} impr | "
              f"{c['clicks']:>5,} clicks | "
              f"{c['cost_usd']:>7,.2f} USD | "
              f"{c['conversions']:>5.1f} conv | "
              f"CPA: {c['cpa_usd']}")

Three critical points on this query. First: costs are in micros (1 USD = 1,000,000 micros). Always divide by 1_000_000 to get USD. Second: metrics.ctr is a float between 0 and 1, multiply by 100 to get a percentage. Third: the DURING LAST_30_DAYS clause is equivalent to WHERE segments.date BETWEEN '2026-03-28' AND '2026-04-26' but much more readable. The list of DURING constants: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_MONTH, LAST_MONTH, etc. (complete list).

Three additional traps often encountered when starting with GAQL. *Trap 1: no SELECT . The API requires you to explicitly declare each field. Listing 25 fields by hand is verbose but it's intentional — Google wants to limit bandwidth and force the advertiser to know what they consume. Maintaining a reusable CAMPAIGN_FIELDS = [...] Python constant avoids rewriting the list in every script. Trap 2: segments.date always introduces row-fanning. A query without segments.date aggregates over the entire DURING period; with segments.date, you get one row per campaign per day, so 30x more rows. Choose consciously based on need (period totals vs time series). Trap 3: ORDER BY is mandatory for consistent pagination. The API automatically paginates beyond 10,000 rows; without an explicit ORDER BY, page order isn't guaranteed and you risk missing entities during batch processing.

To test other GAQL queries interactively without Python, Google provides a GAQL Query Builder in the official documentation — it's the fastest way to iterate on query structure before coding it. A practical tip: prototype the query in the query builder, copy-paste into your Python script, and only then add the mapping to your BigQuery columns or pandas. Avoid rewriting the query three times while debugging because you forgot a field.

Mutations: create, update, pause a campaign

Mutations are the API's write operations: create a campaign, modify a budget, pause a keyword, add a negative. They go through dedicated services (CampaignService, CampaignBudgetService, KeywordPlanService, etc.) and use the operation > mutation > response pattern.

Here's a script that pauses a campaign by its ID:

# pause_campaign.py
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

CUSTOMER_ID = "1112223333"
CAMPAIGN_ID = "111222333"

def pause_campaign(client, customer_id, campaign_id):
    campaign_service = client.get_service("CampaignService")

    # Build resource_name (mandatory format)
    resource_name = campaign_service.campaign_path(customer_id, campaign_id)

    # Operation: update
    campaign_operation = client.get_type("CampaignOperation")
    campaign = campaign_operation.update
    campaign.resource_name = resource_name
    campaign.status = client.enums.CampaignStatusEnum.PAUSED

    # Field mask (specify what we update)
    client.copy_from(
        campaign_operation.update_mask,
        protobuf_helpers.field_mask(None, campaign._pb),
    )

    try:
        response = campaign_service.mutate_campaigns(
            customer_id=customer_id,
            operations=[campaign_operation],
        )
        print(f"Paused campaign: {response.results[0].resource_name}")

    except GoogleAdsException as ex:
        for error in ex.failure.errors:
            print(f"Error: {error.message}")
            if error.location:
                for field in error.location.field_path_elements:
                    print(f"  Field: {field.field_name}")
        raise

if __name__ == "__main__":
    from google.api_core import protobuf_helpers
    client = GoogleAdsClient.load_from_storage("google-ads.yaml")
    pause_campaign(client, CUSTOMER_ID, CAMPAIGN_ID)

The critical pattern for ALL mutations: resource_name + update_mask. The resource_name identifies the entity (customers/{customer_id}/campaigns/{campaign_id}), the update_mask specifies which fields are being modified (without it, the API returns INVALID_FIELD_MASK). The protobuf_helpers.field_mask(None, campaign._pb) automatically generates the mask from modified fields.

To create a new campaign (Standard Search, daily budget $100, Manual CPC):

# create_search_campaign.py
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException
import uuid

CUSTOMER_ID = "1112223333"

def create_campaign_budget(client, customer_id, daily_budget_usd):
    budget_service = client.get_service("CampaignBudgetService")
    operation = client.get_type("CampaignBudgetOperation")
    budget = operation.create
    budget.name = f"Budget {uuid.uuid4().hex[:8]}"
    budget.amount_micros = int(daily_budget_usd * 1_000_000)
    budget.delivery_method = client.enums.BudgetDeliveryMethodEnum.STANDARD

    response = budget_service.mutate_campaign_budgets(
        customer_id=customer_id, operations=[operation]
    )
    return response.results[0].resource_name

def create_search_campaign(client, customer_id, name, budget_resource):
    campaign_service = client.get_service("CampaignService")
    operation = client.get_type("CampaignOperation")
    campaign = operation.create

    campaign.name = name
    campaign.advertising_channel_type = client.enums.AdvertisingChannelTypeEnum.SEARCH
    campaign.status = client.enums.CampaignStatusEnum.PAUSED  # create as PAUSED, activate after review
    campaign.manual_cpc.enhanced_cpc_enabled = False
    campaign.campaign_budget = budget_resource

    # Network settings
    campaign.network_settings.target_google_search = True
    campaign.network_settings.target_search_network = True
    campaign.network_settings.target_content_network = False
    campaign.network_settings.target_partner_search_network = False

    response = campaign_service.mutate_campaigns(
        customer_id=customer_id, operations=[operation]
    )
    return response.results[0].resource_name

if __name__ == "__main__":
    client = GoogleAdsClient.load_from_storage("google-ads.yaml")

    budget_rn = create_campaign_budget(client, CUSTOMER_ID, daily_budget_usd=100)
    print(f"Budget created: {budget_rn}")

    campaign_rn = create_search_campaign(
        client, CUSTOMER_ID, "Test API Campaign", budget_rn
    )
    print(f"Campaign created (PAUSED): {campaign_rn}")

Mutation best practices:

• Always create as PAUSED initially, activate manually after review. A campaign accidentally created as ENABLED can spend the budget in a few hours.
• Log the resource_name returned by the API for traceability.
• Wrap in try/except GoogleAdsException systematically (see retry section).
• Test on a test account before touching prod. The API doesn't offer a native dry-run mode (unlike Scripts).

Error handling and retry logic in production

The Google Ads API can return 3 categories of errors: transient (RESOURCE_EXHAUSTED, DEADLINE_EXCEEDED, UNAVAILABLE) which justify a retry with backoff, client errors (INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED) which will never retry successfully, and rate limit (TOO_MANY_REQUESTS) which require waiting for the next window.

Here's an exponential retry wrapper to paste in all production scripts:

# retry_helpers.py
import time
from functools import wraps
from google.ads.googleads.errors import GoogleAdsException
from google.api_core.exceptions import (
    DeadlineExceeded, ServiceUnavailable, ResourceExhausted
)

RETRYABLE_ERRORS = (
    DeadlineExceeded,
    ServiceUnavailable,
    ResourceExhausted,
)

def with_retry(max_retries=3, base_delay=2.0, max_delay=60.0):
    """
    Decorator that automatically retries with exponential backoff
    on transient Google Ads API errors.
    """
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries + 1):
                try:
                    return func(*args, **kwargs)

                except RETRYABLE_ERRORS as e:
                    if attempt == max_retries:
                        print(f"[RETRY] Max retries reached: {e}")
                        raise

                    delay = min(base_delay * (2 ** attempt), max_delay)
                    print(f"[RETRY] Attempt {attempt + 1}/{max_retries} "
                          f"failed: {type(e).__name__}. Retry in {delay}s...")
                    time.sleep(delay)

                except GoogleAdsException as e:
                    # Check if error is retryable (rate limit notably)
                    is_retryable = any(
                        err.error_code.quota_error or
                        err.error_code.internal_error
                        for err in e.failure.errors
                    )

                    if is_retryable and attempt < max_retries:
                        delay = min(base_delay * (2 ** attempt), max_delay)
                        print(f"[RETRY] GoogleAdsException retryable. "
                              f"Retry in {delay}s...")
                        time.sleep(delay)
                    else:
                        # Non-retryable client error
                        for error in e.failure.errors:
                            print(f"[ERROR] {error.error_code}: {error.message}")
                        raise

            return None

        return wrapper
    return decorator

# Usage
@with_retry(max_retries=3, base_delay=2.0)
def pull_performance_safe(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = "SELECT campaign.id, campaign.name FROM campaign LIMIT 100"
    return list(ga_service.search(customer_id=customer_id, query=query))

The pattern: exponential backoff (delay doubles on each retry, capped at 60 seconds) + error classification (retryable vs non-retryable). Never retry on INVALID_ARGUMENT — it's a bug in your code, not a network problem. Never retry indefinitely — 3 to 5 retries max, otherwise you mask a structural problem (token revoked, quota permanently exhausted).

For structured logging, use standard Python logging with a JSON format for ingestion in an observability stack (Datadog, Grafana Loki):

import logging
import json

class JsonFormatter(logging.Formatter):
    def format(self, record):
        log_obj = {
            "ts": self.formatTime(record),
            "level": record.levelname,
            "msg": record.getMessage(),
            "module": record.module,
        }
        if record.exc_info:
            log_obj["exc"] = self.formatException(record.exc_info)
        return json.dumps(log_obj)

logger = logging.getLogger("google_ads_api")
handler = logging.StreamHandler()
handler.setFormatter(JsonFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# Usage
logger.info("Pulled 247 campaigns", extra={"customer_id": CUSTOMER_ID})

OAuth refresh flow: what gets forgotten in production

The Google Ads refresh_token doesn't expire as long as it's used at least once every 6 months. However, it can be revoked in several cases worth knowing. First case: the Google user who generated the token changes their password or MFA — all refresh_tokens tied to that account become invalid. Second case: Google detects suspicious behavior (token used from 30 different IPs in 1 hour, for example), automatically revokes and sends a security email. Third case: exceeding the limit of 50 active refresh_tokens simultaneously per OAuth client triggers a silent FIFO that invalidates the oldest ones. That's why we recommend a dedicated technical service account for the API (never an employee's personal Google account), with stable password and hardware key MFA.

The retry pattern on auth errors must be different from transient network retry. If you receive UNAUTHENTICATED or PERMISSION_DENIED tied to the token, NEVER retry with backoff — the token won't resurrect. Instead, trigger an alert (PagerDuty, Slack ops) and let a human regenerate the refresh_token via the generate_user_credentials.py script. Confusing these two cases can cost hours of debug and lost conversions. To limit surprises, monitor token health with a simple cron: a minimal GAQL query (SELECT customer.id FROM customer LIMIT 1) every 6 hours, alert on auth failure.

Rate limiting: understanding quotas in practice

API quotas are structured at two levels: operations per day (Test 15,000, Basic 10,000 per client account, Standard officially unlimited but throttled around 1 million/day) and requests per second (soft limit around 50 RPS sustained per OAuth client, below which the API returns without error). One operation = one mutated row, one get, or one page of GAQL results. A GAQL query returning 5,000 rows counts as 1 operation, not 5,000.

The most frequent trap in production: batch mutations exceeding 5,000 operations in a single call. The API then returns RESOURCE_EXHAUSTED not because of the daily quota but because of a per-call limit of 5,000 operations. The correct pattern is to chunk the lists: if you have 12,000 negative keywords to add, make 3 calls of 4,000 keywords rather than a single call of 12,000. Chunking adds 5 lines of code and avoids 90% of errors in bulk operations.

# Chunking pattern for batch mutations
def chunked(iterable, size=4000):
    for i in range(0, len(iterable), size):
        yield iterable[i:i + size]

for chunk in chunked(all_operations, size=4000):
    response = service.mutate_negatives(
        customer_id=customer_id, operations=chunk
    )
    print(f"Chunk processed: {len(response.results)} mutations")

For nightly batch pipelines, adding a time.sleep(0.5) between chunks smooths the load without degrading global throughput. On accounts observed in public Google Ads benchmarks, a batch of 50,000 mutations chunked at 4k + 500ms sleep runs in approximately 8-10 minutes vs 4-5 minutes in 4k chunks without sleep — but with a failure rate divided by 5. The time/reliability tradeoff is well worth the sleep.

6 ready-to-fork Python scripts

To accelerate the start, we publish a public GitHub repo github.com/steerads/google-ads-python-starter with 6 documented Python scripts, ready to fork. Each script is standalone, configured via env vars, with retry logic included. Here's the list with an example snippet for each.

Script 1 — Pull campaign performance LAST_30_DAYS

Pulls full KPIs (impressions, clicks, cost, conversions, ROAS) of ENABLED campaigns, exports to CSV or pushes to BigQuery. Frequency: daily or hourly. See full snippet in section 3.

Script 2 — Bulk update campaign budget

Modifies daily budgets of N campaigns in a single batch operation. Useful for monthly budget rebalancing or automatic seasonal adjustments.

# bulk_update_budgets.py
def bulk_update_budgets(client, customer_id, updates):
    """
    updates = [{"budget_id": "111", "new_amount_usd": 150}, ...]
    """
    service = client.get_service("CampaignBudgetService")
    operations = []

    for u in updates:
        op = client.get_type("CampaignBudgetOperation")
        budget = op.update
        budget.resource_name = service.campaign_budget_path(
            customer_id, u["budget_id"]
        )
        budget.amount_micros = int(u["new_amount_usd"] * 1_000_000)

        client.copy_from(
            op.update_mask,
            protobuf_helpers.field_mask(None, budget._pb),
        )
        operations.append(op)

    response = service.mutate_campaign_budgets(
        customer_id=customer_id, operations=operations
    )
    return [r.resource_name for r in response.results]

Script 3 — Add negative keywords from search query report

Pulls the Search Term Performance Report over 30 days, identifies queries with 0 conversion and over 15 clicks, adds them as negatives at campaign level. Equivalent to script 2 of our 10 ready-to-copy Scripts guide, but in API to handle 100+ campaigns in a single run.

Script 4 — Pause underperforming keywords (CTR + CPA)

Identifies keywords with CTR below 1% AND CPA above 2x target CPA over 30 days, pauses them automatically with a pre-action log. Multi-dimensional criterion impossible on the Scripts side (which forces iterating on AdsApp.keywords()), trivial in GAQL.

Script 5 — Export report to BigQuery (data warehousing)

Pulls aggregated metrics, transforms with pandas, loads into BigQuery via google-cloud-bigquery. This is the use case where the API surpasses Scripts: impossibility of cleanly connecting Scripts to BigQuery, while on the Python side it's 10 lines.

# bigquery_export.py
from google.cloud import bigquery
import pandas as pd

def export_to_bigquery(client, customer_id, dataset_id, table_id):
    # 1. Pull GAQL data
    perf = pull_performance(client, customer_id)
    df = pd.DataFrame(perf)
    df["snapshot_date"] = pd.Timestamp.today().normalize()

    # 2. BigQuery client
    bq = bigquery.Client()
    table_ref = f"{bq.project}.{dataset_id}.{table_id}"

    # 3. Load with append
    job_config = bigquery.LoadJobConfig(
        write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
        autodetect=True,
    )
    job = bq.load_table_from_dataframe(df, table_ref, job_config=job_config)
    job.result()  # wait for completion

    print(f"Loaded {len(df)} rows to {table_ref}")

Script 6 — Daily monitoring with Slack alerts

Combines pull performance + check anomalies (spend, CPA, conversions) + push Slack via webhook if anomaly detected. Industrialized equivalent of a daily monitoring cron job.

# daily_monitoring.py
import requests

SLACK_WEBHOOK = "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

def detect_anomalies(perf):
    alerts = []
    for c in perf:
        # Spend > 2x avg 7d
        if c.get("cost_usd", 0) > c.get("avg_cost_7d", 0) * 2:
            alerts.append(f"Spend +100% : {c['name']}")
        # CPA > 3x target
        if c.get("cpa_usd") and c.get("target_cpa") and \
           c["cpa_usd"] > c["target_cpa"] * 3:
            alerts.append(f"CPA x3 target : {c['name']}")
    return alerts

def send_slack(alerts):
    if not alerts:
        return
    msg = "Google Ads anomalies detected:\n" + "\n".join(f"- {a}" for a in alerts)
    requests.post(SLACK_WEBHOOK, json={"text": msg})

if __name__ == "__main__":
    client = GoogleAdsClient.load_from_storage("google-ads.yaml")
    perf = pull_performance(client, CUSTOMER_ID)
    alerts = detect_anomalies(perf)
    send_slack(alerts)

The repo github.com/steerads/google-ads-python-starter contains for each script: complete documented code, a README with step-by-step setup, a .env.example file for variables, and a pinned requirements.txt for reproducibility. For cross-platform automation, also see our n8n Google Ads automation flows guide and our MCP Google Ads + Claude Desktop guide to steer Google Ads conversationally from Claude.

When to move from Scripts to API

Moving from Scripts to API isn't a systematic upgrade — it's a tradeoff choice. Here are the 5 concrete triggers observed in public benchmarks during audits.

Trigger 1: multi-account (10+ accounts to steer in parallel). Scripts is mono-account by essence (one script attached to one account or one MCC). Beyond 10 accounts to sync, the Python API with a for loop on the customer_ids list becomes much simpler to maintain.

Trigger 2: data warehousing. If you want to push metrics to BigQuery, Snowflake, Redshift, the API is mandatory. Scripts UrlFetchApp can technically call a REST API, but GCP authentication, batching, ETL with pandas — that requires Python.

Trigger 3: bidirectional CRM integration. To push offline conversions from Salesforce/HubSpot, the Google Ads API supports OfflineUserDataJobService which does secure batch upload. See our Google Ads conversion tracking guide for the functional framework.

Trigger 4: advanced ML / stats needs. Statistical anomaly detection (ARIMA, Prophet), keyword segmentation (clustering), spend forecasting — all these tasks require numpy/pandas/scikit-learn, impossible in Scripts.

Trigger 5: internal product. You're building a dashboard or internal tool that displays/manipulates Google Ads data. Necessarily API — Scripts can't expose a UI or respond to an HTTP request.

For the 5 reverse cases (single account, simple monitoring, no data needs, non-tech team, constrained infrastructure), Scripts remains superior in cost/maintenance. Our Microsoft Ads Scripts guide covers the equivalent on the Microsoft side.

For accounts that want to industrialize without coding their own stack, our Auto-optimization module covers the equivalent of the 6 scripts above in managed mode: multi-account pull performance, anomaly detection, Slack alerts, BigQuery sync, without a line of Python to maintain. Also see our Google Ads audit checklist for the audit basis that must precede any automation, and our Zapier vs Make comparison for complementary no-code automations.

Common mistakes to avoid when starting with the API

Five recurring mistakes slow down Python beginners on the Google Ads API. Each costs on average several hours of avoidable debug if you know the trap in advance. Here's the list with diagnosis and direct correction.

1. Confusing customer_id and login_customer_id. Diagnosis: the script returns INVALID_CUSTOMER_ID or NOT_ADS_USER while everything seems well configured. Correction: login_customer_id (in the YAML) = ID of the parent MCC under which the API authenticates, without dashes. customer_id (in the request) = ID of the client account you want to query, without dashes. If you query an account directly that isn't under an MCC, put its ID in both places. Always remove dashes from format 123-456-7890 -> 1234567890.

2. Forgetting update_mask on mutations. Diagnosis: the mutation fails with MISSING_REQUIRED_FIELD: update_mask or all entity fields are replaced with their defaults (catastrophe in prod). Correction: for any update operation, generate the mask via protobuf_helpers.field_mask(None, entity._pb) after setting the fields. The mask declares to the API which fields you're modifying; without it, the API either refuses, or interprets as "all fields are at their default value" and resets everything.

3. Looping in individual pull instead of batch. Diagnosis: a script that should pull 500 campaigns takes 25 minutes instead of 30 seconds. Correction: NEVER do for campaign_id in ids: ga_service.search(...) with one query per campaign. Instead, a single GAQL query that filters WHERE campaign.id IN (...) or pulls everything and filters on the Python side. The API isn't penalized on query size, it's penalized on the number of calls.

4. Testing directly in prod without a test account. Diagnosis: a rounding bug in budget mutation code accidentally drops all budgets to $1. Prod burns. Correction: create a test Google Ads account (free, no associated CC) for all dev mutations. The Test developer_token only covers test accounts — which is a welcome involuntary protection. Only switch to Basic Access after validating the code in sandbox on 2-3 real use cases.

5. Ignoring GAQL pagination beyond 10,000 rows. Diagnosis: a script that pulls keywords from a large account crashes beyond 10k rows or returns incomplete without error. Correction: use ga_service.search_stream(...) which paginates automatically without loading the entire result into memory. For 50,000+ row pulls, it's mandatory — search() loads everything in memory and will crash on low-RAM machines.

For official documentation, see the Google Ads API portal and the official google-ads-python repo which contains dozens of Google-maintained examples.

Sources

Official sources consulted for this guide:

• modelcontextprotocol.io
• schema.org
• blog.google
• anthropic.com

FAQ