Create Monitor

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:

Simple: “Alert me if ROAS drops below 2” → metric: “roas”, operator: “less_than”, threshold: 2.0
Consecutive days: “Alert if CPA exceeds $50 for 3 days straight” → metric: “cpa”, operator: “greater_than”, threshold: 50, consecutive_days: 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”
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”
% 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.

POST

/

api

/

v1

/

tools

/

create_monitor

/

execute

Create Monitor

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_monitor/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "conditions": [
      {
        "consecutive_days": 1,
        "direction": "string",
        "metric": "string",
        "operator": "string",
        "threshold": 1,
        "threshold_multiplier": 1,
        "threshold_timeframe": "string",
        "threshold_type": "string",
        "timeframe": "string"
      }
    ],
    "conditions_logic": "AND",
    "metric": "string",
    "monitor_type": "performance_drop",
    "name": "string",
    "operator": "string",
    "threshold": 1
  }
}
'

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

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 for creating a monitoring alert.

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

Delete MonitorDelete a monitoring alert by its task ID. **When to use:** - "Delete my ROAS monitor" - "Remove this alert" - "Stop monitoring my campaign" Get the task_id from `list_monitors` first. Accepts `task_id`, `alert_id`, or `monitor_id` — all treated the same.

Create Monitor

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/create_monitor/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "conditions": [
      {
        "consecutive_days": 1,
        "direction": "string",
        "metric": "string",
        "operator": "string",
        "threshold": 1,
        "threshold_multiplier": 1,
        "threshold_timeframe": "string",
        "threshold_type": "string",
        "timeframe": "string"
      }
    ],
    "conditions_logic": "AND",
    "metric": "string",
    "monitor_type": "performance_drop",
    "name": "string",
    "operator": "string",
    "threshold": 1
  }
}
'

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