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.

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)

If you are using the Google Ads Audiences API — Data Manager destination, make sure your connection is configured with the correct Customer ID (Google Ads account ID). If you copy it from the Google Ads UI with hyphens (for example, 123-456-7890), Extract will normalize it automatically.

Configuration​

Provide the following configuration values when setting up the Google Ads source:

  • client_id: Your Google OAuth client ID.
  • client_secret: Your Google OAuth client secret.
  • token: The OAuth refresh token obtained during authorization.
  • developer_token: Your Google Ads API developer token.
  • backfill: Number of days to backfill for date-partitioned streams.

Optional:

  • accounts_to_sync: A list of Google Ads customer IDs to sync. If omitted, the connector will sync all accessible customers.
  • invoice_month_lookback: Number of months to look back when syncing invoices. Defaults to 2.
  • reports: A list of custom report definitions. Each report must include:
    • name: A unique name for the report.

    • query: A GAQL query in the following format:

      • SELECT <field>[, <field> ...] FROM <resource> [WHERE <conditions>]

      Requirements for query:

      • The query must be a single SELECT ... FROM ... statement (optionally with a WHERE clause).
      • The SELECT list must be a comma-separated list of field names (letters/numbers/_/.), for example: campaign.id, metrics.clicks, segments.date.
      • The FROM resource must be a single resource name (letters/numbers/_), for example: campaign.
      • If you include a WHERE clause, it must be on the same statement (no additional clauses like ORDER BY, LIMIT, or multiple statements).

      Notes:

      • If your selected fields include segments.date, the connector may add an additional date filter during validation to test the query.

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
  • If an audience with the same name already exists in Google Ads, the connector will reuse it. If the existing audience’s identifier type does not match the stream’s data contract, the sync will fail and you must use a different audience name (or update the existing audience to match).

Troubleshooting​

If you’re using custom reports (the reports parameter) and validation fails, check the formatting of your GAQL query. The connector validates queries using a strict pattern and will reject queries that don’t match it exactly.

Your query must be a single GAQL statement in the form:

SELECT field1, field2, field3 FROM resource_name [WHERE ...]
  • Missing SELECT / FROM or extra clauses
    Only SELECT ... FROM ... with an optional WHERE ... is supported. Queries that include other clauses (for example ORDER BY, LIMIT, GROUP BY, etc.) will fail validation.

  • Invalid field list formatting

    • Fields must be comma-separated.
    • Each field must be a simple identifier like campaign.id or segments.date (letters/numbers/underscore/dot).
    • Avoid *, functions, aliases, or expressions (for example campaign.id AS id, COUNT(...), etc.).
  • Invalid resource name after FROM
    The resource name must be a single identifier (for example campaign, customer, ad_group_ad) and cannot contain dots or spaces.

  • Leading/trailing text or multi-statement queries
    The query must contain only the GAQL statement (no surrounding text, no multiple statements).

Notes about WHERE​

  • WHERE is optional, but if present it must come after FROM.
  • If you include segments.date in the selected fields, the connector may add an additional date filter during validation/extraction. If you also provide your own WHERE, ensure it can be combined with an additional AND ... date condition.