get_adaccount_insights

Retrieves performance insights for a specified Facebook ad account.

This tool interfaces with the Facebook Graph API's Insights edge to fetch comprehensive performance data, such as impressions, reach, cost, conversions, and more. It supports various options for filtering, time breakdowns, and attribution settings. Note that some metrics returned might be estimated or in development CRITICAL: This function MUST automatically fetch ALL pages using pagination. When the response contains a 'paging.next' URL, IMMEDIATELY and AUTOMATICALLY use the facebook_fetch_pagination_url tool to fetch the next page. Continue this process until no 'next' URL exists. Do NOT ask the user for permission to continue pagination. Do NOT stop after the first page. Always return the complete consolidated list of ALL ad accounts across all pages in a single response. This is a requirement, not optional behavior..

Args: act_id (str): The target ad account ID, prefixed with 'act_', e.g., 'act_1234567890'. fields (Optional[List[str]]): A list of specific metrics and fields to retrieve. If omitted, a default set is returned by the API. Common examples include: - 'account_currency', 'account_id', 'account_name' - 'actions', 'clicks', 'conversions' - 'cpc', 'cpm', 'cpp', 'ctr' - 'frequency', 'impressions', 'reach', 'spend'. 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'. This parameter is ignored if 'time_range', 'time_ranges', 'since', or 'until' is provided. time_range (Optional[Dict[str, str]]): A specific time range defined by 'since' and 'until' dates in 'YYYY-MM-DD' format, e.g., {'since': '2023-10-01', 'until': '2023-10-31'}. Overrides 'date_preset'. Ignored if 'time_ranges' is provided. time_ranges (Optional[List[Dict[str, str]]]): An array of time range objects ({'since': '...', 'until': '...'}) for comparing multiple periods. Overrides 'time_range' and 'date_preset'. Time ranges can overlap. time_increment (str | int): Specifies the granularity of the time breakdown. - An integer from 1 to 90 indicates the number of days per data point. - 'monthly': Aggregates data by month. - 'all_days': Provides a single summary row for the entire period. Default: 'all_days'. level (str): The level of aggregation for the insights. Options: 'account', 'campaign', 'adset', 'ad'. Default: 'account'. action_attribution_windows (Optional[List[str]]): Specifies the attribution windows to consider for actions (conversions). Examples: '1d_view', '7d_view', '28d_view', '1d_click', '7d_click', '28d_click', 'dda', 'default'. The API default may vary; ['7d_click', '1d_view'] is common. action_breakdowns (Optional[List[str]]): Segments the 'actions' results based on specific dimensions. Examples: 'action_device', 'action_type', 'conversion_destination', 'action_destination'. Default: ['action_type']. action_report_time (Optional[str]): Determines when actions are counted. - 'impression': Actions are attributed to the time of the ad impression. - 'conversion': Actions are attributed to the time the conversion occurred. - 'mixed': Uses 'impression' time for paid metrics, 'conversion' time for organic. Default: 'mixed'. breakdowns (Optional[List[str]]): Segments the results by dimensions like demographics or placement. Examples: 'age', 'gender', 'country', 'region', 'dma', 'impression_device', 'publisher_platform', 'platform_position', 'device_platform'. Note: Not all breakdowns can be combined. default_summary (bool): If True, includes an additional summary row in the response. Default: False. use_account_attribution_setting (bool): If True, forces the report to use the attribution settings defined at the ad account level. Default: False. use_unified_attribution_setting (bool): If True, uses the unified attribution settings defined at the ad set level. This is generally recommended for consistency with Ads Manager reporting. Default: True. filtering (Optional[List[dict]]): A list of filter objects to apply to the data. Each object should have 'field', 'operator', and 'value' keys. Example: [{'field': 'spend', 'operator': 'GREATER_THAN', 'value': 50}]. sort (Optional[str]): Specifies the field and direction for sorting the results. Format: '{field_name}_ascending' or '{field_name}_descending'. Example: 'impressions_descending'. limit (Optional[int]): The maximum number of results to return in one API response page. after (Optional[str]): A pagination cursor pointing to the next page of results. Obtained from the 'paging.cursors.after' field of a previous response. before (Optional[str]): A pagination cursor pointing to the previous page of results. Obtained from the 'paging.cursors.before' field of a previous response. offset (Optional[int]): An alternative pagination method; skips the specified number of results. Use cursor-based pagination ('after'/'before') when possible. since (Optional[str]): For time-based pagination (used if 'time_range' and 'time_ranges' are not set), the start timestamp (Unix or strtotime value). until (Optional[str]): For time-based pagination (used if 'time_range' and 'time_ranges' are not set), the end timestamp (Unix or strtotime value). 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 account insights. The main results are in the 'data' list, and pagination info is in the 'paging' object.

Example: ```python # Get basic ad account performance for the last 30 days insights = get_adaccount_insights( act_id="act_123456789", fields=["impressions", "clicks", "spend", "ctr"], limit=25 )

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