Get Meta Ad Set Insights
meta_ads_get_adset_insightsRetrieve performance metrics for a Meta ad set, including impressions, clicks, spend, and conversions, to analyze ad effectiveness.
Instructions
Retrieve performance insights for a specific Meta ad set.
Provides advertising statistics for an ad set, useful for analyzing performance across its child ads.
Args:
adset_id (string): Ad set ID, e.g., '6123456789012'
fields (string[]): Metrics to retrieve. Common: adset_name, campaign_name, impressions, clicks, spend, ctr, reach, actions, cpc, cpm, cpp, cost_per_action_type
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: adset, ad (default: adset)
breakdowns (string[]): Segment by: age, gender, country, publisher_platform, impression_device, platform_position, 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 | |
| adset_id | Yes | Ad set ID, e.g., '6123456789012' |