Get Insights
adsap_get_insightsRetrieve aggregated spend and performance metrics for accounts, campaigns, ad sets, or ads over a date range. Served from ADSAP's insights cache and automatically refreshed live from Meta when the cache is missing or stale (>6h) — no dashboard visit required. Results / cost_per_result are objective-aware at every level (result_type per row names what a result is; 'multiple' when children mix; reach and ad recall fetched live). Parent filters campaign_ids (on adset/ad rows) and adset_ids (on ad rows) narrow the set server-side — sort, limit and summary then describe the filtered set; rows expose adset_id / campaign_id.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| date_to | No | YYYY-MM-DD. Required if no date_preset. | |
| metrics | No | Any of: spend, impressions, clicks, link_clicks, outbound_clicks, conversions, purchase_conversions, lead_conversions, add_to_cart_conversions, conversion_value, purchase_value, video_views (=75% completion), video_thruplay, video_p25, video_p50, video_p75, video_p95, video_p100, lpv (landing page views), post_engagement, video_3s (3-sec plays), contact, checkout, registration, app_install, app_activation, subscribe, start_trial, view_content, add_payment_info, submit_application, add_to_wishlist, search, schedule, donate, find_location, customize_product, app_purchase, app_add_to_cart, app_initiate_checkout, app_add_payment_info, app_complete_registration, app_content_view, app_search, app_add_to_wishlist, app_level_achieved, app_achievement_unlocked, app_tutorial_completion, app_spent_credits, app_rate, subscribe_value (conversion value), start_trial_value (conversion value), ctr (link CTR), ctr_all, cpc (cost/link click), cpc_all, cpm, cost_per_conversion, purchase_roas, aov, conversion_rate, hook_rate, hold_rate, lpv_rate, cost_per_lpv, cost_per_lead, cost_per_atc, cost_per_thruplay, cost_per_post_engagement, cost_per_purchase, cost_per_subscribe, cost_per_start_trial, cost_per_view_content, cost_per_add_payment_info, cost_per_submit_application, cost_per_add_to_wishlist, cost_per_search, cost_per_schedule, cost_per_donate, cost_per_find_location, cost_per_customize_product, outbound_ctr, quality_ranking (ad level only, latest text value), engagement_rate_ranking (ad level only, latest text value), conversion_rate_ranking (ad level only, latest text value), results (objective-aware count at every level; the type is in result_type per row ('multiple' when children mix, then results is null and results_breakdown lists each type); reach / ad recall are fetched live per range), cost_per_result (spend/results (reach: per 1,000 people reached, Meta convention)). Also accepts custom-conversion refs: cc_<id> (count), cc_<id>_value (conversion value), cost_per_cc_<id> (spend/count), where <id> is the numeric custom conversion id from adsap_list_custom_conversions. Defaults to spend, impressions, link_clicks, ctr, cpc, cpm, results, cost_per_result, purchase_roas. | |
| sort_by | No | ||
| group_by | No | 'entity': one aggregated row per campaign/ad set/ad across the whole date range (ratios correctly weighted from summed raws) — use for ranked tables. Omit for per-entity-per-day rows. Not valid with entity_type='account' (account is already a rollup and returns per-day rows). | |
| sort_dir | No | ||
| adset_ids | No | Parent filter: keep only the ads in these ad sets (entity_type ad; to pick ad sets themselves use entity_ids). Composes with entity_ids and campaign_ids. Max 50. | |
| date_from | No | YYYY-MM-DD. Required if no date_preset. | |
| cache_mode | No | cache_only (never hit Meta) | cache_then_refresh (default — auto-refresh from Meta when cache is missing or stale) | force_refresh (always refresh from Meta first) | |
| entity_ids | No | Filter to specific IDs. Max 50. | |
| date_preset | No | Required if no date_from/date_to | |
| entity_type | Yes | ||
| campaign_ids | No | Parent filter: keep only the ad sets / ads whose ad set belongs to one of these campaigns (entity_type adset or ad; to pick campaigns themselves use entity_ids). Mapping comes from the cached insight rows themselves (campaign_id stored with every ad-set / ad row, so deleted or archived ad sets stay linked) with the ad-set metadata cache (hourly) as fallback. Composes with entity_ids and adset_ids. Max 50. | |
| ad_account_id | Yes | ||
| live_ad_recallers | No | Deprecated: awareness results (reach, estimated ad recallers) are fetched live automatically wherever a row's result_type is a people count. Kept for compatibility: when true, estimated_ad_recallers is also attached to every row of the page (adds one Meta call). |