explain_meta_anomaly

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

User asks why Meta/Facebook/Instagram performance dropped or changed, what happened to their ROAS/CTR/CPM, or wants to understand why a metric changed during a specific period. This tool analyzes why a specific metric changed during a specified period by comparing it to historical baselines and identifying contributing factors. It detects Meta-specific causes including creative fatigue, audience saturation, placement mix shifts, and auction competition. Returns: - Current metric value vs historical averages (30/60/90-day) - Deviation percentages from baselines - Contributing factors ranked by estimated impact - Factor explanations with details - Similar historical periods with comparable changes - Assessment of anomaly severity (CRITICAL/WARNING/MINOR/NORMAL) - Specific recommendations based on detected factors - Quick actionable items When to use this tool: - "Why did my Meta ROAS drop?" - "What happened to my Facebook CTR this week?" - "Why is my Instagram CPM so high?" - "Explain my Meta performance change" - "My conversions dropped last week - why?" - "Why did my frequency spike?" - "What caused my ROAS to decline 40%?" - "Diagnose my Meta performance problem" Parameters: - metric: Required - 'roas', 'ctr', 'cpc', 'cpm', 'conversions', 'conversion_rate', 'frequency', or 'reach' - period_start: Required - Start date (YYYY-MM-DD format) - period_end: Required - End date (YYYY-MM-DD format, must be ≤30 days from start) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 3-8 seconds (statistical analysis across multiple periods) Data source: campaign_daily_metrics + meta_placement_daily_metrics + meta_ad_creative_metrics tables Contributing Factors Detected: - CPM Change: Auction competition fluctuations (holidays, competitor activity) - CTR Change: Creative performance (fatigue, messaging, targeting) - Conversion Rate Change: Landing page or offer issues - Frequency Change: Audience saturation (Meta-specific) - Creative Fatigue: High frequency + declining CTR (Meta-specific) - Placement Mix Change: Shift in placement distribution (Meta-specific) - Campaign Changes: Paused/new campaigns affecting overall performance Severity Levels: - 🔴 CRITICAL (≥40% deviation): Immediate action required - 🟡 WARNING (25-40% deviation): Review recommended - 🟢 MINOR (15-25% deviation): Monitor situation - ✅ NORMAL (<15% deviation): Within normal variation Similar Historical Periods: Finds past periods with comparable deviations to provide context (e.g., "similar drop occurred during Black Friday 2024") Best for: - Diagnosing sudden performance drops - Understanding seasonal patterns - Identifying actionable causes vs. external factors - Prioritizing optimization efforts

{
  "arguments": {
    "metric": "ctr",
    "period_start": "string",
    "period_end": "string",
    "ad_account_id": "string",
    "raw_data": false
  }
}

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

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

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