Google Ads

1. Authenticate
2. Verify your setup
3. Discover your customers
4. Explore campaigns
5. Run a GAQL query
6. Stream to CSV
Google Guide
Google Workflows

Step 01

Authenticate

Google Ads requires a developer token, OAuth client ID, OAuth client secret, and OAuth refresh token. Store them once in your OS credential store:

Primary command

Authenticate

bash

agent-ads google auth set

Or set shell variables for the current process:

bash

export GOOGLE_ADS_DEVELOPER_TOKEN=devtoken...
export GOOGLE_ADS_CLIENT_ID=client-id.apps.googleusercontent.com
export GOOGLE_ADS_CLIENT_SECRET=client-secret
export GOOGLE_ADS_REFRESH_TOKEN=refresh-token

Optional defaults:

bash

export GOOGLE_ADS_DEFAULT_CUSTOMER_ID=1234567890
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=1112223333

Step 02

Verify your setup

Add --api to exchange the refresh token and ping the Google Ads API.

Primary command

Verify your setup

bash

agent-ads google doctor

Add --api to exchange the refresh token and ping the Google Ads API.

Step 03

Discover your customers

Primary command

Discover your customers

bash

agent-ads google customers list
agent-ads google customers hierarchy --customer-id 1234567890

Step 04

Explore campaigns

Primary command

Explore campaigns

bash

agent-ads google campaigns list --customer-id 1234567890

Step 05

Run a GAQL query

Primary command

Run a GAQL query

bash

agent-ads google gaql search \
  --customer-id 1234567890 \
  --query "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks FROM campaign"

Step 06

Stream to CSV

Primary command

Stream to CSV

bash

agent-ads google gaql search-stream \
  --customer-id 1234567890 \
  --query-file campaign-query.sql \
  --format csv \
  --output google-report.csv

Reference

Google Ads guides

2 guides — exact flags, auth details, and workflow notes.

Guide

Google Guide

This is the provider guide for Google Ads. Read this first when the user wants to work with Google Ads through agent-ads.

This is the provider guide for Google Ads. Read this first when the user wants to work with Google Ads through agent-ads.

Start Here

Task	First command
Set up auth or inspect config	`agent-ads google doctor`
List accessible customers	`agent-ads google customers list`
Explore a customer hierarchy	`agent-ads google customers hierarchy --customer-id <id>`
List campaigns, ad groups, or ads	`agent-ads google campaigns list --customer-id <id>`
Run a provider-native query	`agent-ads google gaql search --customer-id <id> --query "..."`
Stream a large query result	`agent-ads google gaql search-stream --customer-id <id> --query-file query.sql`
Follow an end-to-end recipe	See google-workflows.md

Auth Model

Google Ads uses four credential pieces:

Credential	Persistent storage	Shell override
Developer token	`agent-ads google auth set`	`GOOGLE_ADS_DEVELOPER_TOKEN`
OAuth client ID	`agent-ads google auth set`	`GOOGLE_ADS_CLIENT_ID`
OAuth client secret	`agent-ads google auth set`	`GOOGLE_ADS_CLIENT_SECRET`
OAuth refresh token	`agent-ads google auth set`	`GOOGLE_ADS_REFRESH_TOKEN`

agent-ads exchanges the refresh token for an access token on demand. It does not persist access tokens.

Optional defaults:

Variable / config	Purpose
`GOOGLE_ADS_DEFAULT_CUSTOMER_ID` / `providers.google.default_customer_id`	Default customer for scoped commands
`GOOGLE_ADS_LOGIN_CUSTOMER_ID` / `providers.google.login_customer_id`	Manager account header for scoped requests

Command Model

customers list is discovery: it lists directly accessible customer resource names.
customers hierarchy is a convenience GAQL wrapper over customer_client.
campaigns list, adgroups list, and ads list are convenience GAQL wrappers with curated default fields.
gaql search and gaql search-stream are the native Google escape hatches for anything more complex.
Keep Google commands provider-native. Do not remap them into insights query.

Pagination

Google uses page-token pagination:

Flag	Meaning
`--page-token <token>`	Resume from `nextPageToken`
`--all`	Follow all pages
`--max-items <n>`	Stop after N rows

Google search returns fixed-size API pages, so there is no page-size override.

gaql search-stream does not use page tokens; use --max-items if needed.

Common Mistakes

Forgetting one of the four required Google credential pieces
Expecting a cross-provider insights query surface; for Google, use gaql search
Omitting login_customer_id when querying through a manager account

Guide

Google Workflows

End-to-end recipes for Google Ads. Each workflow is a sequence of commands you can run in order.

First command

Google Workflows

bash

# Step 1: List all accessible customers
agent-ads google customers list --all --pretty

# Step 2: Explore a customer hierarchy (manager accounts)
agent-ads google customers hierarchy --customer-id 1234567890 --all

1. Account Discovery

Start from your credentials and discover all accessible customers:

bash

# Step 1: List all accessible customers
agent-ads google customers list --all --pretty

# Step 2: Explore a customer hierarchy (manager accounts)
agent-ads google customers hierarchy --customer-id 1234567890 --all

If you query through a manager account, set login_customer_id in config or pass GOOGLE_ADS_LOGIN_CUSTOMER_ID.

2. Campaign Overview

bash

# List campaigns
agent-ads google campaigns list --customer-id 1234567890

# List ad groups
agent-ads google adgroups list --customer-id 1234567890

# List ads
agent-ads google ads list --customer-id 1234567890

3. GAQL Performance Report

Pull campaign metrics with a native GAQL query:

bash

agent-ads google gaql search \
  --customer-id 1234567890 \
  --query "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS"

For a longer query, put it in a file:

bash

agent-ads google gaql search \
  --customer-id 1234567890 \
  --query-file campaign-report.sql \
  --all

4. Streaming Large Results to CSV

search-stream avoids page-token overhead for large result sets:

bash

agent-ads google gaql search-stream \
  --customer-id 1234567890 \
  --query "SELECT ad_group.id, ad_group.name, metrics.impressions, metrics.clicks FROM ad_group WHERE segments.date DURING LAST_30_DAYS" \
  --format csv \
  --output adgroup-report.csv

5. CI / Automation Pattern

bash

#!/bin/bash
set -euo pipefail

# Verify setup
agent-ads google doctor --api -q

# Pull yesterday's campaign data
agent-ads google gaql search-stream \
  --customer-id 1234567890 \
  --query "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date = '$(date -d yesterday +%Y-%m-%d)'" \
  --format csv \
  --output /data/google-yesterday.csv

echo "Report saved to /data/google-yesterday.csv"

Exit codes make it safe in set -e scripts: 0 = success, 1 = transport/internal, 2 = config/argument, 5 = Google API error.

6. Piping and Composing

bash

# Pretty-print to less
agent-ads google campaigns list --customer-id 1234567890 --pretty | less

# Filter with jq
agent-ads google campaigns list --customer-id 1234567890 --all \
  | jq '.[] | select(.campaign.status == "ENABLED")'

# Count enabled campaigns
agent-ads google campaigns list --customer-id 1234567890 --all \
  | jq '[.[] | select(.campaign.status == "ENABLED")] | length'