get_adset_insights

Retrieves performance insights for a specific Facebook ad set.

Provides advertising performance statistics for an ad set, allowing for analysis of metrics across its child ads. Supports time range definitions, breakdowns, filtering, sorting, and attribution settings. Some metrics may be estimated or in development.

Args: adset_id (str): The ID of the target ad set, e.g., '6123456789012'. fields (Optional[List[str]]): A list of specific metrics and fields. Common examples: 'adset_name', 'campaign_name', 'account_id', 'impressions', 'clicks', 'spend', 'ctr', 'reach', 'frequency', 'actions', 'conversions', 'cpc', 'cpm', 'cpp', 'cost_per_action_type', 'video_p25_watched_actions', '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'. 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 ('adset', 'ad'). Default: 'adset'. 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 set insights, with 'data' and 'paging' keys.

Example: ```python # Get ad set performance with breakdown by device for last 14 days insights = get_adset_insights( adset_id="6123456789012", fields=["adset_name", "impressions", "spend"], breakdowns=["impression_device"], date_preset="last_14d" )

# Fetch the next page if available
next_page_url = insights.get("paging", {}).get("next")
if next_page_url:
    next_page_results = fetch_pagination_url(url=next_page_url)
```