analyze_wasted_spend

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

🚨 **IF THIS TOOL RETURNS A QUOTA ERROR:** - The error message will include a clickable upgrade link - Show the FULL error message to the user (it contains the upgrade link) - DO NOT attempt to work around the error or use alternative data - DO NOT create campaigns or perform actions without valid tool data - STOP and direct the user to upgrade via the provided link Analyze wasted ad spend and identify campaigns losing money or underperforming. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. 🎯 **What This Tool Does (Performance Agent - Phase 1):** - Identifies campaigns LOSING money (ROAS < 1.0x) - Identifies campaigns UNDERPERFORMING (1.0x ≤ ROAS < target) - Separates true waste from opportunity cost - Provides severity-based classification (CRITICAL/HIGH/MEDIUM) - Generates actionable recommendations with expected impact - Shows top performing campaigns for budget reallocation **Returns detailed analysis:** - Total wasted spend (campaigns with ROAS < 1.0) - Total underperforming spend (profitable but below target) - Campaign-by-campaign breakdown with severity levels - Specific recommendations (PAUSE/REDUCE/OPTIMIZE) - Quick actions for immediate implementation - Budget reallocation suggestions **Target ROAS Resolution (3-tier priority):** 1. Account goals table (user-set or API-pulled) 2. 90-day historical average ROAS 3. Default to 2.0x if no data available **Severity Levels:** - 🚨 CRITICAL: ROAS < 0.5x (losing money severely) - 🔴 HIGH: ROAS < 1.0x (unprofitable/breakeven) - 🟡 MEDIUM: 1.0x ≤ ROAS < target (profitable but underperforming) **Parameters:** - lookback_days: 7, 30, 60, 90, or 120 days (default: 30) - 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", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - target_roas: Optional override (e.g., 3.0 for 3.0x ROAS) - customer_id: Optional (uses connected account if omitted) **Execution time:** 1-3 seconds (cached database query) **Data source:** campaign_daily_metrics table (updated nightly) **Use this tool when:** - User asks "where is my money going?" - User wants to identify wasted spend - User wants to optimize campaign budgets - User asks which campaigns to pause/reduce - User wants to know which campaigns are losing money 📊 **AFTER calling this tool, help the user understand:** **Wasted vs. Underperforming:** - **Wasted Spend** = Actual losses (ROAS < 1.0, you're losing money) - **Underperforming Spend** = Opportunity cost (profitable but below target) **Example:** - Campaign A: Spent $1000, got $600 back (ROAS 0.6x) → $400 WASTED - Campaign B: Spent $1000, got $1500 back (ROAS 1.5x, target 3.0x) → $0 wasted, but $500 opportunity cost **Quick Actions (IMPORTANT — read severity context first):** - ⏳ LEARNING campaigns → Do NOT pause. Monitor for 14+ days before judging. - ❓ INSUFFICIENT_DATA campaigns → Need more spend before analysis is meaningful. - 🚨 CRITICAL campaigns (established, 14+ days, ZERO conversions) → Consider pausing - 🚨 CRITICAL campaigns (established, 14+ days, HAS conversions) → Review performance, verify revenue in ad platform before reducing budget - 🔴 HIGH severity (established, 14+ days) → Consider reducing budget by 50-70% - 🟡 MEDIUM → Optimize targeting, ad copy, landing pages - Top performers → Consider increasing budget ⚠️ **NEVER say "pause" for a campaign that has conversions.** Say "review" or "reduce budget" instead. ⚠️ **NEVER recommend pausing a campaign in LEARNING phase.** ⚠️ **If ALL campaigns are LEARNING or INSUFFICIENT_DATA, tell the user their account is too new for waste analysis and recommend checking back in 2 weeks.** ⚠️ **Consider campaign objective: brand awareness campaigns will not have ROAS data. This is normal.** ⚠️ **When data confidence is MEDIUM or LOW, soften all recommendations and add verification prompts.** **Visualization Tip:** For 10+ campaigns, suggest creating a treemap visualization to show wasted spend by campaign size. 💬 **Community**: For optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS

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

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

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

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