List every customer_id the OAuth user has direct access to.

This is a small, cheap list, typically just the MCC itself and any standalone accounts. For the full tree of accounts under the MCC (agency use case), call google_ads_list_customer_clients instead.

Returns: {"resource_names": [...], "customer_ids": [...]}. Each customer_id is 10 digits, no hyphens.

Walk the MCC (Manager Account) hierarchy and return every child account.

For agency use: this is the canonical "which clients can I query?" call. Uses GAQL on the customer_client resource. Fast: one streaming call.

Args: mcc_customer_id: MCC customer_id. Defaults to GOOGLE_ADS_LOGIN_CUSTOMER_ID (the configured MCC). Accepts 10-digit or hyphenated. include_managers: include sub-MCCs in the result (default True). include_hidden: include customer_clients marked hidden=True (default False). max_level: max hierarchy depth (default 3, hard cap 10).

Returns per account: customer_id, descriptive_name, currency_code, time_zone, manager (bool), level, status (ENABLED|CANCELED|…), hidden, resource_name.

Run a GAQL (Google Ads Query Language) query against a specific customer account.

GAQL is SQL-like: SELECT ... FROM <single_resource> WHERE ... ORDER BY ... LIMIT .... No JOINs; attribute fields from related resources by selecting them directly. Common resources: campaign, ad_group, keyword_view, search_term_view, shopping_performance_view, customer, customer_client, conversion_action, change_event, change_status, recommendation, asset, asset_group.

Use google_ads_describe_resource first if unsure of field names on a new resource; saves a FIELD_NOT_FOUND roundtrip.

Args: customer_id: 10-digit customer_id (no hyphens) for the account to query. gaql: the full GAQL query string (must start with SELECT; no semicolons). max_rows: if set, stop streaming after this many rows. Defaults to unbounded (the 64 MB response cap still applies). convert_micros: if True (default), also emit _units alongside any _micros field (divided by 1,000,000). E.g. cost_micros = 12345678 → cost_units = 12.345678.

Example queries:

SELECT campaign.id, campaign.name, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS ORDER BY metrics.cost_micros DESC LIMIT 50

SELECT ad_group.name, ad_group_criterion.keyword.text, metrics.impressions, metrics.clicks FROM keyword_view WHERE segments.date DURING LAST_30_DAYS

SELECT segments.product_item_id, metrics.conversions_value FROM shopping_performance_view WHERE segments.date DURING LAST_30_DAYS

Gotchas (surface to user where relevant):

• metrics.cost_micros: 1 unit = $0.000001. Divide by 1M for currency.

• LAST_30_DAYS = 30 days ending YESTERDAY (today excluded).

• Last 72h data is partial; conversions retroactively re-attribute.

• Zero-metric rows are excluded when segmenting by date.

• Response cap is 64 MB per call; split by date range for huge reports.

• GAQL IN (...) clause is capped at 20,000 items.

Schema (fields, metrics, segments) for a GAQL resource.

Queries GoogleAdsFieldService for every selectable field on a resource plus its data type, selectability, filterability, sort-ability, and selectable_with (which other fields can coexist in a single SELECT).

Args: resource_name: the GAQL resource, e.g. "campaign", "ad_group", "shopping_performance_view", "change_event", "recommendation".

Returns: {resource, fields: [{name, category: ATTRIBUTE|METRIC|SEGMENT, data_type, selectable, filterable, sortable, enum_values, type_url, selectable_with}]}.

Essential before composing GAQL on an unfamiliar resource; prevents FIELD_NOT_COMPATIBLE and FIELD_NOT_FOUND errors.

Return the full catalog of GAQL resources (FROM-able tables).

Useful when the agent needs to pick the right resource for a question. Each entry: name, category, selectable (whether it can be the FROM target).

Response is cacheable for the session; the catalog is stable across queries.

Read Google's optimization recommendations for a customer account.

Returns suggestions only; does NOT apply any. Types include: KEYWORD, CAMPAIGN_BUDGET, KEYWORD_MATCH_TYPE, TARGET_CPA_OPT_IN, MAXIMIZE_CLICKS_OPT_IN, OPTIMIZE_AD_ROTATION, RESPONSIVE_SEARCH_AD, ENHANCED_CPC_OPT_IN, SEARCH_PARTNERS_OPT_IN, SITELINK_EXTENSION, CALL_EXTENSION, CALLOUT_EXTENSION, STRUCTURED_SNIPPET_EXTENSION, DISPLAY_EXPANSION_OPT_IN, KEYWORD_MATCH_TYPE, FORECASTING_*, SHOPPING_*, MOVE_UNUSED_BUDGET. (Google adds new types over time.)

Args: customer_id: 10-digit account ID. types: optional list to filter by recommendation_type. Case-sensitive. dismissed: include dismissed recommendations (default False). limit: max rows (default 200).

Each row contains: type, impact (absolute_metrics, base_metrics, potential_metrics), campaign / ad_group ref (if applicable), dismissed flag, recommendation-specific payload (e.g. suggested_keywords, budget_increase).

Generate keyword ideas with search volume + competition + CPC estimates.

Args: customer_id: customer_id to attribute the request (any Ads account under MCC works). keywords: seed keywords, list of strings. Optional if page_url is given. page_url: seed URL (crawled for keyword extraction). Optional if keywords given. language_id: Google language criterion ID. Default '1000' (English). Common: '1001' Spanish, '1002' French, '1003' German, '1007' Italian. geo_target_ids: list of geo criterion IDs. Default ['2840'] (US). Common: '2826' UK, '2124' Canada, '2036' Australia, '2276' Germany. keyword_network: GOOGLE_SEARCH (default) | GOOGLE_SEARCH_AND_PARTNERS. include_adult: include adult-category keywords (default False). page_size: max ideas to return (default 100, capped at 10000).

Returns: {ideas: [{text, avg_monthly_searches, competition, low_top_of_page_bid_micros, high_top_of_page_bid_micros, concept_group}]}.

Rate limit: 1 QPS for this service. Back off on RESOURCE_EXHAUSTED. Requires Basic Access (Explorer may 403); if you get USER_PERMISSION_DENIED, the dev_token tier is too low.

Historical monthly search-volume + competition metrics for specific keywords.

Args: customer_id: 10-digit customer_id. keywords: list of keyword strings (max 10,000 per call). language_id / geo_target_ids / keyword_network: same shape as keyword_ideas. year_month_start / year_month_end: optional date range as {year: 2025, month: 1..12}. Defaults to last 12 months.

Returns: {results: [{text, approximate_monthly_searches, monthly_search_volumes: [{year, month, monthly_searches}], competition, high/low_top_of_page_bid_micros}]}.

Rate limit: 1 QPS. May require Basic Access.

Forecast KPIs (impressions, clicks, cost, conversions) for a proposed keyword plan.

Args: customer_id: 10-digit customer_id. campaign_spec: a KeywordPlanCampaign forecast spec. Minimum shape: { "bidding_strategy": "MANUAL_CPC", "daily_budget_micros": 10000000, "keyword_match_type": "BROAD" | "PHRASE" | "EXACT", "language_id": "1000", "geo_target_ids": ["2840"], "keywords": ["running shoes", "trail running shoes"] }

Returns: {campaign_forecast: {impressions, clicks, cost_micros, conversions, average_cpc_micros}, weekly_time_series: [...]}.

Rate limit: 1 QPS. Requires Basic Access.

Audit trail: who changed what in the last 30 days.

Max window is 30 days back. Returns: change_date_time, user_email, change_resource_type (CAMPAIGN|AD_GROUP|AD_GROUP_CRITERION|CAMPAIGN_BUDGET| AD|AD_GROUP_BID_MODIFIER|…), old_resource, new_resource, changed_fields, client_type (GOOGLE_ADS_WEB_CLIENT|GOOGLE_ADS_API|…).

Args: customer_id: 10-digit customer_id. days_back: 1–30. resource_types: optional filter to specific change_resource_type enum values. limit: max rows (default 10000, capped 100000).

Lightweight change tracker: last-modified-at timestamps for resources.

Unlike change_event, this is a per-resource "last modified" view rather than a change-diff log. Covers up to 14 days.

Args: customer_id: 10-digit customer_id. days_back: 1–14. resource_types: optional filter by change_status.resource_type enum. limit: max rows.