`meta_ads_get_insights`

Get Meta Ads Insights

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, or video metrics.

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

hopkin meta insights get

Flag	Type	Required	Description
`--account`	`string`	Required	Meta ad account ID
`--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
`--time-range`	`object`	Optional	Custom date range {since, until} in YYYY-MM-DD
`--time-increment`	`unknown`	Optional	Time grouping: 1=daily, 7=weekly, or "monthly"
`--level`	`string`	Optional	Aggregation level: 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
`--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

{
  "mcpServers": {
    "meta-ads": {
      "url": "https://mcp.hopkin.ai/meta-ads/mcp",
      "transport": "sse"
    }
  }
}

7-day click only conversions
Age and gender breakdown
Publisher platform breakdown
Video asset metrics

Parameters

Name	Type	Required	Description
`account_id`	`string`	Required	Meta ad account IDminLength: 1
`reason`	`string`	Required	Why this tool call is neededminLength: 1, maxLength: 500

Optional parameters (9)

Name	Type	Required	Description
`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`	`unknown`	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
`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

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