analyze_meta_audiences

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

User asks about Meta/Facebook/Instagram audience performance by demographics, age group or gender targeting optimization, audience saturation, or which demographic segments to target or exclude. This tool provides deep analysis of audience segment performance and detects audience saturation to optimize demographic targeting for Meta Ads. Returns: - Age group performance breakdown (18-24, 25-34, 35-44, 45-54, 55-64, 65+) - Gender performance breakdown (male, female, unknown) - Age + Gender combination analysis - Segments categorized as SCALE/MAINTAIN/REDUCE/EXCLUDE based on ROAS - Audience saturation score (0-100) with contributing factors - Best performing segments to scale - Underperforming segments to reduce/exclude - Targeting optimization recommendations - Quick actionable items When to use this tool: - "Which age groups perform best for my Meta ads?" - "Should I target men or women on Facebook?" - "Is my Meta audience saturated?" - "Which demographics should I exclude?" - "Analyze my Instagram audience performance" - "Best demographic targeting for my Facebook campaigns" - "Age and gender breakdown for my Meta ads" - "Are my lookalike audiences exhausted?" - "Which audience segments are wasting money?" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - date_range: preset alternative to lookback_days / start_date / end_date. One of: 'last_7_days', 'last_14_days', 'last_30_days', 'last_60_days', 'last_90_days'. (Both 'last_30_days' and 'last_30d' / 'last_month' aliases accepted.) - start_date: Optional start date (YYYY-MM-DD). Overrides lookback_days when used with end_date. - end_date: Optional end date (YYYY-MM-DD). Overrides lookback_days when used with start_date. ⚠️ DATE CLARIFICATION: If the user's date request is vague or ambiguous (e.g., "March to June" without a year, "last quarter", "recently", "a few months ago"), ask the user to specify exact dates before calling this tool. Do not assume or guess dates. - breakdown_type: 'age', 'gender', 'age_gender', or 'all' (default) - include_saturation: Include saturation analysis (default: True) - target_roas: Optional override (default: from account goals or 2.0x) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 2-5 seconds (cached database query with analysis) Data source: meta_audience_daily_metrics table (demographic-level daily metrics) ROAS Thresholds for Segment Recommendations: - 🚀 SCALE (ROAS ≥ 1.5x target): Increase budget to this segment - ➖ MAINTAIN (ROAS 0.75x-1.5x target): Keep current allocation - ⚠️ REDUCE (ROAS 0.5x-0.75x target): Decrease budget - 🔴 EXCLUDE (ROAS < 0.5x target): Remove from targeting Saturation Score Factors (weighted): - Frequency Score (35%): How often users see ads (>3 indicates fatigue) - CTR Decline Score (30%): Week-over-week CTR changes - CPA Increase Score (25%): Rising cost per acquisition - Reach Saturation Score (10%): Audience reach exhaustion Saturation Levels: - ✅ HEALTHY (<40): Audience is fresh, continue scaling - 🟡 AT_RISK (40-69): Monitor frequency, prepare new audiences - 🔴 SATURATED (≥70): Expand targeting or refresh creatives Common Insights: - Age 25-44 typically has highest ROAS for e-commerce - Gender targeting varies significantly by product category - High frequency (>4) combined with declining CTR indicates saturation - Lookalike audiences can exhaust within 4-8 weeks at high spend

{
  "arguments": {
    "start_date": "string",
    "end_date": "string",
    "date_range": "string",
    "raw_data": false,
    "lookback_days": 30,
    "breakdown_type": "all"
  }
}

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

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

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