Google Ads API Account Performance Diagnostics Skill
This skill provides instructions on how to use the Google Ads MCP server tools to diagnose common account performance issues.
Workflows
Pre-Flight Tool Verification
Before starting any diagnostic task, verify whether the Google Ads MCP Server tools (search, list_accessible_customers, get_resource_metadata — these may be exposed with a server prefix, e.g. customers_list_accessible_customers) are available in the runtime environment:
Identifying Active Client Accounts
Most diagnostics tasks require sending GAQL queries to a specific customer account. If the customer ID is not explicitly provided by the user, you must first call the list_accessible_customers (or customers_list_accessible_customers) tool to retrieve the customer resource names/IDs you have access to.
Once you have the list of accessible customer IDs, query the customer_client resource using the search tool under those customer accounts to find active client customer accounts. Make sure to select only enabled client accounts and filter out manager accounts:
SELECT
customer_client.id,
customer_client.descriptive_name,
customer_client.status,
customer_client.manager
FROM customer_client
WHERE customer_client.status = 'ENABLED' AND customer_client.manager = FALSE
Only run subsequent diagnostic queries against the enabled client customer IDs retrieved from this list. Do not query deactivated or manager accounts, as doing so will cause API errors.
Fallback When MCP Tools Are Unavailable
When Google Ads MCP tools (search, list_accessible_customers, get_resource_metadata — these may be exposed with a server prefix, e.g. customers_list_accessible_customers) are not registered in the runtime environment:
- Inform the User: State that live account performance diagnostics require the Google Ads MCP Server.
- Reference Setup Guide: Direct the user to the setup instructions in the google-ads-api-mcp-setup skill to install and configure the Google Ads MCP Server for their assistant environment.
- Provide GAQL Templates, Gotchas, and Remediation Guidance: Formulate and output the complete diagnostic plan for manual execution in the Google Ads Query Builder or via API integration:
- Provide all multi-step GAQL queries for the workflow, including current-vs-prior date window comparisons (e.g. traffic, impression share, conversion breakdowns, or change events).
- Explain all metric conversion and constraint gotchas (
metrics.cost_micros / 1,000,000 for currency, impression share reported as decimals or "< 0.10", change_event 30-day window and LIMIT 10000 without metrics.*, and successful_event_count / total_event_count plus status for upload health).
- Outline concrete actionable next steps for each diagnostic branch (e.g., raising campaign budgets when
search_budget_lost_impression_share is high vs. improving ad quality or bids when search_rank_lost_impression_share is high).
- Do Not Attempt Unauthorized Local Probing: Do not attempt to run shell commands, custom Python scripts, local SQL/database queries, or direct RPC CLI utilities to access account data. These commands lack credentials and API access and will fail.
1. Conversion and Conversion Value Loss
When conversions or conversion value suddenly decline, use the following steps to diagnose the issue.
Steps:
Discover Fields: Use get_resource_metadata with resource campaign or ad_group to ensure you have the correct field names.
Query Performance: Use search to retrieve performance data.
- Resource:
campaign or ad_group
- Fields: Include
campaign.name, metrics.conversions, metrics.conversions_value, metrics.cost_micros.
- Segments: To isolate the loss, include segments like
segments.date, segments.device, segments.conversion_action.
- Conditions: Compare the period of decline with a previous period (e.g.,
segments.date >= '{start_date}').
- Gotcha:
metrics.cost_micros must be divided by 1,000,000 to get standard currency amounts.
- Gotcha (conversion action segmentation): In GAQL,
metrics.cost_micros cannot be selected when segmenting by segments.conversion_action. Query conversion action breakdowns separately without metrics.cost_micros.
Example GAQL Queries:
- To query performance and cost by date and device:
SELECT
campaign.name,
metrics.conversions,
metrics.conversions_value,
metrics.cost_micros,
segments.date,
segments.device
FROM campaign
WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
- To query conversion breakdown by conversion action (without
metrics.cost_micros):
SELECT
campaign.name,
metrics.conversions,
metrics.conversions_value,
segments.date,
segments.conversion_action
FROM campaign
WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
Analyze: Check if the loss is limited to certain devices (e.g., mobile vs desktop) or specific conversion actions.
Check Uploads: If using offline imports, query offline_conversion_upload_conversion_action_summary to verify upload pipeline health. If the query returns no results, report that no offline uploads exist for the account and proceed.
Example GAQL Query:
To check upload pipeline health for a customer account {customer_id}:
SELECT
offline_conversion_upload_conversion_action_summary.conversion_action_name,
offline_conversion_upload_conversion_action_summary.successful_event_count,
offline_conversion_upload_conversion_action_summary.total_event_count,
offline_conversion_upload_conversion_action_summary.status
FROM offline_conversion_upload_conversion_action_summary
2. Opportunities Lost (Impression Share)
To identify lost opportunities due to ad rank, bids, or budgets, analyze impression share metrics.
Steps:
Query Impression Share: Use search to retrieve impression share metrics.
- Resource:
campaign
- Fields: Include
campaign.name, metrics.search_impression_share, metrics.search_rank_lost_impression_share, metrics.search_budget_lost_impression_share.
- Gotcha: Impression share values in the API are returned as decimals (e.g., 0.35 = 35%) or formatted strings (e.g.,
"< 0.10").
Example GAQL Query:
To query impression share metrics for a customer account {customer_id} between {start_date} and {end_date}:
SELECT
campaign.name,
metrics.search_impression_share,
metrics.search_rank_lost_impression_share,
metrics.search_budget_lost_impression_share
FROM campaign
WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
Analyze:
- High
search_budget_lost_impression_share indicates opportunities lost due to limited budget.
- High
search_rank_lost_impression_share indicates opportunities lost due to low ad rank (bid or quality issues).
3. Low Lead Flow Diagnostics
When a user asks "why is my lead flow low these past few days?", follow this systematic approach.
Steps:
Confirm Drop: Query conversions segmented by date for the last few days vs the previous period.
Isolate Cause:
- Check if Traffic (clicks, impressions) dropped.
- Check if Conversion Rate (conversions/clicks) dropped.
Example GAQL Query (Traffic and Conversion Trends):
To query traffic and conversion rate metrics across campaigns segmented by date:
SELECT
campaign.id,
campaign.name,
segments.date,
metrics.impressions,
metrics.clicks,
metrics.ctr,
metrics.conversions,
metrics.conversions_from_interactions_rate
FROM campaign
WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
ORDER BY segments.date DESC
If Traffic Dropped: Check Impression Share metrics (see Workflow 2) to see if it's a budget or rank issue, or if search volume generally declined.
If Conversion Rate Dropped: Check breakdowns by segments.device or segments.conversion_action to see if a specific area is failing.
Check Changes: Query the change_event resource to see if any changes were made to bids, budgets, or targeting around the time the drop started.
- Gotcha (change_event constraints): Queries to the
change_event resource:
- Must specify a
LIMIT clause of less than or equal to 10000.
- Must filter by date (
change_event.change_date_time) within the past 30 days.
- Cannot select performance metrics (e.g.,
metrics.* is not supported; only change_event attributes and allowed resource fields can be selected).
Example GAQL Query:
To query change events for a customer account {customer_id} between {start_date} and {end_date}:
SELECT
change_event.change_date_time,
change_event.change_resource_name,
change_event.resource_change_operation,
change_event.changed_fields
FROM change_event
WHERE change_event.change_date_time >= '{start_date}' AND change_event.change_date_time <= '{end_date}'
LIMIT 10000
4. Offline Upload Pipeline Diagnostics
When offline conversion uploads for a specific action (e.g., store-purchase) stop showing up or fail, use the following steps to diagnose the issue.
Steps:
Retrieve Client Accounts: If {customer_id} is not provided, follow Identifying Active Client Accounts to retrieve active client customer accounts.
Verify Pipeline Health: Query offline_conversion_upload_conversion_action_summary for the active client account.
- Fields: Include
offline_conversion_upload_conversion_action_summary.conversion_action_name, offline_conversion_upload_conversion_action_summary.successful_event_count, offline_conversion_upload_conversion_action_summary.total_event_count, and offline_conversion_upload_conversion_action_summary.status.
Example GAQL Query:
SELECT
offline_conversion_upload_conversion_action_summary.conversion_action_name,
offline_conversion_upload_conversion_action_summary.successful_event_count,
offline_conversion_upload_conversion_action_summary.total_event_count,
offline_conversion_upload_conversion_action_summary.status
FROM offline_conversion_upload_conversion_action_summary
Analyze:
- Gotcha: If the query to
offline_conversion_upload_conversion_action_summary returns no results or is empty (indicating there are no offline conversion uploads configured or active for the customer account), immediately stop/break the diagnostic workflow. Report directly to the user that no offline conversion upload data or summaries exist in the accessible account(s), rather than retrying or attempting to generate custom scripts.
- If results are returned, verify the upload success rate by comparing
successful_event_count with total_event_count. Check the status field to diagnose failures.
1---2compatibility: 'Google Ads MCP Server (tools: search, list_accessible_customers, get_resource_metadata); see the google-ads-api-mcp-setup skill.'3description: Diagnoses Google Ads account performance issues such as conversion loss (value or volume), low lead flow/volume, and lost impression share (opportunities) due to ad rank, bids, or budgets. Use when troubleshooting sudden performance drops, analyzing campaign impression share metrics, investigating low lead flow, or searching for bidding and budget constraints. Don't use for setting up new campaigns, uploading conversion events directly, or general Google Mobile Ads SDK integration issues (use gma-android-integrate instead).4metadata:5 source: https://skillmd.com/skills/h3y6e/google-ads-api-account-diagnostics6 author: google-ads-api-team7 category: GoogleAds8 github-path: skills/ads/google-ads-api-account-diagnostics9 github-ref: refs/heads/main10 github-repo: https://github.com/google/skills11 github-tree-sha: 9397dd7b51ca932855f97a4355482d9bc466b83f12 version: 1.0.213name: google-ads-api-account-diagnostics14---1516# Google Ads API Account Performance Diagnostics Skill1718This skill provides instructions on how to use the Google Ads MCP server tools to diagnose common account performance issues.1920## Workflows2122### Pre-Flight Tool Verification23Before starting any diagnostic task, verify whether the Google Ads MCP Server tools (`search`, `list_accessible_customers`, `get_resource_metadata` — these may be exposed with a server prefix, e.g. `customers_list_accessible_customers`) are available in the runtime environment:24- **If MCP tools are available**: Proceed with live diagnostics — first [identify active client accounts](#identifying-active-client-accounts), then run GAQL via the `search` tool (arguments `customer_id` and `query`).25- **If MCP tools are missing**: Follow [Fallback When MCP Tools Are Unavailable](#fallback-when-mcp-tools-are-unavailable).2627### Identifying Active Client Accounts28Most diagnostics tasks require sending GAQL queries to a specific customer account. If the customer ID is not explicitly provided by the user, you must first call the `list_accessible_customers` (or `customers_list_accessible_customers`) tool to retrieve the customer resource names/IDs you have access to.2930Once you have the list of accessible customer IDs, query the `customer_client` resource using the `search` tool under those customer accounts to find active client customer accounts. Make sure to select only enabled client accounts and filter out manager accounts:31```sql32SELECT33 customer_client.id,34 customer_client.descriptive_name,35 customer_client.status,36 customer_client.manager37FROM customer_client38WHERE customer_client.status = 'ENABLED' AND customer_client.manager = FALSE39```40Only run subsequent diagnostic queries against the enabled client customer IDs retrieved from this list. Do not query deactivated or manager accounts, as doing so will cause API errors.4142### Fallback When MCP Tools Are Unavailable43When Google Ads MCP tools (`search`, `list_accessible_customers`, `get_resource_metadata` — these may be exposed with a server prefix, e.g. `customers_list_accessible_customers`) are not registered in the runtime environment:441. **Inform the User**: State that live account performance diagnostics require the Google Ads MCP Server.452. **Reference Setup Guide**: Direct the user to the setup instructions in the [google-ads-api-mcp-setup](../google-ads-api-mcp-setup/SKILL.md) skill to install and configure the Google Ads MCP Server for their assistant environment.463. **Provide GAQL Templates, Gotchas, and Remediation Guidance**: Formulate and output the complete diagnostic plan for manual execution in the Google Ads Query Builder or via API integration:47 - Provide all multi-step GAQL queries for the workflow, including current-vs-prior date window comparisons (e.g. traffic, impression share, conversion breakdowns, or change events).48 - Explain all metric conversion and constraint gotchas (`metrics.cost_micros / 1,000,000` for currency, impression share reported as decimals or `"< 0.10"`, `change_event` 30-day window and `LIMIT 10000` without `metrics.*`, and `successful_event_count / total_event_count` plus `status` for upload health).49 - Outline concrete **actionable next steps** for each diagnostic branch (e.g., raising campaign budgets when `search_budget_lost_impression_share` is high vs. improving ad quality or bids when `search_rank_lost_impression_share` is high).504. **Do Not Attempt Unauthorized Local Probing**: Do **not** attempt to run shell commands, custom Python scripts, local SQL/database queries, or direct RPC CLI utilities to access account data. These commands lack credentials and API access and will fail.5152### 1. Conversion and Conversion Value Loss5354When conversions or conversion value suddenly decline, use the following steps to diagnose the issue.5556**Steps:**571. **Discover Fields**: Use `get_resource_metadata` with resource `campaign` or `ad_group` to ensure you have the correct field names.582. **Query Performance**: Use `search` to retrieve performance data.59 * **Resource**: `campaign` or `ad_group`60 * **Fields**: Include `campaign.name`, `metrics.conversions`, `metrics.conversions_value`, `metrics.cost_micros`.61 * **Segments**: To isolate the loss, include segments like `segments.date`, `segments.device`, `segments.conversion_action`.62 * **Conditions**: Compare the period of decline with a previous period (e.g., `segments.date >= '{start_date}'`).63 * *Gotcha*: `metrics.cost_micros` must be divided by 1,000,000 to get standard currency amounts.64 * *Gotcha (conversion action segmentation)*: In GAQL, `metrics.cost_micros` cannot be selected when segmenting by `segments.conversion_action`. Query conversion action breakdowns separately without `metrics.cost_micros`.6566 **Example GAQL Queries:**67 1. To query performance and cost by date and device:68 ```sql69 SELECT70 campaign.name,71 metrics.conversions,72 metrics.conversions_value,73 metrics.cost_micros,74 segments.date,75 segments.device76 FROM campaign77 WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'78 ```7980 2. To query conversion breakdown by conversion action (without `metrics.cost_micros`):81 ```sql82 SELECT83 campaign.name,84 metrics.conversions,85 metrics.conversions_value,86 segments.date,87 segments.conversion_action88 FROM campaign89 WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'90 ```91923. **Analyze**: Check if the loss is limited to certain devices (e.g., mobile vs desktop) or specific conversion actions.934. **Check Uploads**: If using offline imports, query `offline_conversion_upload_conversion_action_summary` to verify upload pipeline health. If the query returns no results, report that no offline uploads exist for the account and proceed.9495 **Example GAQL Query:**96 To check upload pipeline health for a customer account `{customer_id}`:97 ```sql98 SELECT99 offline_conversion_upload_conversion_action_summary.conversion_action_name,100 offline_conversion_upload_conversion_action_summary.successful_event_count,101 offline_conversion_upload_conversion_action_summary.total_event_count,102 offline_conversion_upload_conversion_action_summary.status103 FROM offline_conversion_upload_conversion_action_summary104 ```105106### 2. Opportunities Lost (Impression Share)107108To identify lost opportunities due to ad rank, bids, or budgets, analyze impression share metrics.109110**Steps:**1111. **Query Impression Share**: Use `search` to retrieve impression share metrics.112 * **Resource**: `campaign`113 * **Fields**: Include `campaign.name`, `metrics.search_impression_share`, `metrics.search_rank_lost_impression_share`, `metrics.search_budget_lost_impression_share`.114 * *Gotcha*: Impression share values in the API are returned as decimals (e.g., 0.35 = 35%) or formatted strings (e.g., `"< 0.10"`).115116 **Example GAQL Query:**117 To query impression share metrics for a customer account `{customer_id}` between `{start_date}` and `{end_date}`:118 ```sql119 SELECT120 campaign.name,121 metrics.search_impression_share,122 metrics.search_rank_lost_impression_share,123 metrics.search_budget_lost_impression_share124 FROM campaign125 WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'126 ```1271282. **Analyze**:129 * High `search_budget_lost_impression_share` indicates opportunities lost due to limited budget.130 * High `search_rank_lost_impression_share` indicates opportunities lost due to low ad rank (bid or quality issues).131132### 3. Low Lead Flow Diagnostics133134When a user asks "why is my lead flow low these past few days?", follow this systematic approach.135136**Steps:**1371. **Confirm Drop**: Query conversions segmented by date for the last few days vs the previous period.1382. **Isolate Cause**:139 * Check if **Traffic** (clicks, impressions) dropped.140 * Check if **Conversion Rate** (conversions/clicks) dropped.141142 **Example GAQL Query (Traffic and Conversion Trends):**143 To query traffic and conversion rate metrics across campaigns segmented by date:144 ```sql145 SELECT146 campaign.id,147 campaign.name,148 segments.date,149 metrics.impressions,150 metrics.clicks,151 metrics.ctr,152 metrics.conversions,153 metrics.conversions_from_interactions_rate154 FROM campaign155 WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'156 ORDER BY segments.date DESC157 ```1581593. **If Traffic Dropped**: Check Impression Share metrics (see Workflow 2) to see if it's a budget or rank issue, or if search volume generally declined.1604. **If Conversion Rate Dropped**: Check breakdowns by `segments.device` or `segments.conversion_action` to see if a specific area is failing.1615. **Check Changes**: Query the `change_event` resource to see if any changes were made to bids, budgets, or targeting around the time the drop started.162 * *Gotcha (change_event constraints)*: Queries to the `change_event` resource:163 * Must specify a `LIMIT` clause of less than or equal to 10000.164 * Must filter by date (`change_event.change_date_time`) within the past 30 days.165 * Cannot select performance metrics (e.g., `metrics.*` is not supported; only `change_event` attributes and allowed resource fields can be selected).166167 **Example GAQL Query:**168 To query change events for a customer account `{customer_id}` between `{start_date}` and `{end_date}`:169 ```sql170 SELECT171 change_event.change_date_time,172 change_event.change_resource_name,173 change_event.resource_change_operation,174 change_event.changed_fields175 FROM change_event176 WHERE change_event.change_date_time >= '{start_date}' AND change_event.change_date_time <= '{end_date}'177 LIMIT 10000178 ```179180### 4. Offline Upload Pipeline Diagnostics181182When offline conversion uploads for a specific action (e.g., store-purchase) stop showing up or fail, use the following steps to diagnose the issue.183184**Steps:**1851. **Retrieve Client Accounts**: If `{customer_id}` is not provided, follow [Identifying Active Client Accounts](#identifying-active-client-accounts) to retrieve active client customer accounts.1861872. **Verify Pipeline Health**: Query `offline_conversion_upload_conversion_action_summary` for the active client account.188 * **Fields**: Include `offline_conversion_upload_conversion_action_summary.conversion_action_name`, `offline_conversion_upload_conversion_action_summary.successful_event_count`, `offline_conversion_upload_conversion_action_summary.total_event_count`, and `offline_conversion_upload_conversion_action_summary.status`.189190 **Example GAQL Query:**191 ```sql192 SELECT193 offline_conversion_upload_conversion_action_summary.conversion_action_name,194 offline_conversion_upload_conversion_action_summary.successful_event_count,195 offline_conversion_upload_conversion_action_summary.total_event_count,196 offline_conversion_upload_conversion_action_summary.status197 FROM offline_conversion_upload_conversion_action_summary198 ```1992003. **Analyze**:201 * *Gotcha*: If the query to `offline_conversion_upload_conversion_action_summary` returns no results or is empty (indicating there are no offline conversion uploads configured or active for the customer account), immediately stop/break the diagnostic workflow. Report directly to the user that no offline conversion upload data or summaries exist in the accessible account(s), rather than retrying or attempting to generate custom scripts.202 * If results are returned, verify the upload success rate by comparing `successful_event_count` with `total_event_count`. Check the `status` field to diagnose failures.203