Get insights (adsap_get_insights)
Platform: Meta · Read or write: Read · Plan: All plans · Consumes a task: No · Preview supported: No
What it does
Returns spend and performance metrics for an account, its campaigns, ad sets or ads over a date range. Results and cost per result follow each entity’s objective, so a lead campaign reports leads and a sales campaign reports purchases. Data comes from Adsap’s insights cache and refreshes from Meta when the cache is missing or older than six hours. You can filter by entity, narrow to specific campaigns or ad sets, sort, and group to one row per entity.
Parameters
Descriptions are shortened from the tool schema. Your assistant sees the full text.
| Name | Type | Required | Description |
|---|---|---|---|
ad_account_id | string | Yes | |
entity_type | one of account, campaign, adset, ad | Yes | |
entity_ids | array of string | No | Filter to specific IDs. Max 50. |
campaign_ids | array of string | 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… Composes with entity_ids and adset_ids. |
adset_ids | array of string | 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_preset | one of today, yesterday, last_3d, last_7d, last_14d, last_30d, this_month, last_month | No | Required if no date_from/date_to. |
date_from | string | No | YYYY-MM-DD. Required if no date_preset. |
date_to | string | No | YYYY-MM-DD. Required if no date_preset. |
metrics | array of string | 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… 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. |
live_ad_recallers | boolean | 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). |
sort_by | string | No | |
sort_dir | one of asc, desc | No | |
limit | number | No | |
cursor | string | No | |
cache_mode | one of cache_only, cache_then_refresh, force_refresh | 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). |
group_by | one of entity | 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). |
Example prompts
- “How did my account perform over the last 7 days?”
- “Rank my campaigns by spend for last month.”
- “Show me cost per result for the ads in the Retargeting ad set this month.”
- “Pull fresh numbers from Meta for yesterday, not the cache.”
Notes
Pass a date preset or an explicit date range; one of the two is required. Cache mode lets you force a live refresh or stay on the cache.
Related tools
adsap_get_account_activities: Retrieve change log for a Meta ad account: budget changes, status toggles, ad creation/deletion, billing events, policy actions.adsap_get_account_health: Full health check on a Meta ad account.adsap_get_account_summary: Structural snapshot of a Meta ad account: campaign counts by status/objective, ad set counts, active ad count, budget allocation, top…adsap_get_insights_breakdown: Live Meta API call: get spend and performance metrics sliced by demographic or placement dimensions (age, gender, platform, country).adsap_list_experiments: List an ad account’s Meta experiments / ad studies (live from Meta): A/B split tests and conversion-lift studies, with type, status…
Guide
Read Insights and reporting for the workflow around this tool, and the Tool reference for every tool.