Optimize Budget Allocation

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:

Sum of budgets = total_budget (you don’t overspend)
Only campaigns with ROAS >= target get significant budget
Min budget per campaign >= min_daily_budget (or $0 to pause)
Max change per campaign <= ±max_change_percentage (avoid drastic shifts)

Target ROAS Resolution (3-tier priority):

User override (if target_roas parameter provided)
Account goals table (user-set or API-pulled)
90-day historical average ROAS
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:

Review recommended changes carefully
Start with campaigns marked CRITICAL (pause/scale first)
Apply changes gradually if user is risk-averse
Monitor performance for 7-14 days after changes
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

POST

/

api

/

v1

/

tools

/

optimize_budget_allocation

/

execute

Optimize Budget Allocation

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/optimize_budget_allocation/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "date_range": "string",
    "end_date": "string",
    "lookback_days": 30,
    "raw_data": false,
    "start_date": "string",
    "target_roas": 1,
    "total_budget": 1
  }
}
'

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

Authorizations

Authorization

string

header

required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key

string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments

object

required

Input schema for budget allocation optimization

Show child attributes

Response

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data

object

required

Show child attributes

success

boolean

required

tool

string

required

Echoed tool_name from the request URL.

Last modified on April 23, 2026

Pause AdPause an ad to stop it from showing. This is REVERSIBLE using resume_ad. **Parameters:** - ad_id: The ad ID to pause (REQUIRED) - ad_group_id: The ad group ID (REQUIRED) - customer_id: Optional **Execution time:** 1-2 seconds **When to use:** - User says "pause this ad", "stop this ad" - User wants to A/B test by pausing one ad - Ad is underperforming and needs a break - Making changes before re-enabling **Example:** User: "Pause my underperforming ad" Agent: 1. Uses get_campaign_structure to find ad_id and ad_group_id 2. Uses pause_ad to stop the ad

Optimize Budget Allocation

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/optimize_budget_allocation/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "date_range": "string",
    "end_date": "string",
    "lookback_days": 30,
    "raw_data": false,
    "start_date": "string",
    "target_roas": 1,
    "total_budget": 1
  }
}
'

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