API Reference › Google Ads › analyze_pmax_search_categories

analyze_pmax_search_categories

Google Ads Read

See the search CATEGORIES a Performance Max campaign matched (grouped queries), with metrics

Endpoint

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

Headers

Description

See the search CATEGORIES a Performance Max campaign matched (grouped queries), with metrics. ⚠️ READ-ONLY. Safe to call repeatedly. This reads campaign_search_term_insight — Google's aggregated view that groups a Performance Max campaign's queries into search categories (themes), each with its own clicks, impressions, conversions, and conversion value. It complements `analyze_pmax_search_terms` (individual terms): categories show the shape of demand at a theme level. Google returns a residual "(Other search terms)" bucket for long-tail queries it doesn't categorize. **High-volume — this pages** (same interface as analyze_pmax_search_terms): - `sort_by`: impressions (default), clicks, conversions, conversion_value - `sort_order`: desc (default) or asc - `query`: free-text filter on the category name - `offset` / `limit`: check `has_more` and re-call with a bigger offset **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 **Use when:** "what search themes is my PMax campaign showing for?", "break down PMax demand by category", "which search categories convert best in Performance Max".

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
campaign_idstring requiredPerformance Max campaign ID (required). Get it from list_campaigns.
customer_idstring optionalGoogle Ads customer ID. Required for multi-account users. Get from get_connections_status.
lookback_daysinteger optionalTrailing window in days: 7, 30, 60, 90, or 120. Default 30. default: 30
querystring optionalFree-text filter — case-insensitive substring match against the search term / category text. E.g. 'free' to surface low-intent queries.
sort_bystring optionalSort field. Terms: cost (default), clicks, impressions, conversions, conversion_value, ctr, cpc. Categories: impressions (default), clicks, conversions, conversion_value.
sort_orderstring optional'desc' (default, biggest first) or 'asc'. default: "desc"
offsetinteger optionalRow offset for paging (0-based). Default 0. Paging is capped near the top (you cannot page far into a large result) — filter with `query` or re-sort instead of paging deep. default: 0
limitinteger optionalRows per page (1-200). Default 100 — one call shows the top 100 by your sort, which is almost always enough. default: 100

Example request

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

Example responses

200 — Success

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

400 — Tool-level error (bad arguments / multi-account selection)

{
  "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_categories"
}

402 — Quota exhausted

{
  "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_categories",
  "quota": {
    "used": 150,
    "limit": 150,
    "tier": "plus",
    "period_end": "2026-05-01",
    "upgrade_url": "https://adspirer.ai"
  }
}

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Google Ads · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai