Get Meta Ad Insights
meta_ads_get_ad_insightsRetrieve performance metrics like impressions, clicks, conversions for a specified Meta ad. Supports custom date ranges and breakdowns by age, gender, and platform.
Instructions
Retrieve detailed performance insights for a specific Meta ad.
Fetches performance metrics for an individual ad, such as impressions, clicks, conversions, video views, etc.
Args:
ad_id (string): Ad ID, e.g., '6123456789012'
fields (string[]): Metrics to retrieve. Common: ad_name, adset_name, campaign_name, impressions, clicks, spend, ctr, cpc, cpm, reach, frequency, actions, conversions, cost_per_action_type, inline_link_clicks, video_p25_watched_actions
date_preset (string): Relative time range preset (default: last_30d)
time_range (object): Custom range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}
level (string): Aggregation level, should be 'ad' (default: ad)
breakdowns (string[]): Segment by: age, gender, country, publisher_platform, impression_device, platform_position, device_platform, etc.
See full parameter list in inputSchema
Returns: Object with:
data (array): List of insight records with requested metrics
paging (object): Pagination cursors. Use meta_ads_fetch_pagination_url with paging.next to get more results
Pagination note: When response contains paging.next, use meta_ads_fetch_pagination_url to retrieve additional pages automatically.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Metrics and dimensions to retrieve. Common examples: impressions, reach, clicks, spend, ctr, cpc, cpm, cpp, frequency, actions, conversions, cost_per_action_type, date_start, date_stop | |
| date_preset | No | Predefined relative time range. Options: today, yesterday, this_month, last_month, this_quarter, 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. Default: last_30d. Ignored if time_range, time_ranges, since, or until is provided | last_30d |
| time_range | No | Specific time range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}. Overrides date_preset | |
| time_ranges | No | Array of time range objects for period comparison. Overrides time_range and date_preset | |
| time_increment | No | Time breakdown granularity: integer 1-90 (days per point), 'monthly', or 'all_days' (single summary). Default: all_days | all_days |
| level | No | Level of aggregation: account, campaign, adset, or ad | |
| action_attribution_windows | No | Attribution windows for actions. Examples: 1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, dda, default | |
| action_breakdowns | No | Segments the actions results. Examples: action_device, action_type, conversion_destination, action_destination. Default: [action_type] | |
| action_report_time | No | When actions are counted: impression (time of ad impression), conversion (time of conversion), mixed. Default: mixed | |
| breakdowns | No | Segment results by dimensions. Examples: age, gender, country, region, dma, impression_device, publisher_platform, platform_position, device_platform | |
| default_summary | No | If true, include an additional summary row in the response. Default: false | |
| use_account_attribution_setting | No | If true, use the attribution settings defined at the ad account level. Default: false | |
| use_unified_attribution_setting | No | If true, use unified attribution settings defined at the ad set level. Recommended for consistency with Ads Manager. Default: true | |
| filtering | No | List of filter objects. Each has 'field', 'operator', and 'value'. Example: [{field: 'spend', operator: 'GREATER_THAN', value: 50}] | |
| sort | No | Sort field and direction. Format: {field}_ascending or {field}_descending. Example: impressions_descending | |
| since | No | Start timestamp for time-based pagination (Unix or strtotime). Only used when time_range and time_ranges are not set | |
| until | No | End timestamp for time-based pagination (Unix or strtotime). Only used when time_range and time_ranges are not set | |
| locale | No | Locale for text responses (e.g., en_US). Controls language and formatting | |
| limit | No | Maximum number of results to return per page (1-100, default: 25) | |
| after | No | Cursor for the next page of results, from response.paging.cursors.after | |
| before | No | Cursor for the previous page of results, from response.paging.cursors.before | |
| offset | No | Alternative pagination: number of results to skip | |
| ad_id | Yes | Ad ID, e.g., '6123456789012' |