analyze_pmax_search_terms

POST https://api.adspirer.ai/api/v1/tools/analyze_pmax_search_terms/execute

See the actual search terms a Performance Max campaign matched, with per-term metrics. ⚠️ READ-ONLY. Safe to call repeatedly. Performance Max search terms live in a different Google Ads resource (campaign_search_term_view) than Search-campaign terms, so `analyze_search_terms` returns "No search term data" for a PMax campaign. Use THIS tool for a PMax campaign. **What you get, per search term:** cost, clicks, impressions, conversions, conversion value, CTR, CPC — the raw numbers the user needs to spot high-cost / zero-conversion queries and converting queries, and decide what to do. **High-volume — do NOT page through everything.** PMax campaigns can have thousands of search terms. The response ALREADY gives you the answer without paging: - Results are sorted by cost (biggest spender first), so the top page is the highest-spend set — the terms most worth reviewing. - A **summary** line reports totals over the WHOLE set (term count, total cost, total conversions, and how many terms recorded 0 conversions and the spend on them) — read that instead of enumerating every term. These are facts; whether a 0-conversion term is a problem depends on the account (some are upper-funnel or tracked elsewhere) — surface the number, let the user decide. - To find something specific, **filter with `query` or re-rank with `sort_by`** — don't walk page after page. Paging is capped (you cannot page past the top ~100). Controls: - `sort_by`: cost (default), clicks, impressions, conversions, conversion_value, ctr, cpc - `sort_order`: desc (default) or asc - `query`: free-text filter on the term (e.g. 'free' to surface low-intent queries) - `offset` / `limit`: only if you truly need more of the same ranking; check `has_more` **Parameters:** - campaign_id (required): the Performance Max campaign ID (from list_campaigns) - lookback_days: 7, 30, 60, 90, or 120 (default 30) - customer_id: required for multi-account users (from get_connections_status) **Use when:** "show me the search terms for my PMax campaign", "what queries is Performance Max spending on?", "find wasted spend / irrelevant queries in PMax".

{
  "arguments": {
    "campaign_id": "<campaign_id>",
    "customer_id": "string",
    "lookback_days": 30,
    "query": "string",
    "sort_by": "string",
    "sort_order": "desc",
    "offset": 0
  }
}

{
  "success": true,
  "data": {
    "text": "(tool-specific textual output for analyze_pmax_search_terms)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "analyze_pmax_search_terms"
}

{
  "success": false,
  "error": "You have 25 meta_ads accounts connected. Please specify which account to use by passing the ad_account_id parameter:\n  - Acme Holdings (ad_account_id=\"act_123456789\")\n  - Acme EU (ad_account_id=\"act_987654321\")",
  "is_error": true,
  "tool": "analyze_pmax_search_terms"
}

{
  "success": false,
  "error": "\ud83d\udea8 Monthly limit reached (150/150 tool calls on Plus tier).\nUpgrade to Pro at https://adspirer.ai to keep building.",
  "is_error": true,
  "tool": "analyze_pmax_search_terms",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}