get_insights
Fetch performance insights for Meta ads, ad sets, campaigns, or accounts, with customizable time ranges and breakdowns for metrics like impressions, clicks, spend, and conversions.
Instructions
Get performance insights for a campaign, ad set, ad or account.
Args:
object_id: ID of the campaign, ad set, ad or account. You can also use the alias parameters below.
account_id: Alias for object_id when querying account-level insights
campaign_id: Alias for object_id when querying campaign-level insights
adset_id: Alias for object_id when querying ad-set-level insights
ad_id: Alias for object_id when querying ad-level insights
access_token: Meta API access token (optional - will use cached token if not provided)
time_range: Either a preset time range string or a dictionary with "since" and "until" dates in YYYY-MM-DD format
Preset options: today, yesterday, this_month, last_month, this_quarter, maximum, data_maximum,
last_3d, last_7d, last_14d, last_28d, last_30d, last_90d, last_week_mon_sun,
last_week_sun_sat, last_quarter, last_year, this_week_mon_today, this_week_sun_today, this_year
Dictionary example: {"since":"2023-01-01","until":"2023-01-31"}
breakdown: Optional breakdown dimension. Valid values include:
Demographic: age, gender, country, region, dma
Platform/Device: device_platform, platform_position, publisher_platform, impression_device
NOTE: platform_position is a Meta-restricted breakdown — Meta requires it to be paired
with publisher_platform (otherwise "(#100) ... (action_type, platform_position) is invalid").
When you pass platform_position, this tool auto-adds publisher_platform, and the
action-typed fields (actions, action_values, conversions, cost_per_action_type) are
returned per placement, so you get leads/CPL/conversions broken down by placement.
Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset,
image_asset, link_url_asset, title_asset, video_asset, media_type,
creative_relaxation_asset_type, flexible_format_asset_type,
gen_ai_asset_type
NOTE: Asset breakdowns (image_asset, video_asset, etc.) only return data for ads
running with Dynamic Creative; for non-DCO ads, expect empty rows.
NOTE: media_type collides with the default action_breakdowns=[action_type], so
this tool auto-overrides action_breakdowns to [] when you pass media_type.
Action-typed metrics (actions, action_values, conversions) are still returned
but are no longer sliced by action_type alongside media_type.
media_asset_url, media_creator, media_destination_url, media_format,
media_origin_url, and media_text_content are NOT supported by Meta's Insights API
(Meta returns "(#100) Tried accessing nonexisting field"). Use the asset breakdowns
above instead.
Campaign/Ad Attributes: breakdown_ad_objective, breakdown_reporting_ad_id, app_id, product_id
Conversion Tracking: coarse_conversion_value, conversion_destination, standard_event_content_type,
signal_source_bucket, is_conversion_id_modeled, fidelity_type, redownload
Time-based: hourly_stats_aggregated_by_advertiser_time_zone,
hourly_stats_aggregated_by_audience_time_zone, frequency_value
Extensions/Landing: ad_extension_domain, ad_extension_url, landing_destination,
mdsa_landing_destination
Attribution: sot_attribution_model_type, sot_attribution_window, sot_channel,
sot_event_type, sot_source
Mobile/SKAN: skan_campaign_id, skan_conversion_id, skan_version, postback_sequence_index
CRM/Business: crm_advertiser_l12_territory_ids, crm_advertiser_subvertical_id,
crm_advertiser_vertical_id, crm_ult_advertiser_id, user_persona_id, user_persona_name
Advanced: hsid, is_auto_advance, is_rendered_as_delayed_skip_ad, mmm, place_page_id,
marketing_messages_btn_name, impression_view_time_advertiser_hour_v2, comscore_market,
comscore_market_code
level: Level of aggregation (ad, adset, campaign, account)
limit: Maximum number of results to return per page (default: 25, Meta API allows much higher values)
after: Pagination cursor to get the next set of results. Use the 'after' cursor from previous response's paging.next field.
action_attribution_windows: Optional list of attribution windows (e.g., ["1d_click", "7d_click", "1d_view"]).
When specified, actions include additional fields for each window. The 'value' field always shows 7d_click.
action_breakdowns: Optional list of action_breakdowns to apply to action-typed metrics. Pass [] to disable
the default action_type slicing (required when combining action data with breakdowns that collide
with action_type, e.g. media_type — auto-applied for media_type when not set).
Meta supports values like action_type, action_target_id, action_destination, etc.
compact: When True, strips redundant action-type duplicates from the response
(omni_*, onsite_web_*, offsite_conversion.fb_pixel_*, etc.) to reduce
payload size by ~60%. The canonical action types (purchase, add_to_cart,
view_content, etc.) are always preserved. Default: False.
Note on response size: This tool always returns a fixed set of fields (impressions, clicks,
spend, cpc, cpm, ctr, reach, actions, action_values, etc.) and cannot filter to a subset.
For large result sets (50+ rows), the actions/action_values arrays can make responses very
large (1–2MB+). If you only need specific metrics like spend or impressions, consider using
bulk_get_insights with compact=true and the fields parameter:
bulk_get_insights(level="ad", account_ids=[...], compact=true, fields=["spend", "impressions"])
bulk_get_insights supports level="ad", "adset", "campaign", and "account".
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "get_insights"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ad_id | No | ||
| after | No | ||
| level | No | ad | |
| limit | No | ||
| compact | No | ||
| adset_id | No | ||
| breakdown | No | ||
| object_id | No | ||
| account_id | No | ||
| time_range | No | maximum | |
| campaign_id | No | ||
| access_token | No | ||
| action_breakdowns | No | ||
| action_attribution_windows | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |