> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Ads

> Connect Google Ads to your Agents for live campaign, ad, keyword, conversion, and performance reporting

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

<Note>
  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.
</Note>

## Prerequisites

* A **Google account** with direct or manager-level access to at least one [Google Ads](https://ads.google.com/) 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

<Steps>
  <Step title="Connect Google Ads in Aster Agents">
    Navigate to **Control Hub > Integrations**, locate **Google Ads**, and click **Connect**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

In agent conversations, nonempty result pages are also attached as flattened CSV files using Aster's shared spill system. The agent receives a token-bounded inline preview and can use [`execute_python`](/tools/execute_python) to analyze the complete fetched page without filling the conversation context. Each CSV contains only that page, not unfetched pages; use `next_page_token` to continue.

`full_result_available` reports whether every fetched row is available inline or in the attachment. If an export fails, `attachment_error` explains the failure; a shortened preview is not a complete report. Direct tool calls use the shared byte budget and do not create conversation attachments.

### 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

```sql theme={null}
SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 100
```

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](https://myaccount.google.com/permissions).

## Troubleshooting

<AccordionGroup>
  <Accordion title="No accounts are returned">
    `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.
  </Accordion>

  <Accordion title="USER_PERMISSION_DENIED for a client account">
    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.
  </Accordion>

  <Accordion title="Cloud project access errors">
    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](https://console.cloud.google.com/google/ads-apis/overview) page.
  </Accordion>

  <Accordion title="Invalid GAQL field or resource combination">
    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](https://developers.google.com/google-ads/api/fields/latest/overview_query_builder) can validate compatible fields.
  </Accordion>

  <Accordion title="More than 10,000 rows">
    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.
  </Accordion>
</AccordionGroup>

## Related

* [Google Analytics 4](/integrations/google-analytics) — website traffic, engagement, and conversion reporting.
* [Google Search Console](/integrations/google-search-console) — organic search clicks, impressions, CTR, and rankings.
* [Run Code](/tools/execute_python) — analyze Google Ads CSV attachments with pandas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.