API Reference › Meta Ads › get_meta_audience_insights

get_meta_audience_insights

Meta Ads Read

User asks about audience demographics, which placements perform best, device breakdown, or targeting optimization for Meta ads

Endpoint

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

Headers

Description

User asks about audience demographics, which placements perform best, device breakdown, or targeting optimization for Meta ads. This tool provides audience and placement analysis for Meta campaigns. Returns: - Age group performance (18-24, 25-34, 35-44, 45-54, 55-64, 65+) - Gender performance breakdown - Placement breakdown (Facebook Feed, Instagram Feed, Stories, Reels, Messenger) - Device breakdown (Mobile, Desktop, Tablet) - Best performing audience segments - Targeting recommendations When to use this tool: - "What age group performs best for my Meta ads?" - "Should I target men or women?" - "Which placements should I use?" - "Do my Instagram Stories ads perform well?" - "Mobile vs desktop performance on Facebook?" Parameters: - lookback_days: 7, 14, 30 (default), 60, or 90 days - 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', 'placement', 'device', or 'all' (default) - ad_account_id: Required for multi-account users. Get from list_connected_accounts Execution time: 1-3 seconds (cached database query) Data source: Cached database (aggregate metrics only - detailed breakdown requires live API) Common insights: - Meta audiences typically skew mobile (70-85%) - Instagram tends to perform better with 18-34 age groups - Facebook Feed often has highest reach but Stories may have better engagement - Reels placement growing rapidly in 2024-2025

Request body

All tool arguments are wrapped in an arguments object.

FieldTypeDescription
start_datestring optionalStart date (YYYY-MM-DD). If provided with end_date, overrides lookback_days for custom date range queries.
end_datestring optionalEnd date (YYYY-MM-DD). If provided with start_date, overrides lookback_days for custom date range queries.
date_rangestring optionalDate range preset: 'last_7_days', 'last_14_days', 'last_30_days', 'last_60_days', 'last_90_days'. Overrides lookback_days. Ignored if start_date/end_date are provided.
raw_databoolean optionalIf true, return ONLY raw metrics as a JSON code block (spend, clicks, impressions, conversions, CPA, CPC, CTR, CVR, ROAS by campaign/ad/date). Strips severity labels, suggested bids/budgets, industry benchmarks, and optimization recommendations. Use when you run your own attribution model or want to minimize token usage. default: false
lookback_daysinteger optionalNumber of days to analyze (7, 14, 30, 60, or 90 days). Default is 30 days. default: 30
breakdown_typestring optionalType of breakdown: 'age', 'gender', 'placement', 'device', or 'all' (default). Use 'all' for comprehensive audience analysis. default: "all"
ad_account_idstring optionalMeta Ad Account ID. Required for multi-account users. Get from list_connected_accounts.

Example request

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

Example responses

200 — Success

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

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": "get_meta_audience_insights"
}

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": "get_meta_audience_insights",
  "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: Meta Ads · All tools

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