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.

When to use it

Use it for spend and results over a date range, at account, campaign, ad set or ad level.
Give it a date_preset, or date_from with date_to. Presets such as last_7d end yesterday.
For a ranked table, set group_by to entity: one row per campaign, ad set or ad for the whole range. Without it you get one row per entity per day. group_by does not work with entity_type set to account.
campaign_ids narrows ad set or ad rows to those campaigns. adset_ids narrows ad rows. To pick entities at their own level, use entity_ids. Each list takes up to 50 IDs.
For a split by age, gender, country or placement, use adsap_get_insights_breakdown.

Worked example

You ask

“Rank my campaigns in act_1234567890 by spend for the last 7 days, with results and ROAS.”

The assistant calls `adsap_get_insights`


{
  "ad_account_id": "act_1234567890",
  "entity_type": "campaign",
  "date_preset": "last_7d",
  "group_by": "entity",
  "metrics": ["spend", "results", "cost_per_result", "purchase_roas"],
  "sort_by": "spend",
  "sort_dir": "desc"
}

Adsap returns

The field names are the ones Adsap returns. The values are examples.


{
  "entity_type": "campaign",
  "group_by": "entity",
  "date_range": { "from": "2026-09-11", "to": "2026-09-17" },
  "currency": "USD",
  "rows": [
    {
      "entity_id": "120210000000002",
      "entity_name": "Spring sale",
      "spend": 1840.5,
      "results": 96,
      "cost_per_result": 19.1719,
      "purchase_roas": 3.4,
      "result_type": "actions:offsite_conversion.fb_pixel_purchase"
    },
    {
      "entity_id": "120210000000004",
      "entity_name": "Summer collection",
      "spend": 1210.25,
      "results": 41,
      "cost_per_result": 29.5183,
      "purchase_roas": 2.2,
      "result_type": "actions:offsite_conversion.fb_pixel_purchase"
    }
  ],
  "summary": {
    "total_spend": 3050.75,
    "purchase_roas": 2.92,
    "result_type": "actions:offsite_conversion.fb_pixel_purchase",
    "total_results": 137,
    "cost_per_result": 22.2682
  }
}

How to read it

Each row is one campaign for the whole range. result_type names what a result is for that row, here website purchases. When a campaign mixes ad sets with different goals, result_type is multiple, results is null, and results_breakdown lists each type. summary covers every entity in the set, not only the page returned. Its ratios are worked out from the summed totals.

Rows also carry entity_status, date_start and date_stop. Next to the data, a meta object holds is_stale, last_refreshed_at, refresh_note and next_cursor. Pass next_cursor back as cursor to read the next page.

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.

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.

The Meta Ads MCP server page shows how to connect Meta Ads to Claude, ChatGPT or Perplexity.

Get insights (adsap_get_insights)