cotera
Logo

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.

Update Campaign Status

Enable, pause, or remove a campaign by updating its status.

Operation Type: Mutation (Write)

Parameters:

  • clientCustomerId string (required): The client customer ID (account to modify). 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 update.
  • status string (required): The new campaign status. Options: ENABLED, PAUSED, REMOVED.

Returns:

  • success boolean: Whether the status was updated successfully
  • campaignId string: The campaign ID that was updated
  • newStatus string: The new status of the campaign

Example Usage:

{
  "clientCustomerId": "1234567890",
  "campaignId": "12345678",
  "status": "PAUSED"
}

Ad Groups

List Ad Groups

List all ad groups within a campaign or account with performance metrics.

Operation Type: Query (Read)

Parameters:

  • clientCustomerId string (required): The client customer ID. Remove dashes.
  • managerCustomerId string (nullable): The manager (MCC) customer ID.
  • campaignId string (nullable): Filter ad groups by campaign ID. Null returns ad groups across all campaigns.
  • adGroupStatus string (nullable): Filter by status. Options: ENABLED, PAUSED, REMOVED.
  • dateRange string (nullable): Date range for metrics. Options: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH.

Returns:

  • adGroups array of objects: Array of ad groups with metrics
    • id string: Ad group ID
    • name string: Ad group name
    • status string: Ad group status
    • campaignId string: Parent campaign ID
    • campaignName string (nullable): Parent campaign name
    • type string (nullable): Ad group type
    • impressions string (nullable): Number of impressions
    • clicks string (nullable): Number of clicks
    • costMicros string (nullable): Total cost in micros
    • conversions number (nullable): Number of conversions
    • ctr number (nullable): Click-through rate

Example Usage:

{
  "clientCustomerId": "1234567890",
  "campaignId": "12345678",
  "adGroupStatus": "ENABLED",
  "dateRange": "LAST_30_DAYS"
}

Get Ad Group

Get a specific ad group by ID with performance metrics.

Operation Type: Query (Read)

Parameters:

  • clientCustomerId string (required): The client customer ID. Remove dashes.
  • managerCustomerId string (nullable): The manager (MCC) customer ID.
  • adGroupId string (required): The ID of the ad group to retrieve.

Returns:

  • adGroup object (nullable): The ad group details with the same fields as List Ad Groups.

Example Usage:

{
  "clientCustomerId": "1234567890",
  "adGroupId": "123456789"
}

Ads

List Ads

List ads within a campaign or ad group with creative details and performance metrics.

Operation Type: Query (Read)

Parameters:

  • clientCustomerId string (required): The client customer ID. Remove dashes.
  • managerCustomerId string (nullable): The manager (MCC) customer ID.
  • campaignId string (nullable): Filter by campaign ID.
  • adGroupId string (nullable): Filter by ad group ID.
  • dateRange string (nullable): Date range for metrics.

Returns:

  • ads array of objects: Array of ads with metrics
    • id string: Ad ID
    • adGroupId string: Parent ad group ID
    • adGroupName string (nullable): Parent ad group name
    • campaignId string: Parent campaign ID
    • campaignName string (nullable): Parent campaign name
    • type string (nullable): Ad type (RESPONSIVE_SEARCH_AD, etc.)
    • status string: Ad status
    • headlines array of strings (nullable): RSA headlines
    • descriptions array of strings (nullable): RSA descriptions
    • finalUrls array of strings (nullable): Landing page URLs
    • impressions string (nullable): Number of impressions
    • clicks string (nullable): Number of clicks
    • costMicros string (nullable): Total cost in micros
    • conversions number (nullable): Number of conversions
    • ctr number (nullable): Click-through rate

Example Usage:

{
  "clientCustomerId": "1234567890",
  "adGroupId": "123456789",
  "dateRange": "LAST_7_DAYS"
}

Keywords

List Keywords

List keywords within a campaign or ad group with match types, quality scores, and performance metrics.

Operation Type: Query (Read)

Parameters:

  • clientCustomerId string (required): The client customer ID. Remove dashes.
  • managerCustomerId string (nullable): The manager (MCC) customer ID.
  • campaignId string (nullable): Filter by campaign ID.
  • adGroupId string (nullable): Filter by ad group ID.
  • keywordStatus string (nullable): Filter by status. Options: ENABLED, PAUSED, REMOVED.
  • dateRange string (nullable): Date range for metrics.

Returns:

  • keywords array of objects: Array of keywords with metrics
    • criterionId string: Keyword criterion ID
    • keyword string: The keyword text
    • matchType string: Match type (EXACT, PHRASE, BROAD)
    • status string: Keyword status
    • adGroupId string: Parent ad group ID
    • adGroupName string (nullable): Parent ad group name
    • campaignId string: Parent campaign ID
    • campaignName string (nullable): Parent campaign name
    • impressions string (nullable): Number of impressions
    • clicks string (nullable): Number of clicks
    • costMicros string (nullable): Total cost in micros
    • conversions number (nullable): Number of conversions
    • ctr number (nullable): Click-through rate
    • averageCpc string (nullable): Average CPC in micros
    • qualityScore number (nullable): Quality score (1-10)

Example Usage:

{
  "clientCustomerId": "1234567890",
  "campaignId": "12345678",
  "keywordStatus": "ENABLED",
  "dateRange": "LAST_30_DAYS"
}

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