create_monitor

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

Create a monitoring alert for the user's ad campaigns. Checked daily. **Shape (aligned with the web UI — both surfaces produce identical alerts):** An alert is exactly ONE condition: - one metric - one operator (greater_than for ceilings, less_than for floors) - one threshold value - optional `consecutive_days` (1–14) to require the condition hold for N days in a row Compound conditions (AND/OR), relative thresholds, the `changes_by` operator, and auto-actions are NOT supported on this tool. If the user asks for something complex, create multiple separate alerts via multiple tool calls instead. **Supported metrics:** - Cost: `cpa`, `cpc`, `cost_per_lead`, `spend` - Performance: `roas`, `ctr`, `conversion_rate` - Volume: `conversions`, `clicks`, `impressions` - Pacing: `budget_utilization` **Operators:** `greater_than`, `less_than` only. **Examples:** 1. "Alert me if ROAS drops below 2" → metric: "roas", operator: "less_than", threshold: 2.0 2. "Alert if CPA exceeds $50 for 3 days straight" → metric: "cpa", operator: "greater_than", threshold: 50, consecutive_days: 3 3. "Alert me when impressions drop below 10 in a day" → metric: "impressions", operator: "less_than", threshold: 10 4. "Alert if CTR collapses below 1%" → metric: "ctr", operator: "less_than", threshold: 1.0 5. "Tell me if budget utilization goes above 110%" → metric: "budget_utilization", operator: "greater_than", threshold: 110 **Per-user caps:** Free tier = 1 active alert. All paid tiers (Plus / Pro / Max / Enterprise) = 5 active alerts. Manually-created and recommender-created alerts share the same pool. **Guidance:** - If the user doesn't specify a platform, default to all connected platforms. - If they don't specify a threshold, ASK — don't guess. - If they don't provide an email for alerts, leave `alert_destination` blank and the backend will resolve it to their account email. - ROAS alerts are skipped automatically on traffic / awareness / engagement campaigns where ROAS isn't meaningful. - CPA alerts are skipped automatically on campaigns with zero conversions. - If the user asks for a complex pattern (e.g., "clicks > 100 AND conversions = 0"), explain that this tool only supports single-condition alerts and offer to create them as TWO separate alerts. The shared capability spec lives at `/api/v1/monitoring-alerts/capabilities` on the backend if you need to verify supported metrics or limits.

{
  "arguments": {
    "metric": "string",
    "operator": "string",
    "threshold": 1.0,
    "consecutive_days": 1,
    "name": "string",
    "platforms": [
      "string"
    ],
    "campaign_ids": [
      "string"
    ],
    "alert_destination": "string"
  }
}

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

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

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