google-ads-api-account-diagnostics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Ads API Account Performance Diagnostics Skill

Google Ads API 账户性能诊断Skill

This skill provides instructions on how to use the Google Ads MCP server tools to diagnose common account performance issues.

本Skill提供了如何使用Google Ads MCP服务器工具诊断常见账户性能问题的说明。

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.

大多数诊断任务需要向特定客户账户发送GAQL查询。如果用户未明确提供客户ID，您必须先调用

list_accessible_customers

（或

customers_list_accessible_customers

）工具来获取您有权访问的客户资源名称/ID。

获取可访问的客户ID列表后，在这些客户账户下使用

search

工具查询

customer_client

资源，以找到活跃的客户账户。确保仅选择已启用的客户账户，并过滤掉管理账户：

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

后续的诊断查询仅针对从此列表中获取的已启用客户账户ID执行。请勿查询已停用或管理账户，否则会导致API错误。

Using the MCP Tools Directly

直接使用MCP工具

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.

要检索信息并运行查询，您必须直接在MCP服务器上调用

search

工具（参数包括

customer_id

、

fields

、

resource

和

conditions

）。请勿编写或执行自定义Python脚本，也不要使用Google Ads客户端库查询API，因为它们在评估沙箱中会验证失败。

1. Conversion and Conversion Value Loss

1. 转化与转化价值损失

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.

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}'

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}

sql

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

当转化量或转化价值突然下降时，使用以下步骤诊断问题。

步骤：

发现字段：使用
```
get_resource_metadata
```
并指定资源
```
campaign
```
或
```
ad_group
```
，确保您使用正确的字段名称。

查询性能数据：使用

search

检索性能数据。

资源：
```
campaign
```
或
```
ad_group
```

字段：包含

campaign.name

、

metrics.conversions

、

metrics.conversions_value

、

metrics.cost_micros

。

细分维度：为了定位损失来源，可包含
```
segments.date
```
、
```
segments.device
```
、
```
segments.conversion_action
```
等细分维度。
条件：将下降期间与之前的时间段进行比较（例如
```
segments.date >= '{start_date}'
```
）。
注意事项：
```
metrics.cost_micros
```
必须除以1,000,000才能得到标准货币金额。

GAQL查询示例： 查询客户账户

{customer_id}

在

{start_date}

至

{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}'

分析：检查损失是否局限于特定设备（如移动设备vs桌面设备）或特定转化操作。

检查上传情况：如果使用离线导入，查询

offline_conversion_upload_conversion_action_summary

以验证上传管道的健康状况。如果查询无结果，说明该账户不存在离线上传，直接向用户报告并继续后续操作。

GAQL查询示例： 检查客户账户

{customer_id}

的上传管道健康状况：

sql

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)

2. 机会流失（展示份额）

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}

sql

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).

要识别因广告排名、出价或预算导致的机会流失，需分析展示份额指标。

步骤：

查询展示份额：使用

search

检索展示份额指标。

资源：
```
campaign
```

字段：包含

campaign.name

、

metrics.search_impression_share

、

metrics.search_rank_lost_impression_share

、

metrics.search_budget_lost_impression_share

。

注意事项：API返回的展示份额值为小数（例如0.35 = 35%）或格式化字符串（例如
```
"< 0.10"
```
）。

GAQL查询示例： 查询客户账户

{customer_id}

在

{start_date}

至

{end_date}

期间的展示份额指标：

sql

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}'

分析：
- 较高的
```
search_budget_lost_impression_share
```
  表示因预算有限导致机会流失。
- 较高的
```
search_rank_lost_impression_share
```
  表示因广告排名低（出价或质量问题）导致机会流失。

3. Low Lead Flow Diagnostics

3. 潜在客户流量低的诊断

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

当用户询问“为什么最近几天我的潜在客户流量很低？”时，请遵循以下系统化方法。

步骤：

确认下降情况：按日期细分查询最近几天与之前时间段的转化数据。
定位原因：
- 检查流量（点击量、展示量）是否下降。
- 检查转化率（转化量/点击量）是否下降。
如果流量下降：检查展示份额指标（参见工作流程2），判断是预算、排名问题，还是整体搜索量下降。
如果转化率下降：按
```
segments.device
```
或
```
segments.conversion_action
```
细分数据，查看是否是特定领域出现问题。
检查变更记录：查询
```
change_event
```
资源，查看下降开始前后是否有出价、预算或定向设置的变更。
- 注意事项（change_event约束）：查询
```
change_event
```
  资源时：
  - 必须指定
```
LIMIT
```
    子句，且值小于或等于10000。
  - 必须按日期过滤（
```
change_event.change_date_time
```
    ），且日期在过去30天内。
  - 不能选择性能指标（例如不支持
```
metrics.*
```
    ；仅可选择
```
change_event
```
    属性和允许的资源字段）。
GAQL查询示例： 查询客户账户
```
{customer_id}
```
在
```
{start_date}
```
至
```
{end_date}
```
期间的变更事件：
sql
```
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

4. 离线上传管道诊断

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, first call the

list_accessible_customers

(or

customers_list_accessible_customers

) tool to retrieve the customer resource names/IDs you have access to. Then, query the

customer_client

resource to find active client customer accounts, ensuring you filter out manager accounts and deactivated/canceled accounts to avoid query errors.

Example GAQL Query:

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

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:

sql

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.

当特定操作（例如到店购买）的离线转化上传停止显示或失败时，使用以下步骤诊断问题。

步骤：

获取客户账户：如果未提供

{customer_id}

，先调用

list_accessible_customers

（或

customers_list_accessible_customers

）工具获取您有权访问的客户资源名称/ID。然后查询

customer_client

资源以找到活跃的客户账户，确保过滤掉管理账户和已停用/取消的账户，避免查询错误。

GAQL查询示例：

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

验证管道健康状况：针对活跃客户账户查询

offline_conversion_upload_conversion_action_summary

。

字段：包含

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

。

GAQL查询示例：

sql

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

分析：
- 注意事项：如果对
```
offline_conversion_upload_conversion_action_summary
```
  的查询无结果或为空（表明该客户账户未配置或未启用离线转化上传），请立即停止诊断流程。直接向用户报告可访问账户中不存在离线转化上传数据或汇总信息，不要重试或尝试生成自定义脚本。
- 如果返回结果，通过比较
```
successful_event_count
```
  与
```
total_event_count
```
  验证上传成功率。查看
```
status
```
  字段诊断失败原因。