meta_ads_get_insights

Get Meta Ads Insights

Meta

Description

Retrieve performance metrics from Meta Ads with date presets/custom ranges, time grouping, entity-level aggregation, dimensional breakdowns, and filtering. Always fetches fresh data. Provide date_preset or time_range. For standard full-funnel analysis, prefer meta_ads_get_performance_report; use this for custom fields, hourly/creative-asset breakdowns, video metrics, or the \

Read-onlyIdempotent

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meta_ads_get_insights",
    "arguments": {
      "account_id": "act_123456789",
      "date_preset": "last_7d",
      "action_attribution_windows": [
        "7d_click"
      ],
      "reason": "Isolate 7-day click attribution conversions for accurate ROAS measurement"
    }
  }
}

Parameters

NameTypeRequiredDescription
account_id string Required Meta ad account IDminLength: 1
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (11)
NameTypeRequiredDescription
date_preset string Optional Predefined date range: today, yesterday, last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, this_month, last_month, this_quarter, last_quarter, this_year, last_year, lifetime, maximum
today yesterday this_week_mon_today this_week_sun_today last_week_mon_sun last_week_sun_sat this_month last_month this_quarter last_quarter this_year last_year last_3d last_7d last_14d last_28d last_30d last_90d lifetime maximum
time_range object Optional Custom date range {since, until} in YYYY-MM-DD
time_increment object Optional Time grouping: 1=daily, 7=weekly, or "monthly"
level string Optional Aggregation level: account, campaign, adset, ad
account campaign adset ad
fields array Optional Metrics to retrieve (defaults to standard set)
breakdowns array Optional Dimensions to segment data by. Pass multiple values in a single call to get cross-tabulated rows (e.g. ["age","gender"] → one row per "35-44 / female" segment). Do NOT make separate calls for each dimension. Available: age, gender, country, region, dma, device_platform, publisher_platform, platform_position, impression_device, frequency_value, place_page_id, product_id, ad_format_asset, body_asset, call_to_action_asset, description_asset, image_asset, link_url_asset, title_asset, video_asset, user_segment_key. Note: `frequency_value` is compatible only with `fields: ["reach"]` and cannot be combined with other breakdowns or with action_breakdowns; the tool rejects incompatible calls. Note: `user_segment_key` is the Advantage+ Shopping Campaigns "Audience Segments" breakdown. Returned values: prospecting, engaged, existing, unknown (lowercase). Cross-tabulation with demographic breakdowns like age is rejected by Meta's API — combine with country if needed; use separate calls for demographic splits.
action_breakdowns array Optional Action breakdown dimensions: action_type, action_target_id, action_destination, action_reaction, action_video_sound, action_video_type, action_carousel_card_id, action_carousel_card_name
filtering array Optional Filters as [{field, operator, value}]
action_attribution_windows array Optional Attribution windows for action/conversion metrics. Controls which click/view windows are reported. Common: ["7d_click"] for 7-day click only. Default (when omitted): ["7d_click","1d_view"]. Available: 1d_click, 7d_click, 28d_click, 1d_view, 7d_view, 28d_view, 1d_ev, default
limit integer Optional Maximum number of rows per page (default: 100, max: 500)min: 1, max: 500
cursor string Optional Pagination cursor from previous responseminLength: 1

Examples

7-day click only conversions

{
  "account_id": "act_123456789",
  "date_preset": "last_7d",
  "action_attribution_windows": [
    "7d_click"
  ],
  "reason": "Isolate 7-day click attribution conversions for accurate ROAS measurement"
}

hopkin meta insights get --account act_123456789 --date-preset last_7d --action-attribution-windows 7d_click

Age and gender breakdown

{
  "account_id": "act_123",
  "date_preset": "last_7d",
  "breakdowns": [
    "age",
    "gender"
  ],
  "reason": "Demographic breakdown not available in performance report"
}

hopkin meta insights get --account act_123 --date-preset last_7d --breakdowns age,gender

Publisher platform breakdown

{
  "account_id": "act_123",
  "date_preset": "last_7d",
  "level": "adset",
  "breakdowns": [
    "publisher_platform",
    "platform_position"
  ],
  "reason": "Placement breakdown by publisher and position"
}

hopkin meta insights get --account act_123 --date-preset last_7d --level adset --breakdowns publisher_platform,platform_position

Video asset metrics

{
  "account_id": "act_123",
  "date_preset": "last_7d",
  "level": "ad",
  "fields": [
    "video_p25_watched_actions",
    "video_p50_watched_actions",
    "video_p75_watched_actions",
    "video_p100_watched_actions",
    "video_avg_time_watched_actions"
  ],
  "reason": "Video completion funnel for creative analysis"
}

hopkin meta insights get --account act_123 --date-preset last_7d --level ad --fields video_p25_watched_actions,video_p50_watched_actions,video_p75_watched_actions,video_p100_watched_actions,video_avg_time_watched_actions

Frequency-bucket reach

{
  "account_id": "act_123",
  "date_preset": "last_30d",
  "breakdowns": [
    "frequency_value"
  ],
  "fields": [
    "reach"
  ],
  "reason": "Distribution of unique users by exposure frequency (1×, 2×, 3+); frequency_value is reach-only per Meta"
}

hopkin meta insights get --account act_123 --date-preset last_30d --breakdowns frequency_value --fields reach

ASC audience-segment split (prospecting vs engaged vs existing vs unknown)

{
  "account_id": "act_123",
  "date_preset": "last_7d",
  "level": "campaign",
  "breakdowns": [
    "user_segment_key"
  ],
  "filtering": [
    {
      "field": "campaign.objective",
      "operator": "EQUAL",
      "value": "OUTCOME_SALES"
    }
  ],
  "reason": "Weekly WoW report for Advantage+ Shopping Campaign — split spend/conversions by acquisition (prospecting) vs retargeting (engaged) vs existing customers"
}

hopkin meta insights get --account act_123 --date-preset last_7d --level campaign --breakdowns user_segment_key --filtering [object Object]