Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mage.ai/llms.txt

Use this file to discover all available pages before exploring further.

Google Ads

​
Overview

This source syncs campaign, ad group, ad, keyword, and performance report data from the Google Ads API (v23). Authentication uses user OAuth (not service accounts) — the connector requires a refresh_token alongside a developer_token. Incremental state is handled inside the connector; stream-level INCREMENTAL selection is not available in the UI, but bookmarks still resume progress across syncs.

​
Authentication

This connector uses two kinds of credentials:
  • Application credential (developer_token) — identifies your app to the Google Ads API. Issued per manager account via API Center. This is not an OAuth token.
  • User OAuth (refresh_token, oauth_client_id, oauth_client_secret) — proves the user has consented to read their Ads data. The required OAuth scope is https://www.googleapis.com/auth/adwords.

​
Manual setup vs Mage OAuth Authorize

MethodWhat to set
Mage OAuth Authorize (recommended)Use the OAuth Authorize button on the source block. Mage injects refresh_token automatically. You only need developer_token and login_customer_ids. You may omit oauth_client_id and oauth_client_secret.
ManualCreate an OAuth 2.0 client in Google Cloud (Web or Desktop app type), obtain a refresh_token for the Ads scope, and fill in all three OAuth fields.
Service accounts and Application Default Credentials are not supported.

​
Configuration

KeyRequiredDefaultDescription
developer_token✅—Google Ads API application token from API Center. Not a user OAuth token.
oauth_client_idConditional—Google Cloud OAuth client ID. Required for manual OAuth setup; optional when using Mage OAuth Authorize.
oauth_client_secretConditional—Google Cloud OAuth client secret. Same conditions as oauth_client_id.
refresh_token✅—Long-lived user refresh token for the https://www.googleapis.com/auth/adwords scope. Injected automatically by Mage OAuth Authorize.
login_customer_ids✅—List of { customerId, loginCustomerId } pairs. customerId is the account to read; loginCustomerId is the manager (MCC) account used to access it, or null for direct access.
start_date✅—Fetch data newer than this date. Format: ISO 8601 (YYYY-MM-DDTHH:MM:SSZ).
end_datenowUpper bound for report syncs.
request_timeout900HTTP timeout in seconds for API calls.
conversion_window30Conversion attribution window in days. Allowed: 1–30, 60, 90.
query_limit1000000Max rows per query for core streams.

​
Sample configs

Using Mage OAuth Authorize (recommended — no OAuth client credentials needed): 
developer_token: YOUR_DEVELOPER_TOKEN
refresh_token: YOUR_REFRESH_TOKEN
start_date: '2023-01-01T00:00:00Z'
login_customer_ids:
  - customerId: '1234567890'
    loginCustomerId: null
Manual OAuth setup with manager account: 
developer_token: YOUR_DEVELOPER_TOKEN
oauth_client_id: YOUR_CLIENT_ID.apps.googleusercontent.com
oauth_client_secret: YOUR_CLIENT_SECRET
refresh_token: YOUR_REFRESH_TOKEN
start_date: '2023-01-01T00:00:00Z'
login_customer_ids:
  - customerId: '1234567890'
    loginCustomerId: '0987654321'

​
How to get login_customer_ids

customerId is the account whose data you want to sync. loginCustomerId is the manager (MCC) account you use to access it — leave it null when there is no manager hop.
  1. Sign in to Google Ads.
  2. Open the account switcher in the top bar.
  3. Copy the numeric ID for each account (strip dashes: 123-456-7890 → '1234567890').

​
How to get a developer_token

A developer token belongs to a manager (MCC) account. Client-only accounts cannot open API Center.
  1. Sign in to a manager account.
  2. Open API Center (Tools & Settings → Setup → API Center).
  3. Complete the API sign-up. Your token may start as Test tier; request Basic or Standard access when you are ready for production volume.
  4. Set the token as developer_token in your config.