Skip to content
T1KTheOneKit

t1k:marketing:monetization:googleads

FieldValue
Modulemonetization
Version1.16.9
Efforthigh
Tools—

How to invoke

Section titled “How to invoke”
/t1k:marketing:monetization:googleads

Google Ads API (Reporting)

Section titled “Google Ads API (Reporting)”

Pull campaign, account, and conversion reporting from the Google Ads API for monetization/UA dashboards.

When to Use

Section titled “When to Use”
  • Reporting advertiser/UA spend, impressions, clicks, conversions, CPC, and ROAS from Google Ads accounts
  • Building campaign-, account-, or conversion-level dashboards from GAQL queries
  • Enumerating accessible Google Ads accounts (account picker, MCC manager trees)
  • Converting cost_micros to account currency for spend reporting

Not for publisher ad-revenue/eCPM dashboards — that is Google Ad Manager (a different product/API). See the first gotcha.

Overview & When to Use — Google Ads API vs Google Ad Manager

Section titled “Overview & When to Use — Google Ads API vs Google Ad Manager”

This skill covers the Google Ads API (developers.google.com/google-ads/api) — advertiser/campaign data: UA spend, clicks, conversions, ROAS. It is NOT Google Ad Manager (admanager), the publisher ad-serving/ad-revenue product. For a pure ad-revenue/eCPM monetization dashboard (publisher impressions revenue), Google Ad Manager API is the correct network. The signal Google Ads API surfaces — UA spend and conversions — is arguably closer to a ua concern than monetization; confirm dashboard intent before classifying.

Reference: https://developers.google.com/google-ads/api/docs/reporting/overview

Auth Setup: OAuth2 + Developer Token + login-customer-id

Section titled “Auth Setup: OAuth2 + Developer Token + login-customer-id”

Every REST call requires two headers:

  • Authorization: Bearer <ACCESS_TOKEN> — OAuth2 access token, refreshed from a long-lived refresh token
  • developer-token: <DEVELOPER_TOKEN> — issued from the Google Ads API Center, gated by access level (Test/Explorer/Basic/Standard)

When a manager (MCC) account calls a client account, add login-customer-id: <MANAGER_CUSTOMER_ID> (digits only, no hyphens). Analytics/data partners on linked accounts add linked-customer-id: <ADVERTISER_CUSTOMER_ID>.

OAuth2 supports three flows: service-account (own accounts via domain-wide delegation), single-user (one refresh token), and multi-user (per-user refresh tokens). The access token is obtained from Google’s standard OAuth2 token endpoint (https://oauth2.googleapis.com/token) using client_id + client_secret + refresh_token.

Credentials needed: OAuth2 client_id, client_secret, refresh_token (per authorized user/account), developer_token, target customer_id (digits only), and login_customer_id (manager/MCC, when applicable).

References: https://developers.google.com/google-ads/api/docs/oauth/overview · https://developers.google.com/google-ads/api/rest/auth

Base URL & Versioning

Section titled “Base URL & Versioning”
  • Reporting base: https://googleads.googleapis.com
  • OAuth2 token refresh: https://oauth2.googleapis.com/token

The API version is pinned in the URL path (/v{N}/...). Current production version is v24 (mid-2026); v20/v21 appear in older indexed pages. Google deprecates versions on a rolling ~quarterly cadence — always substitute a current version and watch the deprecation schedule.

GAQL Fundamentals

Section titled “GAQL Fundamentals”

Google Ads Query Language (GAQL): SELECT <fields> FROM <resource> WHERE <conditions> [DURING <date_range>] [ORDER BY ...] [LIMIT ...].

  • Resources — the FROM object (campaign, ad_group, customer). Dimensions live under their resource object in the response (campaign{}, customer{}).
  • Metrics — metrics.cost_micros, metrics.impressions, metrics.clicks, metrics.conversions, metrics.average_cpc, metrics.conversions_value, etc. Nested under metrics{} in the response.
  • Segments — breakdowns like segments.date, segments.device, segments.ad_network_type. Nested under segments{}.
  • Date macros: DURING LAST_7_DAYS, DURING LAST_30_DAYS, or explicit segments.date BETWEEN '2026-01-01' AND '2026-01-31'.

Each metric requires compatible segments/resources — incompatible field combos return query-validation errors. Consult the per-version Reports/fields reference (/google-ads/api/fields/v{N}/overview) for compatibility.

References: https://developers.google.com/google-ads/api/rest/common/search · https://developers.google.com/google-ads/api/docs/reporting/example

Section titled “SearchStream vs Search”
  • GoogleAdsService.SearchStream — POST /v{N}/customers/{CUSTOMER_ID}/googleAds:searchStream. Streams the entire result set of a GAQL query in a single chunked JSON-array response (no pagination, no pageSize). Preferred for bulk dashboard reporting. The parser must iterate chunks — the response is an array of { results: [...], fieldMask, requestId } chunks, not a single object.
  • GoogleAdsService.Search — POST /v{N}/customers/{CUSTOMER_ID}/googleAds:search. Paginated equivalent: fixed pages up to 10,000 rows via pageToken/pageSize. Same GAQL semantics and row shape; returns { results: [...], nextPageToken, fieldMask, totalResultsCount }. Use when you need page-at-a-time control or smaller responses.

Reference: https://developers.google.com/google-ads/api/rest/reference/rest/v20/customers.googleAds/searchStream

Core Reporting Recipes

Section titled “Core Reporting Recipes”

Campaign cost/clicks/conversions (segmented by date):

SELECT campaign.name, campaign.status, segments.date,
       metrics.impressions, metrics.clicks, metrics.conversions,
       metrics.average_cpc, metrics.cost_micros
FROM campaign
WHERE segments.date BETWEEN '2026-01-01' AND '2026-01-31'
ORDER BY segments.date

Account summary (roll-up + currency/timezone context):

SELECT customer.id, customer.descriptive_name, customer.currency_code,
       customer.time_zone, metrics.cost_micros, metrics.impressions,
       metrics.clicks, metrics.conversions
FROM customer
WHERE segments.date DURING LAST_30_DAYS

Conversion / ROAS breakdown by campaign:

SELECT campaign.name, segments.date, metrics.conversions,
       metrics.conversions_value, metrics.cost_per_conversion,
       metrics.cost_micros
FROM campaign
WHERE segments.date BETWEEN '2026-01-01' AND '2026-01-31'

ROAS = conversions_value / (cost_micros / 1,000,000).

Device / network segmentation: add segments.device or segments.ad_network_type to the SELECT and they appear under segments{}.

Cost-in-Micros Conversion + Currency/Timezone

Section titled “Cost-in-Micros Conversion + Currency/Timezone”

metrics.cost_micros (and metrics.cost_per_conversion) are in micros: divide by 1,000,000 to get currency units. Apply customer.currency_code for the unit and customer.time_zone to interpret segments.date. Pull these from the customer resource (SELECT customer.currency_code, customer.time_zone FROM customer) so dashboards label spend correctly.

Account Enumeration & MCC Manager-Tree Traversal

Section titled “Account Enumeration & MCC Manager-Tree Traversal”

CustomerService.ListAccessibleCustomers — GET /v{N}/customers:listAccessibleCustomers. Lists every customer resource name the authenticated OAuth credential can reach. No customer ID in the path — driven entirely by the OAuth token + developer token. Returns { resourceNames: ["customers/1234567890", ...] }.

Use it to enumerate accounts before reporting (account picker / multi-account dashboards). For MCC manager trees, set login-customer-id to the manager account and query each accessible client account (e.g. via customer_client resource for full tree expansion).

Reference: https://developers.google.com/google-ads/api/rest/auth

Rate Limits & Quota by Access Level

Section titled “Rate Limits & Quota by Access Level”

Quota is per developer token, tiered by access level:

  • Explorer (formerly Test): 2,880 production ops/day, 15,000/day against test accounts
  • Basic: 15,000 ops/day (test + production combined)
  • Standard: higher limits negotiated with Google

Limits cover combined search/searchStream + mutate operations. Rejected GoogleAdsFailure requests still consume quota (network-level failures do not). Over-quota error: RESOURCE_EXHAUSTED (HTTP 429). The gRPC/response hard cap is 64MB → also RESOURCE_EXHAUSTED; narrow date ranges or segment queries for large accounts. Exact per-minute/concurrent numbers are dynamic and not published as fixed values.

Reference: https://developers.google.com/google-ads/api/docs/best-practices/quotas

Mapping Fields to a Monetization Dashboard

Section titled “Mapping Fields to a Monetization Dashboard”
Dashboard metricGoogle Ads field
Spendmetrics.cost_micros / 1,000,000 (× customer.currency_code)
CPCmetrics.average_cpc / 1,000,000
eCPM (derived)(cost_micros / 1,000,000) / impressions × 1000
Conversionsmetrics.conversions
Conversion valuemetrics.conversions_value
ROASconversions_value / (cost_micros / 1,000,000)
Cost per conversionmetrics.cost_per_conversion / 1,000,000

Gotchas

Section titled “Gotchas”
  • Google Ads API ≠ Google Ad Manager. This API gives advertiser/UA spend + conversions, not publisher IAA ad-revenue/eCPM. For a pure ad-revenue monetization dashboard, use the Google Ad Manager API instead. Double-check the dashboard’s intent before classifying the signal as monetization vs ua.
  • metrics.cost_micros is in MICROS — always divide by 1,000,000 and apply customer.currency_code. Forgetting this inflates spend 1,000,000×.
  • customer_id and login_customer_id must be digits only — strip hyphens from the 123-456-7890 display format.
  • API version is in the URL path and Google deprecates older versions on a rolling ~quarterly cadence — pin a current version (v24 as of mid-2026) and watch the deprecation schedule.
  • SearchStream does NOT support pageSize and returns a streamed JSON array of chunks, not a single object — the parser must iterate chunks.
  • Daily operation quota is per developer token by access level (Explorer 2,880 prod ops/day; Basic 15,000) — and rejected GoogleAdsFailure requests still consume quota.
  • gRPC/response hard cap 64MB → RESOURCE_EXHAUSTED — narrow date ranges or segment queries for large accounts.
  • Test-access developer tokens can only hit test accounts — production reporting needs Basic+ access (apply via API Center, manual review).
  • Each metric requires compatible segments/resources — incompatible field combos return query-validation errors; consult the per-version Reports reference for field compatibility.

References

Section titled “References”