get_ad_insights
Fetch performance data for a single Facebook ad: impressions, clicks, spend, conversions, engagement, and video metrics. Filter by date, breakdown, attribution, and sorting to diagnose campaign results.
Instructions
Retrieves detailed performance insights for a specific Facebook ad.
Fetches performance metrics for an individual ad (ad group), such as impressions, clicks, conversions, engagement, video views, etc. Allows for customization via time periods, breakdowns, filtering, sorting, and attribution settings. Note that some metrics may be estimated or in development.
Args: ad_id (str): The ID of the target ad (ad group), e.g., '6123456789012'. fields (Optional[List[str]]): A list of specific metrics and fields. Common examples: 'ad_name', 'adset_name', 'campaign_name', 'account_id', 'impressions', 'clicks', 'spend', 'ctr', 'cpc', 'cpm', 'cpp', 'reach', 'frequency', 'actions', 'conversions', 'cost_per_action_type', 'inline_link_clicks', 'inline_post_engagement', 'unique_clicks', 'video_p25_watched_actions', 'video_p50_watched_actions', 'video_p75_watched_actions', 'video_p95_watched_actions', 'video_p100_watched_actions', 'video_avg_time_watched_actions', 'website_ctr', 'website_purchases'. date_preset (str): A predefined relative time range ('last_30d', 'last_7d', etc.). Default: 'last_30d'. Ignored if 'time_range', 'time_ranges', 'since', or 'until' is used. time_range (Optional[Dict[str, str]]): Specific time range {'since':'YYYY-MM-DD','until':'YYYY-MM-DD'}. Overrides 'date_preset'. Ignored if 'time_ranges' is provided. time_ranges (Optional[List[Dict[str, str]]]): Array of time range objects for comparison. Overrides 'time_range' and 'date_preset'. time_increment (str | int): Granularity of the time breakdown ('all_days', 'monthly', 1-90 days). Default: 'all_days'. action_attribution_windows (Optional[List[str]]): Specifies attribution windows for actions. Examples: '1d_view', '7d_click'. Default depends on API/settings. action_breakdowns (Optional[List[str]]): Segments 'actions' results. Examples: 'action_device', 'action_type'. Default: ['action_type']. action_report_time (Optional[str]): Time basis for action stats ('impression', 'conversion', 'mixed'). Default: 'mixed'. breakdowns (Optional[List[str]]): Segments results by dimensions. Examples: 'age', 'gender', 'country', 'publisher_platform', 'impression_device', 'platform_position', 'device_platform'. default_summary (bool): If True, includes an additional summary row. Default: False. use_account_attribution_setting (bool): If True, uses the ad account's attribution settings. Default: False. use_unified_attribution_setting (bool): If True, uses unified attribution settings. Default: True. level (Optional[str]): Level of aggregation. Should typically be 'ad'. Default: 'ad'. filtering (Optional[List[dict]]): List of filter objects {'field': '...', 'operator': '...', 'value': '...'}. sort (Optional[str]): Field and direction for sorting ('{field}_ascending'/'_descending'). limit (Optional[int]): Maximum number of results per page. after (Optional[str]): Pagination cursor for the next page. before (Optional[str]): Pagination cursor for the previous page. offset (Optional[int]): Alternative pagination: skips N results. since (Optional[str]): Start timestamp for time-based pagination (if time ranges absent). until (Optional[str]): End timestamp for time-based pagination (if time ranges absent). locale (Optional[str]): The locale for text responses (e.g., 'en_US'). This controls language and formatting of text fields in the response.
Returns:
Dict: A dictionary containing the requested ad insights, with 'data' and 'paging' keys.
Example: ```python # Get basic ad performance for the last 30 days ad_insights = get_ad_insights( ad_id="6123456789012", fields=["ad_name", "impressions", "clicks", "spend", "ctr", "reach"], limit=10 )
# Get ad performance with platform breakdown for last 14 days
platform_insights = get_ad_insights(
ad_id="6123456789012",
fields=["ad_name", "impressions", "clicks", "spend"],
breakdowns=["publisher_platform", "platform_position"],
date_preset="last_14d"
)
# Fetch the next page of basic performance if available
next_page_url = ad_insights.get("paging", {}).get("next")
if next_page_url:
next_page = fetch_pagination_url(url=next_page_url)
```
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | ||
| ad_id | Yes | ||
| after | No | ||
| level | No | ||
| limit | No | ||
| since | No | ||
| until | No | ||
| before | No | ||
| fields | No | ||
| locale | No | ||
| offset | No | ||
| filtering | No | ||
| breakdowns | No | ||
| time_range | No | ||
| date_preset | No | last_30d | |
| time_ranges | No | ||
| time_increment | No | all_days | |
| default_summary | No | ||
| action_breakdowns | No | ||
| action_report_time | No | ||
| action_attribution_windows | No | ||
| use_account_attribution_setting | No | ||
| use_unified_attribution_setting | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |