get_insights

Get performance insights for a campaign, ad set, ad or account.

Args:
    object_id: ID of the campaign, ad set, ad or account. You can also use the alias parameters below.
    account_id: Alias for object_id when querying account-level insights
    campaign_id: Alias for object_id when querying campaign-level insights
    adset_id: Alias for object_id when querying ad-set-level insights
    ad_id: Alias for object_id when querying ad-level insights
    access_token: Meta API access token (optional - will use cached token if not provided)
    time_range: Either a preset time range string or a dictionary with "since" and "until" dates in YYYY-MM-DD format
               Preset options: today, yesterday, this_month, last_month, this_quarter, maximum, data_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
               Dictionary example: {"since":"2023-01-01","until":"2023-01-31"}
    breakdown: Optional breakdown dimension. Valid values include:
               Demographic: age, gender, country, region, dma
               Platform/Device: device_platform, platform_position, publisher_platform, impression_device
               NOTE: platform_position is a Meta-restricted breakdown — Meta requires it to be paired
               with publisher_platform and is incompatible with the default action_breakdowns=[action_type].
               When you pass platform_position, this tool auto-adds publisher_platform and drops the
               action-typed fields (actions, action_values, conversions, cost_per_action_type) from the
               response. Use publisher_platform alone if you need action data alongside placement.
               Creative Assets: ad_format_asset, body_asset, call_to_action_asset, description_asset,
                              image_asset, link_url_asset, title_asset, video_asset, media_type,
                              creative_relaxation_asset_type, flexible_format_asset_type,
                              gen_ai_asset_type
               NOTE: Asset breakdowns (image_asset, video_asset, etc.) only return data for ads
               running with Dynamic Creative; for non-DCO ads, expect empty rows.
               NOTE: media_type collides with the default action_breakdowns=[action_type], so
               this tool auto-overrides action_breakdowns to [] when you pass media_type.
               Action-typed metrics (actions, action_values, conversions) are still returned
               but are no longer sliced by action_type alongside media_type.
               media_asset_url, media_creator, media_destination_url, media_format,
               media_origin_url, and media_text_content are NOT supported by Meta's Insights API
               (Meta returns "(#100) Tried accessing nonexisting field"). Use the asset breakdowns
               above instead.
               Campaign/Ad Attributes: breakdown_ad_objective, breakdown_reporting_ad_id, app_id, product_id
               Conversion Tracking: coarse_conversion_value, conversion_destination, standard_event_content_type,
                                   signal_source_bucket, is_conversion_id_modeled, fidelity_type, redownload
               Time-based: hourly_stats_aggregated_by_advertiser_time_zone, 
                          hourly_stats_aggregated_by_audience_time_zone, frequency_value
               Extensions/Landing: ad_extension_domain, ad_extension_url, landing_destination, 
                                  mdsa_landing_destination
               Attribution: sot_attribution_model_type, sot_attribution_window, sot_channel, 
                           sot_event_type, sot_source
               Mobile/SKAN: skan_campaign_id, skan_conversion_id, skan_version, postback_sequence_index
               CRM/Business: crm_advertiser_l12_territory_ids, crm_advertiser_subvertical_id,
                            crm_advertiser_vertical_id, crm_ult_advertiser_id, user_persona_id, user_persona_name
               Advanced: hsid, is_auto_advance, is_rendered_as_delayed_skip_ad, mmm, place_page_id,
                        marketing_messages_btn_name, impression_view_time_advertiser_hour_v2, comscore_market,
                        comscore_market_code
    level: Level of aggregation (ad, adset, campaign, account)
    limit: Maximum number of results to return per page (default: 25, Meta API allows much higher values)
    after: Pagination cursor to get the next set of results. Use the 'after' cursor from previous response's paging.next field.
    action_attribution_windows: Optional list of attribution windows (e.g., ["1d_click", "7d_click", "1d_view"]).
               When specified, actions include additional fields for each window. The 'value' field always shows 7d_click.
    action_breakdowns: Optional list of action_breakdowns to apply to action-typed metrics. Pass [] to disable
               the default action_type slicing (required when combining action data with breakdowns that collide
               with action_type, e.g. media_type — auto-applied for media_type when not set).
               Meta supports values like action_type, action_target_id, action_destination, etc.
    compact: When True, strips redundant action-type duplicates from the response
             (omni_*, onsite_web_*, offsite_conversion.fb_pixel_*, etc.) to reduce
             payload size by ~60%. The canonical action types (purchase, add_to_cart,
             view_content, etc.) are always preserved. Default: False.

Note on response size: This tool always returns a fixed set of fields (impressions, clicks,
spend, cpc, cpm, ctr, reach, actions, action_values, etc.) and cannot filter to a subset.
For large result sets (50+ rows), the actions/action_values arrays can make responses very
large (1–2MB+). If you only need specific metrics like spend or impressions, consider using
bulk_get_insights with compact=true and the fields parameter:
    bulk_get_insights(level="ad", account_ids=[...], compact=true, fields=["spend", "impressions"])
bulk_get_insights supports level="ad", "adset", "campaign", and "account".