Google Ads API Account Performance Diagnostics

ANÁLISE EDITORIAL

Google Ads API Account Performance Diagnostics é uma Agent Skill mantida pelo time da Google Ads API para organizar uma investigação que costuma começar com uma pergunta vaga, como “por que as conversões caíram?”. Em vez de saltar direto para uma recomendação de orçamento ou lance, ela orienta o agente a identificar a conta correta, consultar métricas por período e segmento, separar perda de tráfego de perda de taxa de conversão e procurar mudanças recentes que possam explicar o resultado.

O ponto mais importante é o limite do que ela entrega. A Skill não administra campanhas sozinha, não cria anúncios e não corrige a conta. Ela contém instruções em Markdown para um agente que já tenha acesso autorizado a ferramentas de consulta da Google Ads API por MCP. O resultado esperado é um diagnóstico com evidências consultáveis, não uma promessa de melhora.

Imagem editorial exclusiva do Bastidores da IA. Não é captura de tela, interface real nem prova de diagnóstico executado.

O que esta Skill faz de verdade

A versão 1.0 auditada descreve quatro fluxos. O primeiro procura perdas de conversão ou de valor de conversão, comparando períodos e decompondo os dados por data, dispositivo e ação de conversão. O segundo consulta participação de impressões e a parcela perdida por orçamento ou Ad Rank. O terceiro investiga baixo volume de leads, começando pela diferença entre queda de tráfego e queda de taxa de conversão. O quarto verifica resumos de upload de conversões offline quando esse recurso existe na conta.

A Skill usa a linguagem de consulta do Google Ads, a GAQL. A documentação oficial da GAQL explica que recursos, atributos, métricas e segmentos podem ser selecionados nas consultas. Isso ajuda a entender por que uma análise por campanha pode ser dividida por data, dispositivo ou ação de conversão, mas também mostra que a qualidade do diagnóstico depende dos campos escolhidos e da compatibilidade entre eles.

Para mudanças recentes, a instrução consulta o recurso change_event. A referência oficial de Change Event exige intervalo dentro dos últimos 30 dias e um limite de no máximo 10.000 linhas. O próprio Google ressalva que esse recurso pode não incluir toda mudança visível no histórico da interface. Portanto, ausência de evento não deve ser apresentada como prova de que nada mudou.

Para quem serve

Ela faz sentido para analistas de mídia, equipes de dados, desenvolvedores de integrações e responsáveis por operações que já usam Google Ads API e precisam transformar uma queda percebida em perguntas verificáveis. Também pode servir como roteiro de revisão humana, mesmo quando o agente não será autorizado a executar as consultas.

Não é uma boa escolha para quem quer configurar uma campanha nova, fazer upload de eventos, alterar lances ou receber uma explicação geral sobre Google Mobile Ads SDK. Esses usos estão explicitamente fora do escopo do SKILL.md. A página também não substitui análise de negócio: sazonalidade, mudança de oferta, qualidade do lead, falha de página e restrições comerciais podem não aparecer apenas nas métricas consultadas.

Compatibilidade e pré-requisitos

O arquivo segue o formato de Agent Skills e pode ser carregado por clientes compatíveis com SKILL.md. Porém, o uso completo depende de um servidor MCP da Google Ads API que ofereça as ferramentas citadas pela instrução, como listar clientes acessíveis, pesquisar recursos e consultar metadados de campos. Se o seu cliente não expõe essas ferramentas com nomes e argumentos compatíveis, a Skill continua útil como documentação, mas não fica operacional automaticamente.

Também são necessários acesso autorizado à conta, um projeto configurado e credenciais adequadas. O início rápido oficial da Google Ads API lista token de desenvolvedor, projeto no Google API Console, autenticação e Customer ID entre os pré-requisitos. O nível do token define se as chamadas podem alcançar somente contas de teste ou contas de produção.

A API usa OAuth 2.0 e também exige token de desenvolvedor, conforme a visão geral oficial de autenticação. Credenciais de aplicativo e de usuário precisam de tratamento semelhante a senhas. A orientação de gerenciamento de credenciais recomenda armazenamento seguro e proíbe colocar segredos em repositórios públicos.

Instalação recomendada

O repositório oficial documenta a instalação pelo Skills CLI com npx skills add google/skills, seguida da seleção da Skill desejada. Faça isso primeiro em um projeto de teste. Confira se a pasta criada corresponde a skills/ads/google-ads-api-account-diagnostics, leia o arquivo instalado e fixe o commit aprovado quando o seu processo permitir.

O botão de download desta página entrega um pacote documental auditado, útil para leitura e comparação de hash. Ele não contém o servidor MCP nem qualquer runtime. Para acompanhar mudanças do mantenedor, use separadamente o botão do repositório oficial da Skill.

Configuração antes do primeiro uso

Comece definindo a conta e o período. Se houver uma conta administradora, não presuma que ela é o cliente a ser diagnosticado. A Skill manda listar clientes acessíveis e filtrar contas ativas que não sejam gerenciadoras. Confirme o Customer ID com o responsável pela mídia antes de consultar métricas.

Em seguida, limite permissões. Um diagnóstico de leitura não precisa de autorização para criar campanha, alterar orçamento ou enviar conversões. Valide o projeto OAuth, o usuário ou conta de serviço, o nível do token de desenvolvedor e os escopos necessários. Nunca cole tokens, segredos ou arquivos JSON de credencial no prompt.

Por fim, defina o critério de comparação. “Últimos dias” é ambíguo. Registre datas, fuso da conta, janela anterior comparável e eventos comerciais relevantes. Uma comparação de três dias contra uma semana inteira pode produzir uma narrativa convincente e errada.

Primeiro uso seguro

1. Use uma conta de teste ou uma conta de produção com acesso somente de leitura compatível com o diagnóstico.
2. Peça primeiro a lista de clientes acessíveis e confirme manualmente o Customer ID correto.
3. Escolha uma pergunta pequena, por exemplo, identificar se a queda veio de tráfego ou taxa de conversão em um período definido.
4. Solicite a consulta e guarde a GAQL usada, os campos, o período e o horário da coleta.
5. Revise os números no contexto da conta e não autorize alteração automática com base na primeira hipótese.

A Skill lembra que metrics.cost_micros precisa ser dividido por 1.000.000 para chegar à unidade monetária padrão. Ela também trata participação de impressões como proporção, não como porcentagem já formatada. A referência oficial de métricas documenta faixas e convenções específicas, inclusive valores limítrofes. Preserve essas convenções no relatório para não transformar 0,35 em 0,35%.

Resultado esperado

Uma boa saída deve dizer qual conta e período foram consultados, quais campos entraram na análise, onde a queda se concentrou e o que ainda não foi explicado. Um exemplo de conclusão responsável seria: “no período informado, a redução apareceu principalmente em campanhas móveis e coincidiu com menor tráfego; a consulta não comprova causa, e o histórico de mudanças precisa ser revisado”.

Quando há conversões offline, a Skill consulta resumos por ação de conversão. A documentação de diagnósticos de upload descreve status, totais, eventos bem-sucedidos, pendentes e alertas. Se a consulta não retorna resumo, a instrução manda parar esse ramo e informar que não há dados disponíveis, em vez de inventar um pipeline ou tentar gerar script alternativo.

Permissões e riscos

O arquivo distribuído é texto, mas o fluxo operacional acessa dados comerciais de uma conta de anúncios. Campanhas, custos, conversões, nomes internos e eventos de mudança podem ser confidenciais. Use conta, projeto e credenciais controlados pela organização. Limite retenção de resultados e remova identificadores antes de compartilhar exemplos.

O segundo risco é transformar correlação em causa. Uma perda de participação por orçamento é uma evidência sobre elegibilidade de impressão, não uma ordem para aumentar verba. Uma mudança registrada perto da queda também não prova que ela causou o problema. Qualquer decisão de lance, orçamento, criativo ou medição continua com o responsável humano.

O terceiro risco é o custo operacional da própria plataforma. Níveis de acesso, cotas e disponibilidade variam. Consulte a checklist oficial para desenvolvedores e o nível atual do token antes de planejar consultas recorrentes. Esta página não informa preço nem promete acesso de produção.

Erros comuns

• Consultar a conta gerenciadora como se fosse cliente: liste clientes acessíveis, filtre contas habilitadas e exclua contas manager.
• Receber erro de campo incompatível: use metadados ou o construtor de consultas para conferir recurso, métrica e segmento antes de insistir.
• Consulta de mudanças rejeitada: use intervalo finito dentro dos últimos 30 dias e LIMIT de no máximo 10.000.
• Valores monetários muito grandes: confira se cost_micros foi convertido para a unidade monetária.
• Resumo offline vazio: informe ausência de dados e pare esse ramo, sem criar código substituto.
• Diagnóstico parece conclusivo demais: separe fatos consultados, interpretação e hipóteses que exigem validação.

Versão auditada e download local

A curadoria foi feita em 14 de agosto de 2026 sobre o commit 9bb184823bd157d9a88d999e2c47ad6dd21fc3fb do repositório google/skills. A API oficial do GitHub registrava 18.142 estrelas na consulta. O frontmatter declara versão 1.0 e mantenedor google-ads-api-team. O repositório usa licença Apache-2.0.

O ZIP local contém somente três arquivos permitidos: SKILL.md, LICENSE e ORIGEM.md. Não há executável, script, servidor MCP, biblioteca, dependência, token, cookie, segredo, credencial ou dado de conta. SHA-256 do pacote: 5d2466034c91f586741fb8b1dbc4d3875faead3ad6f405507066c96da76eb9e1.

Resultado esperado e limite final

Use esta Skill quando precisar tornar uma investigação de desempenho mais ordenada e reproduzível. Espere uma sequência de consultas e uma síntese com limites, não uma otimização automática. Antes de qualquer ação na conta, confirme a hipótese com o analista responsável, revise o período e as segmentações e trate cada alteração como uma decisão separada.

Fontes primárias

• Repositório oficial google/skills.
• SKILL.md no commit auditado.
• Licença Apache-2.0 do repositório.
• Pré-requisitos da Google Ads API.
• Visão geral da GAQL.
• Change Event na Google Ads API.
• Diagnósticos de upload de conversões offline.
• Gerenciamento seguro de credenciais.