optimize_meta_budget

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

User asks about Meta/Facebook/Instagram budget optimization, reallocating ad spend, maximizing conversions with their budget, or wants data-driven budget recommendations. This tool uses linear programming (scipy.optimize) to find the optimal budget allocation across Meta Ads campaigns or ad sets to maximize conversions while respecting constraints. Returns: - Optimal budget allocation for each campaign/ad set - Expected conversion lift from reallocation - Campaigns to scale up (high ROAS performers) - Campaigns to reduce (below target ROAS) - Campaigns to consider pausing (ROAS < 1.0) - Actionable recommendations - CBO (Campaign Budget Optimization) notes When to use this tool: - "How should I allocate my Meta budget?" - "Optimize my Facebook ad spend for conversions" - "Which Instagram campaigns should I increase budget?" - "Reallocate my $5000 Meta budget" - "Maximize conversions with my current spend" - "What's the optimal budget split across campaigns?" Parameters: - total_budget: Total daily budget to allocate (required, e.g., 5000.00) - lookback_days: 7, 14, 30 (default), 60, or 90 days for analysis - 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 (default: from account goals or 2.0x) - max_change_percentage: Max budget change per item (default: 0.5 = 50%) - min_daily_budget: Minimum budget per item (default: 5.00) - optimization_level: 'campaign' (default) or 'ad_set' - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query + optimization) Data source: campaign_daily_metrics + ad_group_daily_metrics tables Key concepts: - Linear Programming: Mathematical optimization to maximize objective (conversions) subject to constraints - Efficiency Score: Conversions per dollar spent - used to prioritize allocation - Max Change Constraint: Prevents dramatic shifts (e.g., ±50% max from current) - Target ROAS: 3-tier resolution: account_goals - 90-day historical - default 2.0x Meta-specific considerations: - CBO campaigns: Budget set at campaign level, Meta distributes to ad sets - ABO campaigns: Budget set at ad set level, more granular control - Learning Phase: New campaigns need 50+ conversions before optimization

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

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

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