Skip to main content

Google Ads

info

API Documentation: Google Ads API Documentation

The Google Ads API allows you to access data related to your advertising accounts, campaigns, ad groups, ads, keywords, and performance metrics.

Source Setup Guide​

Click banner in the Edit Source form to the left.

Step 2​

Follow the authentication flow (OAuth) on Google’s website to grant Extract the required permissions.

Step 3​

Confirm you can see your email and profile picture, and that the source is Connected.

Step 4 - (Optional) Limit which accounts are synced​

By default, Extract will discover and sync all accessible (non-manager) customer accounts available to the authenticated Google Ads user.

If you want to sync only specific accounts, configure Accounts to sync (accounts_to_sync) with a list of Google Ads Customer IDs to include.

Notes:

  • Customer IDs are the numeric Google Ads account IDs (often shown with dashes in the UI, e.g. 123-456-7890). Use the format your Extract UI expects; the connector treats them as strings.
  • Any accounts not in this list will be skipped.

Step 5 - Custom Reports​

You can create custom reports from the Google Ads API, tailored to your specific needs.

  • Simplified configuration: Extract uses Google Ads Query Language (GAQL), allowing you to build reports using familiar SELECT and FROM statements.
  • Extensive options: Explore report options through the Google Ads Query Builder.

Before saving your custom report, you can use the Google Ads Query Validator to:

  1. Set up your query: Define the specific data you want to retrieve from Google Ads.
  2. Validate your query: Ensure the structure of your query is correct and will return the desired results.
warning
  • The segments.date field is managed automatically by our extraction process and should not be used in the WHERE clause.
  • When segments.date is included automatically, it enables Date Partition load mode; otherwise, the system will perform a Full Refresh.
  • When segments.date is included, the data stream will start from the backfill date set in your connection settings.
  • Custom reports currently do not support LIMIT, ORDER BY, or PARAMETERS statements.

Connection Setup Guide​

Once you connected Google Ads to a destination, you will also need to configure:

  • Connection Pull Schedule: Determines how frequently data is extracted from the source.
  • Backfill (Days): Specifies the duration for which historical data will be retrieved during each connection run.
  • Destination-specific settings: Settings such as “Dataset Name” or “Target Schema” (depending on your destination).
  • Schema Migration Policy: Controls how Extract will handle schema changes from the source.

If you are using the Google Ads Audiences destination to load Mobile ID (mobile advertising ID) custom audiences, you must also provide an App ID stream parameter:

  • Android: use the app’s package name (for example, com.example.app)
  • iOS: use the numeric App Store ID (for example, 123456789)

Connector Information​

Schema ERD​

Explore the interactive entity relationship diagram for Google Ads.

Open page

Data Streams​

ad_group_ad_asset_conversions​

Loading ....

ad_group_ad_asset_stats​

Loading ....

ad_group_ad​

Loading ....

ad_group_conversion_stats​

Loading ....

ad_group_criterion_label​

Loading ....

ad_group_criterion​

Loading ....

ad_group_stats​

Loading ....

ad_group​

Loading ....

ad_stats​

Loading ....

asset​

Loading ....

billing_setup​

Loading ....

campaign_budget​

Loading ....

campaign_conversion_stats​

Loading ....

campaign_criterion​

Loading ....

campaign_label​

Loading ....

campaign_shared_set​

Loading ....

campaign_stats​

Loading ....

campaign​

Loading ....

change_event​

Loading ....

change_status​

Loading ....

conversion_action​

Loading ....

customer_label​

Loading ....

customer_stats​

Loading ....

customer​

Loading ....

geo_target​

Loading ....

invoice_account_budget_summaries​

Loading ....

invoice_account_summaries​

Loading ....

invoices​

Loading ....

keyword_conversion_stats​

Loading ....

keyword_stats​

Loading ....

label​

Loading ....

mobile_device​

Loading ....

operating_system_version​

Loading ....

shared_criterion​

Loading ....

shared_set​

Loading ....

topic​

Loading ....

user_interest​

Loading ....

user_list​

Loading ....

Notes​

  • This connector requires a data contract to be attached to the stream. Streams without a data contract are not supported.
  • Google Ads Customer Match audiences are created/selected based on the data contract’s identifier type:
    • Contact info (for example, email/phone)
    • CRM ID
    • Mobile advertising ID (Android Advertising ID / iOS IDFA)
  • For Mobile advertising ID audiences, you must also provide the stream parameter app_id:
    • Android: use the app’s package name (for example, com.example.app)
    • iOS: use the numeric App Store ID