optimize_budget_allocation

POST https://api.adspirer.ai/api/v1/tools/optimize_budget_allocation/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 Optimize budget allocation across campaigns using linear programming to maximize conversions. ⚠️ IMPORTANT: This tool retrieves READ-ONLY optimization recommendations. Safe to call multiple times. Does NOT automatically change budgets. 🎯 **What This Tool Does (Performance Agent - Phase 1):** - Uses linear programming to optimize budget distribution - Maximizes total conversions while respecting constraints - Provides current vs optimized allocation comparison - Categorizes campaigns into actions: PAUSE/SCALE/REDUCE/MAINTAIN - Shows expected conversion lift from optimization - Generates specific recommendations with budget amounts **Returns detailed optimization plan:** - Current allocation (what you have now) - Optimized allocation (what you should have) - Expected conversion lift (absolute and percentage) - Campaign-by-campaign actions with reasoning - Budget change amounts and percentages - Specific implementation recommendations **Optimization Algorithm:** Uses scipy linear programming with constraints: 1. Sum of budgets = total_budget (you don't overspend) 2. Only campaigns with ROAS >= target get significant budget 3. Min budget per campaign >= min_daily_budget (or $0 to pause) 4. Max change per campaign <= ±max_change_percentage (avoid drastic shifts) **Target ROAS Resolution (3-tier priority):** 1. User override (if target_roas parameter provided) 2. Account goals table (user-set or API-pulled) 3. 90-day historical average ROAS 4. Default to 1.0x (breakeven) if no data **Configuration Parameters:** - **total_budget**: Total monthly budget to allocate (REQUIRED) - **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. - **target_roas**: Optional override (e.g., 3.0 for 3.0x) - **max_change_percentage**: 0.0-1.0 (default: 0.5 = ±50%) * 0.3 = Conservative (±30% change, minimal disruption) * 0.5 = Balanced (±50% change, standard optimization) * 0.7 = Aggressive (±70% change, fast scaling) - **min_daily_budget**: Minimum $ per campaign (default: $5.00, or $0.00 to allow pausing) - **customer_id**: Optional (uses connected account if omitted) **Execution time:** 1-5 seconds (depends on campaign count) **Data source:** campaign_daily_metrics table (updated nightly) **Use this tool when:** - User wants to optimize budget allocation - User asks "how should I allocate my budget?" - User wants to maximize conversions with current spend - User wants data-driven budget recommendations - After running wasted spend analysis (natural next step) 📊 **AFTER calling this tool, help the user understand:** **Campaign Actions:** - **PAUSE**: Campaigns below target ROAS, losing money (ROAS < target) - **SCALE**: High performers, increase budget by X% (top conversion rates) - **REDUCE**: Underperformers, decrease budget by X% (low efficiency) - **MAINTAIN**: Steady performers, keep current budget (±5% change) **Expected Impact:** - Current conversions: What you get now - Optimized conversions: What you could get - Conversion lift: Additional conversions (+X%) **Example Interpretation:** "Implementing this optimization will increase your conversions by 45 (+18.8%) without spending more money. You should scale 'Brand - Exact' campaign by $2,250/month and pause 'Display - Broad' to free up $3,000/month." **Implementation Steps:** 1. Review recommended changes carefully 2. Start with campaigns marked CRITICAL (pause/scale first) 3. Apply changes gradually if user is risk-averse 4. Monitor performance for 7-14 days after changes 5. Re-run optimization monthly for continuous improvement **Important Notes:** - This is a RECOMMENDATION tool, not automated budget application - User must review and apply changes manually in Google Ads - Avoid large changes (>50%) for campaigns in learning phase (<7 days) - Consider seasonality when interpreting results - Re-optimize every 30 days as performance changes **Visualization Tip:** For 5+ campaigns, suggest creating a grouped bar chart showing current vs optimized budgets side-by-side. **Best Practices:** - Start conservative (max_change_percentage=0.3) for first optimization - Increase aggressiveness (0.5-0.7) as you gain confidence - Use longer lookback_days (60-90) during seasonal changes - Set realistic target_roas (start with 1.0x breakeven, increase gradually) 💬 **Community**: For optimization discussions, visit our Discord: https://discord.gg/dH3Qt4YS

{
  "arguments": {
    "total_budget": 1.0,
    "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 optimize_budget_allocation)",
    "quota": {
      "used": 42,
      "limit": 150,
      "tier": "plus",
      "period_end": "2026-05-01"
    }
  },
  "tool": "optimize_budget_allocation"
}

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

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