Back to Help

How It Works

Technical explanation for advanced users who want to understand the internals.

The 30-Minute Timeout Constraint

Google Apps Script has a hard 30-minute execution limit. This is the fundamental constraint that shapes how the script works.

Why this matters: We can't process all accounts in a single run. Instead, we use gradual initialization (3 accounts per run) and hourly scheduling (distribute accounts across hours) to stay within limits.

High-Level Architecture

Data Flow

  1. 1. Script runs in MCC account (hourly trigger)
  2. 2. Reads settings tab to determine which accounts to process
  3. 3. For each account:
    • • Selects account via AdsManagerApp
    • • Runs GAQL queries to fetch data
    • • Processes and formats data
    • • Writes to individual account sheet
    • • Updates master sheet totals
  4. 4. Updates settings tab with timestamps and status

Initialization System (v92)

First Run

  • • Populates 'all' tab with all MCC accounts
  • • Auto-populates 'settings' tab (accounts with PMax Cost > 0)
  • • Sets run times: 15 accounts per hour starting at 03:00
  • • Auto-detects Demand Gen campaigns
  • • Processes first 3 accounts immediately
  • • Marks those 3 as Initialized = TRUE

Subsequent Hourly Runs

  • • Checks each account in settings tab
  • • If Initialized = FALSE: Process up to 3 accounts, mark as initialized
  • • If Initialized = TRUE: Check if current hour matches Run At time, then process
  • • This gradual approach ensures all accounts get initialized within hours, then update hourly

Hourly Processing Logic

The script uses a simple decision tree for each account:

IF Initialized = FALSE AND uninitializedCount < 3:
→ Process account (first proper run)
→ Mark Initialized = TRUE
→ Increment uninitializedCount
ELSE IF Initialized = TRUE AND currentHour = RunAt:
→ Process account (regular update)
ELSE:
→ Skip account (not time yet or already processed)

Maintenance Hour (23:00)

At 11pm (MCC timezone), the script enters maintenance mode instead of processing individual accounts:

  • • Refreshes 'all' tab if REFRESH_ALL_TAB = true
  • • Collects historical data for daily/weekly/trend tabs
  • • Aggregates metrics across all accounts
  • • Skips individual account processing

Performance Optimization

MAX_INIT_PER_RUN = 3

Limits initialization to 3 accounts per run. Keeps execution under 30 minutes even for large accounts.

PLACEMENT_LIMIT = 50,000

Fetches top 50,000 placements by impressions. Prevents timeout on accounts with millions of placements.

Run Time Distribution

Distributes 15 accounts per hour across 03-23. Spreads load and ensures all accounts update within 24 hours.

Security & Permissions

What Permissions Does the Script Need?

  • • Google Ads: Read access to MCC and client accounts (to fetch data)
  • • Google Sheets: Read/write access to your master sheet and individual account sheets
  • • No external services: All data stays within Google's ecosystem

The script runs under your Google account. Data is never sent to external servers. Sheet sharing is controlled by you.

Next Steps

Advanced configuration options →Troubleshooting guide →
Understanding the DataAdvanced Configuration→