Skip to main content
⚠️ 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 percampaign(default: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

​
OpenAPI

/api-reference/openapi.json post /api/v1/tools/optimize_budget_allocation/execute