# google-ads

> Query and audit Google Ads accounts via API. Use for conversion tracking analysis, campaign performance, ROAS optimization, and SEM audits. Enforces verification methodology: NEVER draw conclusions from configuration alone—always cross-reference against actual metrics behavior.

- Author: james-claw
- Repository: james-claw/sem-manager
- Version: 20260206114349
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/james-claw/sem-manager
- Web: https://mule.run/skillshub/@@james-claw/sem-manager~google-ads:20260206114349

---

---
name: google-ads
description: "Query and audit Google Ads accounts via API. Use for conversion tracking analysis, campaign performance, ROAS optimization, and SEM audits. Enforces verification methodology: NEVER draw conclusions from configuration alone—always cross-reference against actual metrics behavior."
---

# Google Ads

Query and audit Google Ads accounts with mandatory verification methodology.

## Setup

```bash
cd {baseDir}
pip install google-ads google-auth-oauthlib

# First-time auth (opens browser)
python scripts/setup_auth.py \
  --developer-token YOUR_TOKEN \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_SECRET \
  --login-customer-id 1234567890
```

Requires:
- Developer token (from Google Ads API Center in MCC)
- OAuth client credentials (from GCP project with Google Ads API enabled)
- google-ads.yaml in working directory or ~/.google-ads.yaml

## Core Scripts

### Conversion Audit (REQUIRED for conversion analysis)

**Always use this instead of querying settings alone:**

```bash
python scripts/audit_conversions.py --customer-id 678-005-3379
python scripts/audit_conversions.py --customer-id 678-005-3379 --days 30 --format json
python scripts/audit_conversions.py --customer-id 678-005-3379 --filter "BIN Tier"
```

Cross-references configuration against actual metrics. Flags discrepancies.

### Campaign Performance

```bash
python scripts/campaign_performance.py --customer-id 678-005-3379
python scripts/campaign_performance.py --customer-id 678-005-3379 --target-roas 1.48 --min-cost 100
```

### Raw GAQL Queries

```bash
python scripts/query.py "SELECT campaign.name, metrics.cost_micros FROM campaign" --customer-id 678-005-3379
python scripts/query.py --file queries/my_query.sql --customer-id 678-005-3379 --format table
```

## Verification Methodology

**See `references/verification-methodology.md` for full details.**

Before making ANY claim about what's being used for bidding:

1. Query configuration (conversion action settings)
2. Query behavior (`metrics.conversions` vs `metrics.all_conversions`)
3. Compare—if they disagree, trust behavior
4. Flag discrepancies for investigation

**Do NOT:**
- Trust `include_in_conversions_metric` alone
- Conclude from API fields without checking actual metrics
- Assume configuration reflects effective behavior

## Quick Reference

### Conversion Metrics Interpretation

| Metric | Meaning |
|--------|---------|
| `conversions` | Used for Smart Bidding |
| `all_conversions` | All tracked (including secondary) |

If action appears in `conversions` → it's being used for bidding.  
If only in `all_conversions` → tracking only.

### Common Tasks

| Task | Script |
|------|--------|
| Audit conversions | `audit_conversions.py` |
| Campaign ROAS check | `campaign_performance.py --target-roas X` |
| Raw data query | `query.py "GAQL..."` |

## References

- `references/verification-methodology.md` - REQUIRED reading before analysis
- `references/gaql-reference.md` - Query language syntax and examples
- `references/conversion-hierarchy.md` - Goals, actions, settings hierarchy