google-ads-api-account-diagnostics

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: google-ads-api-account-diagnostics
description: >-
  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).
metadata:
  category: GoogleAds
  author: google-ads-api-team
  version: "1.0"
---

# 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

### 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:
```sql
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.

### Using the MCP Tools Directly
To retrieve information and run queries, you must call the `search` tool on the MCP server directly (with arguments like `customer_id`, `fields`, `resource`, and `conditions`). Do not write or execute custom Python scripts or use the Google Ads client library to query the API, as they will fail authentication inside the evaluation sandbox.

### 1. Conversion and Conversion Value Loss

When conversions or conversion value suddenly decline, use the following steps to diagnose the issue.

**Steps:**
1.  **Discover Fields**: Use `get_resource_metadata` with resource `campaign` or `ad_group` to ensure you have the correct field names.
2.  **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.

    **Example GAQL Query:**
    To query performance data for a customer account `{customer_id}` between `{start_date}` and `{end_date}`:
    ```sql
    SELECT
      campaign.name,
      metrics.conversions,
      metrics.conversions_value,
      metrics.cost_micros,
      segments.date,
      segments.device,
      segments.conversion_action
    FROM campaign
    WHERE segments.date >= '{start_date}' AND segments.date <= '{end_date}'
    ```

3.  **Analyze**: Check if the loss is limited to certain devices (e.g., mobile vs desktop) or specific conversion actions.
4.  **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