Google Ads

Authentication Type: OAuth2 + Developer Token Description: Query your Google Ads account data including campaigns, ad groups, keywords, and performance metrics using the Google Ads API and GAQL (Google Ads Query Language).

Authentication

To authenticate with Google Ads, you need OAuth2 credentials and a Google Ads developer token:

1. Go to the Google Cloud Console and create a project (or use an existing one)
2. Enable the Google Ads API in the API Library
3. Create OAuth2 credentials (type: Web application) in Credentials
4. Get a Developer Token from your Google Ads Manager Account under Tools & Settings > API Center

You'll need to provide:

• clientId string: Your OAuth2 client ID from Google Cloud Console
• clientSecret string: Your OAuth2 client secret
• refreshToken string: An OAuth2 refresh token with Google Ads access scope
• developerToken string: Your Google Ads API developer token (from the MCC API Center)

Note: The developer token is separate from your OAuth credentials. You get it from your Google Ads Manager (MCC) account, not from Google Cloud Console. Test accounts have a test developer token with limited access.

Account

List Accessible Customers

List all Google Ads customer accounts accessible to the authenticated user. Use this to discover available account IDs before querying campaigns or running GAQL queries.

Operation Type: Query (Read)

Parameters:

No parameters required.

Returns:

• customerIds array of strings: List of accessible customer resource names (e.g., "customers/1234567890")

Example Usage:

{}

Campaigns

List Campaigns

List all campaigns for a Google Ads account with performance metrics including impressions, clicks, conversions, and cost. Supports filtering by date range and campaign status.

Operation Type: Query (Read)

Parameters:

• clientCustomerId string (required): The client customer ID (account to query). Remove dashes, e.g., "6665554444".
• managerCustomerId string (nullable): The manager (MCC) customer ID. Required if accessing a sub-account through a manager account.
• dateRange string (nullable): Date range filter for metrics. Options: TODAY, YESTERDAY, LAST_7_DAYS, LAST_BUSINESS_WEEK, THIS_MONTH, LAST_MONTH, LAST_14_DAYS, LAST_30_DAYS. Null for all time.
• campaignStatus string (nullable): Filter by campaign status. Options: ENABLED, PAUSED, REMOVED. Null for all statuses.

Returns:

• campaigns array of objects: Array of campaigns with performance metrics
  • id string: Campaign ID
  • name string: Campaign name
  • status string: Campaign status (ENABLED, PAUSED, REMOVED)
  • advertisingChannelType string (nullable): Channel type (SEARCH, DISPLAY, VIDEO, etc.)
  • advertisingChannelSubType string (nullable): Channel sub-type
  • optimizationScore number (nullable): Optimization score (0 to 1)
  • budgetAmountMicros string (nullable): Budget amount in micros (divide by 1,000,000 for actual value)
  • budgetPeriod string (nullable): Budget period (DAILY, etc.)
  • impressions string (nullable): Number of impressions
  • interactions string (nullable): Number of interactions (clicks)
  • interactionRate number (nullable): Interaction rate
  • averageCost string (nullable): Average cost in micros
  • costMicros string (nullable): Total cost in micros
  • conversions number (nullable): Number of conversions
  • costPerConversion number (nullable): Cost per conversion in micros
  • conversionsFromInteractionsRate number (nullable): Conversion rate from interactions
  • videoViews string (nullable): Number of video views
  • averageCpm number (nullable): Average CPM in micros
  • ctr number (nullable): Click-through rate

Example Usage:

{
  "clientCustomerId": "1234567890",
  "managerCustomerId": "9876543210",
  "dateRange": "LAST_30_DAYS",
  "campaignStatus": "ENABLED"
}

Tip: Budget and cost fields are returned in micros. Divide by 1,000,000 to get the actual currency value. For example, 5000000 micros = $5.00.

Get Campaign

Get a specific Google Ads campaign by ID with performance metrics including impressions, clicks, conversions, and cost.

Operation Type: Query (Read)

Parameters:

• clientCustomerId string (required): The client customer ID (account to query). Remove dashes, e.g., "6665554444".
• managerCustomerId string (nullable): The manager (MCC) customer ID. Required if accessing through a manager account.
• campaignId string (required): The ID of the campaign to retrieve.

Returns:

• campaign object (nullable): The campaign details, or null if not found. Has the same fields as campaigns in the List Campaigns response.

Example Usage:

{
  "clientCustomerId": "1234567890",
  "managerCustomerId": "9876543210",
  "campaignId": "12345678"
}

Search with GAQL

Execute a custom Google Ads Query Language (GAQL) query against a Google Ads account. This is the most flexible tool, supporting queries across campaigns, ad groups, ads, keywords, and any other Google Ads resource.

Operation Type: Query (Read)

Parameters:

• clientCustomerId string (required): The client customer ID (account to query). Remove dashes, e.g., "6665554444".
• managerCustomerId string (nullable): The manager (MCC) customer ID. Required if accessing through a manager account.
• query string (required): A Google Ads Query Language (GAQL) query.

Returns:

• results array: Array of result rows from the GAQL query. Structure depends on the fields selected in the query.

Example Usage:

{
  "clientCustomerId": "1234567890",
  "query": "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks FROM campaign WHERE campaign.status = 'ENABLED' AND segments.date DURING LAST_7_DAYS"
}

GAQL Reference: You can query any resource in the Google Ads API, including campaign, ad_group, ad_group_ad, keyword_view, search_term_view, geographic_view, and more. See the Google Ads Query Language documentation for the full list of resources and fields.

Common Use Cases

Campaign Performance Monitoring:

• Pull daily/weekly performance metrics for all active campaigns
• Track key metrics like CPA, ROAS, and conversion rates over time
• Compare campaign performance across different date ranges

Ad Spend Analysis:

• Monitor budget utilization across campaigns
• Identify campaigns with high spend but low conversions
• Calculate aggregate spend across multiple accounts

Custom Reporting with GAQL:

• Build custom reports querying ad groups, keywords, or search terms
• Analyze geographic performance with location-based queries
• Pull device-level or audience segment data for deeper analysis

Multi-Account Management:

• List all accessible accounts under a manager (MCC) hierarchy
• Compare performance across client accounts
• Automate cross-account reporting workflows