Skip to main content

​
Overview

The Google Ads integration gives your agents live, read-only reporting access through the official Google Ads API. Agents can discover the customers available to the connected Google account and use Google Ads Query Language (GAQL) to analyze campaign structure, delivery, spend, clicks, conversions, and segmented performance. An Aster admin connects one Google account for the organization through Aster’s Google OAuth application. Google Ads API access is granted to the Google Cloud project that owns Aster’s OAuth client; customers do not need to apply for API access or supply a developer token.
Google Ads offers one OAuth scope for both reads and writes. Aster keeps this initial integration read-only by exposing only customer discovery and the Google Ads Search reporting endpoint. No mutate endpoints are registered as agent tools.

​
Prerequisites

  • A Google account with direct or manager-level access to at least one Google Ads customer
  • An Aster admin to connect the shared organization integration
  • For manager-account reporting, the manager customer ID and target advertiser customer ID

​
Setup Guide

1

Connect Google Ads in Aster Agents

Navigate to Control Hub > Integrations, locate Google Ads, and click Connect.
2

Authorize the Google account

Sign in with a Google account that can access the relevant advertiser or manager accounts, then approve the Google Ads permission. Tokens stay server-side and refresh automatically.
3

Add Google Ads tools to an agent

Edit the agent and enable Google Ads: List Accounts and Google Ads: Query. The agent can discover customer IDs first, then run GAQL reports against the selected customer.

​
Available Tools

  • Google Ads: List Accounts (google_ads_list_accounts) — Lists customers directly accessible to the connected Google user. By default, it also retrieves each account’s name, currency, time zone, status, manager flag, and test-account flag. Set include_details to false for faster ID-only discovery when the user has many directly accessible accounts.
  • Google Ads: Query (google_ads_query) — Runs one read-only GAQL SELECT query against a customer. It accepts an optional login_customer_id for manager-to-client access and an opaque page_token for pagination. Google Ads returns fixed pages of up to 10,000 rows.
Large result pages are also attached as flattened CSV files. The agent receives a token-bounded inline preview and can use execute_python to analyze the complete CSV without filling the conversation context.

​
Manager account example

When a manager account 1234567890 has access to advertiser 0987654321:
  • customer_id: 0987654321
  • login_customer_id: 1234567890
Customer IDs may be entered with or without hyphens; Aster normalizes them before calling Google.

​
GAQL example

Fields ending in _micros, such as metrics.cost_micros, are expressed in millionths of the customer’s currency. Divide by 1,000,000 to get the standard currency amount.

​
Example Prompts

  • “List the Google Ads accounts I can access and identify which are manager accounts.”
  • “Show spend, clicks, conversions, and cost per conversion by campaign for the last 30 days.”
  • “Compare branded and non-branded search keyword performance this month.”
  • “Which campaigns lost the most conversion volume versus the prior 30 days?”
  • “Break down impressions, clicks, cost, and conversions by device for this quarter.”

​
Security Considerations

  • Read-only tool surface — the registered tools call only account discovery and GAQL search. They cannot create, update, or remove Google Ads resources.
  • Shared org connection — one admin authorizes an account for the organization. Grant Google Ads tools only to agents that should see advertising data.
  • Least Google Ads access — use a Google user whose Ads role and account hierarchy match the customers agents should be able to query.
  • Server-side credentials — OAuth tokens are never returned to the browser or agent.
  • Revoke any time — disconnect Google Ads from Control Hub > Integrations or revoke Aster from Google Account permissions.

​
Troubleshooting

google_ads_list_accounts returns customers to which the connected Google user has direct access. Reconnect with the correct Google account or grant that user access in Google Ads.
When access is inherited through a manager account, pass the manager’s customer ID as login_customer_id and the advertiser’s customer ID as customer_id. Use digits only or the usual hyphenated format.
The Google Cloud project that owns Aster’s OAuth client must have the Google Ads API enabled. Test access can query only test accounts; production accounts require Explorer, Basic, or Standard access. Aster manages this project-level access in the Google Ads API Overview page.
GAQL fields are resource-specific and some metrics or segments cannot be selected together. Start with a small query against one resource, then add fields incrementally. The Google Ads Query Builder can validate compatible fields.
Pass next_page_token from the result back as page_token with the identical query and customer IDs. Each returned page is attached as its own CSV when file output is available.