get_meta_adset_performance

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

User wants ad-set-level Meta performance — the middle layer between campaigns and individual ads. Use this when the user asks about ad set performance, has accounts with one campaign and many ad sets, or wants to compare audiences/budgets at the ad set level. This tool fills the gap between `get_meta_campaign_performance` (campaign rollups) and `analyze_meta_ad_performance` (per-ad creatives). Returns: - Per-ad-set metrics: spend, impressions, CTR, frequency, conversions, CPA, ROAS, reach - Top performing ad sets (ranked by ROAS when conversions exist, else CTR) - Underperforming ad sets (high spend, zero conversions, or ROAS < 1) - Frequency fatigue alerts (frequency ≥ 3.0) - Recommendations for budget reallocation and creative refresh When to use this tool: - "How are my Meta ad sets performing?" - "Which ad sets in this campaign are best?" - "Compare ad set performance across audiences" - "Find ad sets with high frequency" - "Which ad sets should I scale or pause?" - Any question about ad-set-level (ad group / audience-level) Meta performance Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - date_range: preset alternative to lookback_days / start_date / end_date. One of: 'last_7_days', 'last_14_days', 'last_30_days', 'last_60_days', 'last_90_days'. (Both 'last_30_days' and 'last_30d' / 'last_month' aliases accepted.) - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently"), ask the user to specify exact dates before calling this tool. - campaign_id: Optional - filter to a single campaign (recommended when one campaign has many ad sets) - include_video_metrics: true (default) or false - include_recommendations: true (default) or false - limit: max ad sets to return (default 100, max 200) - offset: pagination offset (default 0) - ad_account_id: Required for multi-account users. Get from get_connections_status. Execution time: 1-3 seconds (cached database query) Data source: ad_group_daily_metrics table (Meta ad sets stored as ad groups)

{
  "arguments": {
    "start_date": "string",
    "end_date": "string",
    "date_range": "string",
    "raw_data": false,
    "lookback_days": 30,
    "campaign_id": "string"
  }
}

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

{
  "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": "get_meta_adset_performance"
}

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