Skip to main content

Google Ads

Google Ads is Google's online advertising platform that enables businesses to create and manage advertising campaigns across Google Search, Display Network, YouTube, and other Google properties. With Google Ads, you can reach potential customers at the moment they're searching for products or services like yours, display visual ads across millions of websites, and track campaign performance with detailed analytics.

This connector provides comprehensive access to the Google Ads API v23, enabling you to programmatically manage campaigns, ad groups, keywords, ads, budgets, and access detailed performance reports.

Authentication Types​

Google Ads supports 1 authentication method:

  • OAuth 2.0 - Standard OAuth authentication with Google Ads API scope
    • Pros: Secure, user-authorized access to Google Ads accounts
    • Cons: Requires both OAuth credentials AND a Developer Token; initial setup is more complex
    • Best for: Programmatic campaign management, automated reporting, and integration with other systems

General Settings​

Before using the Google Ads connector, you need to configure two critical settings:

Developer Token​

A Developer Token is a unique 22-character alphanumeric string required for every Google Ads API call. It identifies your application to Google and controls your API access level.

How to get your Developer Token:

  1. Sign in to your Google Ads account
  2. Click the Tools & Settings icon in the top right
  3. Under Setup, click API Center
  4. Your Developer Token is displayed at the top of the page
  5. Copy the token (format: 1234567890ABCDEFGHIJ)

Access Levels:

  • Test Access (default) - Can only access test accounts; limited to 15,000 operations/day
  • Basic Access - Can access production accounts with up to 15,000 operations/day
  • Standard Access - Unlimited operations for approved applications
tip

If your Developer Token has "Test Access" level, you'll need to apply for Basic or Standard access to use it with production Google Ads accounts. This requires demonstrating API usage and may take a few days for Google to review.

Customer ID​

Your Customer ID is a unique 10-digit identifier for your Google Ads account (sometimes called Client Customer ID). This determines which account the API calls will be made against.

How to find your Customer ID:

  1. Sign in to your Google Ads account
  2. Look at the top right corner of any page
  3. Your Customer ID is displayed next to your account name (format: 123-456-7890)
  4. Important: Remove the hyphens when entering in Webrix (use 1234567890)
note

If you manage multiple Google Ads accounts through a manager account (MCC), each sub-account has its own Customer ID. Use the specific Customer ID for the account you want to access.

Setting up OAuth​

Follow these steps to configure OAuth authentication for Google Ads:

1. Create a Google Cloud Project​

  1. Go to the Google Cloud Console
  2. Click Select a project at the top of the page, then click New Project
  3. Enter a project name (e.g., "Webrix Google Ads Integration")
  4. Click Create

2. Enable the Google Ads API​

  1. In your Google Cloud project, navigate to APIs & Services > Library
  2. Search for "Google Ads API"
  3. Click on Google Ads API and click Enable
  4. Wait for the API to be enabled (this may take a minute)
  1. Navigate to APIs & Services > OAuth consent screen
  2. Select External as the User Type (or Internal if you're using Google Workspace and want to restrict to your organization)
  3. Click Create
  4. Fill in the required information:
    • App name: Enter your application name (e.g., "Webrix")
    • User support email: Select your email address
    • Developer contact information: Enter your email address
  5. Click Save and Continue
  6. On the Scopes page, click Add or Remove Scopes
  7. Scroll down or search for the Google Ads API scope:
    • https://www.googleapis.com/auth/adwords (required for Google Ads API access)
  8. Check the box next to this scope
  9. Click Update and then Save and Continue
  10. If using External user type, add test users who should have access during development (add the email addresses of Google Ads account users)
  11. Click Save and Continue to review, then click Back to Dashboard
tip

The Google Ads API uses a single OAuth scope (adwords) that grants full access. Unlike some Google APIs, there are no separate read-only or limited scopes.

4. Create OAuth 2.0 Credentials​

  1. Navigate to APIs & Services > Credentials
  2. Click Create Credentials at the top and select OAuth client ID
  3. Select Web application as the Application type
  4. Enter a name for your OAuth client (e.g., "Webrix Web Client")
  5. Under Authorized redirect URIs, add your Webrix redirect URI:
    • For Webrix Cloud: https://app.webrix.ai/oauth/callback
    • For self-hosted: Your Webrix instance callback URL
  6. Click Create
  7. A dialog will appear with your Client ID and Client Secret
  8. Copy both values - you'll need them for Webrix configuration

5. Configure in Webrix​

  1. Log in to your Webrix instance
  2. Navigate to Connectors or Integrations
  3. Find and select Google Ads
  4. Enter your General Settings:
    • Developer Token: Paste your 22-character token from the Google Ads API Center
    • Customer ID: Enter your 10-digit Customer ID (no hyphens)
  5. Choose OAuth as the authentication method
  6. Paste your Client ID from step 4
  7. Paste your Client Secret from step 4
  8. The scope https://www.googleapis.com/auth/adwords is pre-selected
  9. Click Connect or Authorize
  10. You'll be redirected to Google to grant permissions
  11. Important: Sign in with a Google account that has access to the Google Ads account specified by your Customer ID
  12. Review the permissions and click Allow
  13. You'll be redirected back to Webrix with a successful connection

6. Verify the Connection​

After authorization, test the connection:

  1. Use the List Accessible Customers tool to verify you can access your account
  2. Try the Get Customer Details tool to see your account information
  3. Run a simple List Campaigns query to verify data access

Common Use Cases​

Campaign Performance Monitoring​

Use the reporting tools to track campaign performance:

Tool: Get Campaign Performance Report
Parameters:
  - dateRange: "LAST_30_DAYS"
  - campaignStatus: "ENABLED"

This returns key metrics (impressions, clicks, cost, conversions) for all active campaigns over the last 30 days.

Bulk Keyword Management​

Add multiple keywords to an ad group efficiently:

Tool: Add Keywords
Parameters:
  - adGroup: "customers/1234567890/adGroups/98765"
  - keywords: [
      {"text": "buy shoes online", "matchType": "PHRASE"},
      {"text": "running shoes", "matchType": "BROAD"},
      {"text": "nike shoes", "matchType": "EXACT"}
    ]

Campaign Creation​

Create a new search campaign:

Tool: Create Campaign
Parameters:
  - name: "Summer Sale 2026"
  - advertisingChannelType: "SEARCH"
  - status: "PAUSED"
  - campaignBudget: "customers/1234567890/campaignBudgets/11111"
  - biddingStrategyType: "MAXIMIZE_CONVERSIONS"

Custom Reporting with GAQL​

For advanced users, execute custom queries using Google Ads Query Language:

Tool: Run Custom GAQL Query
Parameters:
  - query: "SELECT campaign.name, ad_group.name, metrics.clicks, metrics.impressions, metrics.cost_micros FROM ad_group WHERE campaign.status = 'ENABLED' AND segments.date DURING LAST_7_DAYS ORDER BY metrics.clicks DESC LIMIT 50"

Automated Bid Adjustments​

Update keyword bids based on performance:

Tool: Update Keywords
Parameters:
  - keywords: [
      {
        "resourceName": "customers/1234567890/adGroupCriteria/98765~11111",
        "cpcBidMicros": 2500000
      }
    ]

Note: 2,500,000 micros = $2.50 (or 2.50 in your account currency)

Understanding Key Concepts​

Resource Names​

Google Ads API uses resource names to identify entities. The format is:

  • Campaign: customers/1234567890/campaigns/98765
  • Ad Group: customers/1234567890/adGroups/98765
  • Keyword: customers/1234567890/adGroupCriteria/98765~11111

Micros (Currency)​

All monetary values in the Google Ads API are represented in "micros":

  • 1 currency unit = 1,000,000 micros
  • $1.50 = 1,500,000 micros
  • €10.25 = 10,250,000 micros

To convert: amount_in_currency * 1,000,000 = micros

GAQL (Google Ads Query Language)​

GAQL is a SQL-like language for querying Google Ads data:

SELECT 
  campaign.name,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.clicks DESC
LIMIT 100

Key features:

  • SELECT: Choose fields to retrieve
  • FROM: Specify the resource type
  • WHERE: Filter results
  • ORDER BY: Sort results
  • LIMIT: Restrict number of rows

Batch Operations​

Many mutate operations support batch processing for efficiency:

  • Create multiple campaigns in one request
  • Update multiple keywords simultaneously
  • Remove multiple ads at once

Use the "Mutate" tools (e.g., Mutate Campaigns, Mutate Ad Groups) for batch operations.

Troubleshooting​

"AUTHORIZATION_ERROR" - Invalid Developer Token​

Cause: The Developer Token is incorrect, missing, or has insufficient access level.

Solution:

  1. Verify your Developer Token in Google Ads API Center
  2. Ensure you copied the full 22-character token
  3. Check your token's access level:
    • Test Access tokens can only access test accounts
    • Apply for Basic or Standard access for production accounts
  4. Update the Developer Token in Webrix general settings
  5. Try the connection again

"INVALID_CUSTOMER_ID" Error​

Cause: The Customer ID format is incorrect or the account doesn't exist.

Solution:

  1. Verify your Customer ID in Google Ads (top right corner, format: 123-456-7890)
  2. Remove hyphens when entering in Webrix (use 1234567890)
  3. Ensure the Customer ID is exactly 10 digits
  4. Verify the authenticated user has access to this Customer ID
  5. Update the Customer ID in Webrix general settings

"User Does Not Have Permission to Access Customer"​

Cause: The Google account used for OAuth doesn't have access to the specified Customer ID.

Solution:

  1. Verify the Customer ID is correct
  2. Sign in to Google Ads with the same Google account you used for OAuth
  3. Check if you can see and access the account with that Customer ID
  4. If not, ask a Google Ads administrator to grant you access with at least:
    • Standard access level for read operations
    • Admin access level for write operations
  5. After gaining access, re-authorize the connection in Webrix

"QUERY_ERROR" - GAQL Syntax Issues​

Cause: The GAQL query has syntax errors or references invalid field combinations.

Solution:

  1. Check the GAQL documentation for correct syntax
  2. Use the Google Ads Query Validator to test queries
  3. Common issues:
    • Incorrect field names (use campaign.name, not campaignName)
    • Invalid field combinations (some metrics can't be queried with certain attributes)
    • Missing quotes around string values in WHERE clauses
  4. Try a simpler query first, then add complexity

Rate Limiting / Quota Exceeded​

Cause: You've exceeded the daily operations limit for your Developer Token access level.

Solution:

  1. Test Access: 15,000 operations/day - Apply for Basic or Standard access
  2. Basic Access: 15,000 operations/day - Optimize queries or apply for Standard access
  3. Standard Access: Unlimited for most use cases
  4. Use batch operations to reduce API call count
  5. Use SearchStream for large reports instead of paginated Search
  6. Cache frequently accessed data instead of repeated queries

"OAuth Scope Mismatch" or Insufficient Permissions​

Cause: The OAuth token doesn't have the required adwords scope.

Solution:

  1. Go to APIs & Services > Credentials in Google Cloud Console
  2. Verify the OAuth consent screen includes the https://www.googleapis.com/auth/adwords scope
  3. In Webrix, disconnect and reconnect the Google Ads integration
  4. During OAuth flow, ensure you grant the requested permissions
  5. If the scope isn't requested, check your Webrix connector configuration

Test Account Access with Test-Level Token​

Cause: Your Developer Token has "Test Access" level but you're trying to access a production account.

Solution:

  1. Create a Google Ads test account
  2. Use the test account's Customer ID during testing
  3. Or apply for Basic/Standard access for your Developer Token:
    • In Google Ads, go to API Center
    • Click "Apply for Basic Access" or "Apply for Standard Access"
    • Fill out the form describing your API usage
    • Wait for Google's approval (typically 1-5 business days)

Response Too Large / Memory Issues​

Cause: Query returns too much data causing timeouts or memory issues.

Solution:

  1. Use the Stream Large Report tool instead of regular search for large datasets
  2. Add LIMIT clause to GAQL queries to restrict results
  3. Add more specific WHERE clauses to filter data
  4. Query date ranges in smaller chunks (e.g., one week at a time instead of all time)
  5. Select only the fields you need in the SELECT clause

"Invalid Resource Name" Error​

Cause: The resource name format is incorrect or the resource doesn't exist.

Solution:

  1. Verify resource name format:
    • Campaign: customers/1234567890/campaigns/98765
    • Ad Group: customers/1234567890/adGroups/98765
    • Keyword: customers/1234567890/adGroupCriteria/98765~11111
  2. Ensure no extra spaces or typos
  3. Verify the resource exists (not removed)
  4. Get resource names from List or Search tools rather than constructing manually

Advanced Topics​

Using Manager Accounts (MCC)​

If you manage multiple Google Ads accounts through a Manager Account (MCC), you can access sub-accounts by specifying different Customer IDs in individual tool calls. The OAuth authentication is done at the manager level, but API calls target specific customer accounts.

Understanding Bidding Strategies​

Google Ads supports multiple bidding strategies:

  • Manual CPC: You set bids manually
  • Maximize Conversions: Google automatically sets bids to get the most conversions
  • Target CPA: Automatically sets bids to achieve a target cost per acquisition
  • Target ROAS: Aims for a specific return on ad spend
  • Maximize Conversion Value: Gets the most conversion value within your budget

Choose the appropriate strategy when creating campaigns based on your goals.

Performance Metrics vs. Attributes​

In GAQL queries:

  • Attributes (e.g., campaign.name, ad_group.status) describe the resource
  • Metrics (e.g., metrics.clicks, metrics.impressions) measure performance
  • Segments (e.g., segments.date, segments.device) break down data by dimensions

Not all combinations are valid - use the Google Ads API Field Reference to check compatibility.

Additional Resources​