get_campaign_insights

Retrieves performance insights for a specific Facebook ad campaign.

Fetches statistics for a given campaign ID, allowing analysis of metrics like impressions, clicks, conversions, spend, etc. Supports time range definitions, breakdowns, and attribution settings.

Args: campaign_id (str): The ID of the target Facebook ad campaign, e.g., '23843xxxxx'. fields (Optional[List[str]]): A list of specific metrics and fields to retrieve. Common examples: 'campaign_name', 'account_id', 'impressions', 'clicks', 'spend', 'ctr', 'reach', 'actions', 'objective', 'cost_per_action_type', 'conversions', 'cpc', 'cpm', 'cpp', 'frequency', 'date_start', 'date_stop'. date_preset (str): A predefined relative time range for the report. 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 used. time_range (Optional[Dict[str, str]]): A 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]]]): An array of time range objects for comparison. Overrides 'time_range' and 'date_preset'. time_increment (str | int): Specifies the granularity of the time breakdown. - Integer (1-90): number of days per data point. - 'monthly': Aggregates data by month. - 'all_days': Single summary row for the period. Default: 'all_days'. action_attribution_windows (Optional[List[str]]): Specifies attribution windows for actions. Examples: '1d_view', '7d_click', '28d_click', etc. 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]): Determines when actions are counted ('impression', 'conversion', 'mixed'). Default: 'mixed'. breakdowns (Optional[List[str]]): Segments results by dimensions. Examples: 'age', 'gender', 'country', 'publisher_platform', 'impression_device'. 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 ('campaign', 'adset', 'ad'). Default: 'campaign'. 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 campaign insights, with 'data' and 'paging' keys.

Example: ```python # Get basic campaign performance for the last 7 days insights = get_campaign_insights( campaign_id="23843xxxxx", fields=["campaign_name", "impressions", "clicks", "spend"], date_preset="last_7d", limit=50 )

# 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)
```