get_insights
Retrieve performance insights for Meta ads campaigns, ad sets, ads, or accounts, with metrics like impressions, clicks, and spend, plus breakdowns and time range filters.
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
Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset,
image_asset, link_url_asset, title_asset, video_asset, media_asset_url,
media_creator, media_destination_url, media_format, media_origin_url,
media_text_content, media_type, creative_relaxation_asset_type,
flexible_format_asset_type, gen_ai_asset_type
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.
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_attribution_windows | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |