API Reference › Monitoring & Reporting › create_monitor

create_monitor

Monitoring & Reporting Write

Create a monitoring alert for your campaigns

Endpoint

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

Headers

Description

Create a monitoring alert for your campaigns. Checked daily. **Supported metrics:** roas, ctr, cpc, cpa, cpm, cpv, spend, conversions, impressions, clicks, cost_per_lead, conversion_rate, budget_utilization, video_views, engagement_rate **Operators:** less_than, greater_than, less_than_or_equal, greater_than_or_equal, changes_by **Advanced features:** - **Multiple conditions with AND/OR:** Use `conditions` array with `conditions_logic: "AND"` or `"OR"` - **Consecutive days:** Add `consecutive_days: 3` to only trigger after 3 days in a row - **Relative thresholds:** Set `threshold_type: "relative"` with `threshold_multiplier: 1.5` to mean "50% above average" - **% change detection:** Use `operator: "changes_by"` with `direction: "decrease"` and `threshold: 30` for "dropped 30%" - **Campaign targeting:** Use `campaign_ids` to monitor specific campaigns only - **Auto-actions (coming soon):** `auto_action: "pause_campaign"` or `"increase_budget"` with `auto_action_value: 20` **Examples:** 1. Simple: "Alert me if ROAS drops below 2" → metric: "roas", operator: "less_than", threshold: 2.0 2. Consecutive days: "Alert if CPA exceeds $50 for 3 days straight" → metric: "cpa", operator: "greater_than", threshold: 50, consecutive_days: 3 3. Compound AND: "Alert if CTR < 0.8% AND spend > $200" → conditions: [ {metric: "ctr", operator: "less_than", threshold: 0.8}, {metric: "spend", operator: "greater_than", threshold: 200} ], conditions_logic: "AND" 4. Relative: "Alert if CPA goes 50% above my 30-day average" → metric: "cpa", operator: "greater_than", threshold_type: "relative", threshold_multiplier: 1.5, threshold_timeframe: "last_30d" 5. % drop: "Notify me if cost per lead drops 30% in a day" → metric: "cost_per_lead", operator: "changes_by", threshold: 30, direction: "decrease", timeframe: "vs_previous_day" **IMPORTANT:** - If user doesn't specify an email for alerts, ASK them. Do not guess. - If user doesn't specify platforms, default to all their connected platforms. - If user doesn't specify campaigns, default to all campaigns. - Do not assume timeframe — ask if unclear. - Do not assume threshold values — ask if the user doesn't specify a number. - ROAS monitors are skipped on traffic/awareness/engagement campaigns automatically. - CPA monitors are skipped on campaigns with zero conversions automatically.

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
namestring requiredName for this alert (e.g., 'High CPA Auto-Pause', 'ROAS Scaling Rule')
monitor_typestring optionalType: 'performance_drop', 'budget_pace', 'anomaly_detection', 'spend_threshold', 'conversion_tracking' default: "performance_drop"
conditionsarray optionalList of conditions. Multiple conditions are evaluated with AND logic by default. For OR logic, set conditions_logic='OR'. If not provided, use the single-condition fields (metric, operator, threshold) below.
conditions_logicstring optionalHow multiple conditions combine: 'AND' (all must be true) or 'OR' (any must be true). Default: 'AND'. default: "AND"
metricstring optionalSingle condition metric (shorthand). Use 'conditions' array for multiple conditions.
operatorstring optionalSingle condition operator (shorthand).
thresholdnumber optionalSingle condition threshold (shorthand).
timeframestring optionalSingle condition timeframe (shorthand).
consecutive_daysinteger optionalSingle condition consecutive days (shorthand).
platformsarray optionalPlatforms to monitor: ['google_ads'], ['meta_ads'], ['google_ads', 'meta_ads'], etc. Default: all connected platforms.
campaign_idsarray optionalSpecific campaign IDs to monitor. Default: all campaigns. Get IDs from list_campaigns/list_meta_campaigns tools.
scope_levelstring optionalWhat level to monitor: 'campaign' (default), 'ad_set' (ad group level), or 'ad' (individual ad/creative level). default: "campaign"
alert_methodstring optionalHow to notify: 'email', 'slack', 'webhook'. Default: email. default: "email"
alert_destinationstring optionalWhere to send alerts: email address, Slack webhook URL, etc. If not provided, uses the user's account email.
auto_actionstring optionalAutomatic action when triggered: 'pause_campaign', 'increase_budget', 'decrease_budget', 'notify_only'. Default: notify_only (no automatic changes).
auto_action_valuenumber optionalValue for auto-action: percentage for budget changes (e.g., 20 for +20%), ignored for pause/notify.
check_frequencystring optionalHow often to check: 'daily' — checks once per day using data through yesterday. This is the only available frequency currently. default: "daily"

Example request

{
  "arguments": {
    "name": "string",
    "monitor_type": "performance_drop",
    "conditions": [
      {
        "metric": "string",
        "operator": "string",
        "threshold": 1.0,
        "timeframe": "string",
        "consecutive_days": 1,
        "threshold_type": "string",
        "threshold_multiplier": 1.0,
        "threshold_timeframe": "string",
        "direction": "string"
      }
    ],
    "conditions_logic": "AND",
    "metric": "string",
    "operator": "string",
    "threshold": 1.0
  }
}

Example responses

200 — Success

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

400 — Tool-level error (bad arguments / multi-account selection)

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

402 — Quota exhausted

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

Try it live

Interactive: Swagger UI

Machine-readable: OpenAPI 3.1 spec · llms-full.txt

More tools: Monitoring & Reporting · All tools

Adspirer REST API — get an API key at adspirer.ai/keys · adspirer.ai