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

Method	What 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`.
Manual	Create 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.

INCREMENTAL Sync

This source handles state internally, meaning INCREMENTAL sync selection is not supported.

Configuration

Key	Required	Default	Description
`developer_token`	✅	—	Google Ads API application token from API Center. Not a user OAuth token.
`oauth_client_id`	Conditional	—	Google Cloud OAuth client ID. Required for manual OAuth setup; optional when using Mage OAuth Authorize.
`oauth_client_secret`	Conditional	—	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_date`		now	Upper bound for report syncs.
`request_timeout`		`900`	HTTP timeout in seconds for API calls.
`conversion_window`		`30`	Conversion attribution window in days. Allowed: `1`–`30`, `60`, `90`.
`query_limit`		`1000000`	Max 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.

Sign in to Google Ads.
Open the account switcher in the top bar.
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.

Sign in to a manager account.
Open API Center (Tools & Settings → Setup → API Center).
Complete the API sign-up. Your token may start as Test tier; request Basic or Standard access when you are ready for production volume.
Set the token as developer_token in your config.

Google Ads API — Get Started
OAuth with Google Ads API
Developer token access levels
Manager accounts overview To set up the Google Ads source, provide the following configuration parameters:

Key	Description	Sample Value	Required
`login_customer_ids`	A list containing both `customerId` and `loginCustomerId` from Google Ads.	`"login_customer_ids": [{"customerId": "1234567890", "loginCustomerId": "0987654321"}]`	✅
`oauth_client_id`	OAuth client ID from Google Cloud.	`XXXXXXXXXXXX-YYYYYYYYYYYYYYYYYYYYYY.apps.googleusercontent.com`	✅
`oauth_client_secret`	OAuth client secret from Google Cloud.	`abc...`	✅
`refresh_token`	Google API refresh token, obtainable from Google OAuth Playground.	`abc...`	✅
`developer_token`	Google Ads developer token.	`abc...`	✅
`start_date`	Fetch data newer than the specified `start_date`. Format: ISO8601 (`YYYY-MM-DDTHH:MM:SSZ`).	`2022-01-01T00:00:00Z`	✅

Generating Credentials

Check out this article
by Sudeep Timalsina for a great guide on generating credentials for Google Ads API access.

Adventure starts here

Concepts

Project

Contributing

About

Overview

Authentication

Manual setup vs Mage OAuth Authorize

Service accounts and Application Default Credentials are not supported.

INCREMENTAL Sync

Configuration

Sample configs

How to get `login_customer_ids`

How to get a `developer_token`

Generating Credentials

​Overview

​Authentication

​Manual setup vs Mage OAuth Authorize

​Service accounts and Application Default Credentials are not supported.

​INCREMENTAL Sync

​Configuration

​Sample configs

​How to get login_customer_ids

​How to get a developer_token

​Related links

​Generating Credentials

Overview

Authentication

Manual setup vs Mage OAuth Authorize

Service accounts and Application Default Credentials are not supported.

INCREMENTAL Sync

Configuration

Sample configs

How to get `login_customer_ids`

How to get a `developer_token`

Related links

Generating Credentials