# Google Ads tools

Source: https://adsuperpowers.ai/docs/tools/google-ads

Full campaign management for Google Ads with GAQL queries, keyword research, and campaign mutations.

## Before you begin

Connect the relevant Google Ads account through [Accounts](https://adsuperpowers.ai/docs/accounts), then connect your [AI assistant](https://adsuperpowers.ai/docs/setup). Confirm the target account and date range before querying data or making changes.

This is the generated catalog. The tools shown in your AI assistant depend on your connected accounts, active workspace, role, write permissions, enabled features and the client's supported tool surface. A listed tool is not a promise that it is enabled in every workspace. See [accounts](https://adsuperpowers.ai/docs/accounts), [workspace access](https://adsuperpowers.ai/docs/workspaces) and [troubleshooting](https://adsuperpowers.ai/docs/troubleshooting).

## Available tools

5 tools · API v25.

| Tool | Access | Purpose |
| --- | --- | --- |
| `google_ads_list_accounts` | Read | List all Google Ads accounts you have access to |
| `google_ads_run_gaql` | Read | Run a Google Ads Query Language (GAQL) query |
| `google_ads_run_keyword_planner` | Read | Get keyword ideas and search volume data |
| `google_ads_mutate` | Write | Create, update, or remove campaigns, ad groups, ads, and keywords |
| `google_ads_upload` | Write | Upload staged Google Ads images/videos, or inspect the exact recorded media. |

Write tools can change account settings, campaigns or workspace content. Confirm the target and proposed changes before running them.

Private local uploads support Meta, TikTok, LinkedIn and Google Ads. Your workspace needs upload access to the destination, and your AI client needs file access and HTTP upload. JPEG/PNG images up to 20 MB (20,000,000 bytes) and MP4 videos up to 500 MB (500,000,000 bytes) are supported by the upload flow; destination-specific restrictions still apply. Existing account-library IDs remain available. Read the [upload guide](https://adsuperpowers.ai/docs/media-upload) before uploading.

## Example questions

> List my Google Ads accounts

> Find keyword ideas for 'marketing automation'

> Show campaign performance for the last 30 days

> What keywords have the best quality score?

> Compare performance across my search campaigns

[More example questions](https://adsuperpowers.ai/docs/examples).

## API capabilities

Available fields and combinations depend on the resource, account and campaign type. Adapt the examples to your selected account.

### Metrics

| Category | Fields |
| --- | --- |
| Traffic | `impressions`, `clicks`, `ctr`, `cost_micros`, `average_cpc`, `average_cpm` |
| Conversion | `conversions`, `conversions_value`, `conversions_by_conversion_date`, `all_conversions`, `view_through_conversions`, `cross_device_conversions` |
| Engagement | `engagements`, `engagement_rate`, `interactions`, `interaction_rate` |
| Video | `video_views`, `video_view_rate`, `video_quartile_p25_rate`, `video_quartile_p50_rate`, `video_quartile_p75_rate`, `video_quartile_p100_rate` |
| Quality & Competition | `search_impression_share`, `search_top_impression_share`, `search_absolute_top_impression_share`, `content_impression_share`, `search_budget_lost_impression_share`, `search_rank_lost_impression_share` |
| Bidding | `average_cost`, `cost_per_conversion`, `cost_per_all_conversions`, `value_per_conversion`, `value_per_all_conversions`, `optimization_score_uplift` |

### Dimensions

| Category | Fields |
| --- | --- |
| Time | `segments.date`, `segments.day_of_week`, `segments.hour`, `segments.month`, `segments.quarter`, `segments.year`, `segments.week` |
| Device & Network | `segments.device`, `segments.ad_network_type`, `segments.click_type` |
| Conversion | `segments.conversion_action`, `segments.conversion_action_category`, `segments.external_conversion_source` |
| Geographic | `segments.geo_target_city`, `segments.geo_target_metro`, `segments.geo_target_region` |
| Shopping | `segments.product_channel`, `segments.product_item_id` |
| Search | `segments.search_term_match_type` |

### Query examples

#### Bidding Strategy Effectiveness Analysis

Compare campaign bidding strategies. Calculate ROAS after retrieval as conversions_value / (cost_micros / 1,000,000); leave ROAS undefined when cost is zero.

Tool: `google_ads_run_gaql`.

```sql
SELECT
  campaign.id,
  campaign.name,
  campaign.bidding_strategy_type,
  bidding_strategy.name,
  campaign.target_cpa.target_cpa_micros,
  campaign.target_roas.target_roas,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions,
  metrics.cost_per_conversion,
  metrics.conversions_value,
  metrics.cost_micros
FROM campaign
WHERE
  campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.conversions DESC
```

#### Search Term Discovery & Negative Keyword Mining

Find search terms that cost money but don't convert - candidates for negative keywords

Tool: `google_ads_run_gaql`.

```sql
SELECT
  search_term_view.search_term,
  search_term_view.status,
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.conversions,
  metrics.cost_micros
FROM search_term_view
WHERE
  segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 50
  AND metrics.conversions = 0
  AND metrics.cost_micros > 10000000
ORDER BY metrics.cost_micros DESC
LIMIT 100
```

#### Geographic Performance Deep Dive

Analyze which geographic locations drive the most conversions

Tool: `google_ads_run_gaql`.

```sql
SELECT
  geographic_view.country_criterion_id,
  geographic_view.location_type,
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions,
  metrics.cost_micros,
  metrics.conversions_value
FROM geographic_view
WHERE
  segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 100
ORDER BY metrics.conversions_value DESC
```

#### Device & Hour Performance Matrix

Build a dayparting matrix to optimize ad scheduling by device

Tool: `google_ads_run_gaql`.

```sql
SELECT
  segments.device,
  segments.hour,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.conversions,
  metrics.cost_per_conversion
FROM campaign
WHERE
  segments.date DURING LAST_7_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY segments.device, segments.hour
```

#### Quality Score & Ad Relevance Analysis

Find keywords with low quality scores that need optimization

Tool: `google_ads_run_gaql`.

```sql
SELECT
  ad_group.name,
  ad_group_criterion.keyword.text,
  ad_group_criterion.quality_info.quality_score,
  ad_group_criterion.quality_info.creative_quality_score,
  ad_group_criterion.quality_info.post_click_quality_score,
  ad_group_criterion.quality_info.search_predicted_ctr,
  metrics.impressions,
  metrics.clicks,
  metrics.average_cpc
FROM keyword_view
WHERE
  segments.date DURING LAST_30_DAYS
  AND ad_group_criterion.status = 'ENABLED'
ORDER BY ad_group_criterion.quality_info.quality_score ASC
```

#### Auction Insights Competitive Analysis

Understand your competitive position with impression share metrics

Tool: `google_ads_run_gaql`.

```sql
SELECT
  campaign.name,
  metrics.search_impression_share,
  metrics.search_top_impression_share,
  metrics.search_absolute_top_impression_share,
  metrics.search_budget_lost_impression_share,
  metrics.search_rank_lost_impression_share,
  metrics.search_exact_match_impression_share
FROM campaign
WHERE
  campaign.advertising_channel_type = 'SEARCH'
  AND segments.date DURING LAST_30_DAYS
  AND campaign.status = 'ENABLED'
ORDER BY metrics.search_impression_share DESC
```

## Technical reference

API endpoint: `googleads.googleapis.com/v25`. Status: stable. Scheduled version sunset: August 2027.



### Limitations and notes

- Campaign mutations require google_ads_mutate tool (Standard Access developer token needed for production)
- GAQL has no LAST_90_DAYS preset - use BETWEEN with specific dates instead
- Some metrics require specific campaign types (e.g., video metrics need video campaigns)

## Other platforms and tools

- [Meta Ads](https://adsuperpowers.ai/docs/tools/meta-ads)
- [Google Analytics](https://adsuperpowers.ai/docs/tools/google-analytics)
- [Google Search Console](https://adsuperpowers.ai/docs/tools/google-search-console)
- [Google Tag Manager](https://adsuperpowers.ai/docs/tools/google-tag-manager)
- [Google Merchant Center](https://adsuperpowers.ai/docs/tools/google-merchant-center)
- [LinkedIn Ads](https://adsuperpowers.ai/docs/tools/linkedin-ads)
- [TikTok Ads](https://adsuperpowers.ai/docs/tools/tiktok-ads)
- [Workflows](https://adsuperpowers.ai/docs/tools/workflows)
- [Skills](https://adsuperpowers.ai/docs/tools/skills)
- [Clients](https://adsuperpowers.ai/docs/tools/clients)

[All tools](https://adsuperpowers.ai/docs/tools) · [Quickstart](https://adsuperpowers.ai/docs/quickstart)