Explain Meta Anomaly

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

POST

api

tools

explain_meta_anomaly

execute

Explain Meta Anomaly

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/explain_meta_anomaly/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_account_id": "string",
    "metric": "ctr",
    "period_end": "string",
    "period_start": "string",
    "raw_data": false
  }
}
'

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

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 Meta anomaly explanation analysis

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

Get Meta Ad CreativesUser wants to see their Meta ad creatives, ad copy, media URLs, or creative performance. Returns ad-level data including full creative content and media URLs alongside performance metrics. When to use this tool: - "Show me my Meta ad creatives" - "What ads are running and how are they performing?" - "Show me the headlines and images for my ads" - "Which ad creatives are performing best?" - "What's the creative content for campaign X?" - "Show me ad performance with creative details" - "Get me the image URLs for my ads" - "Export my ad copy" - "What images and videos are my ads using?" Returns per ad — ALWAYS display ALL of these fields when present: - Ad copy: headline, primary_text, description, call_to_action_type - Media URLs: image_url (direct CDN link to ad image), thumbnail_url, video_url (playable video source), video_id - Landing page: landing_page_url - Carousel cards: carousel_cards array with per-card image_url, headline, description, landing_page_url - Performance: spend, impressions, clicks, CTR, CPC, reach, frequency - Video engagement: 25%, 50%, 75%, 100% watched (for video ads) - Creative metadata: creative_type (image/video/carousel/dynamic_creative), first_seen_date IMPORTANT: Always show the full image_url, thumbnail_url, video_url, and landing_page_url values — these are direct CDN links users need to download/export their creative media. Do not summarize or omit URLs. Parameters: - lookback_days: Number of days to analyze (7, 14, 30, 60, 90). Default: 30 - campaign_id: Optional filter to specific campaign - ad_set_id: Optional filter to specific ad set - ad_account_id: Required for multi-account users. Get from list_connected_accounts - start_date/end_date: Optional custom date range (overrides lookback_days) - limit: Max ads per page (default 20, max 50). Use for pagination. - offset: Number of ads to skip (default 0). Use with limit to page through results. Pagination: Results are paginated. Response includes total_ads count and has_more flag. To get next page, increase offset by limit. Execution time: 1-3 seconds Data source: Cached database (collected daily)

Explain Meta Anomaly

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/explain_meta_anomaly/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "ad_account_id": "string",
    "metric": "ctr",
    "period_end": "string",
    "period_start": "string",
    "raw_data": false
  }
}
'

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