Tools for retrieving performance metrics across campaigns, ad sets, ads, and ad accounts. Insights include spend, ROAS, reach, impressions, conversions, and more.
Common Parameters
All insights tools share these parameters for controlling what data is returned:
| Parameter | Type | Description |
|---|---|---|
fields |
string[] |
Metrics to retrieve (default: ["impressions", "spend"]). Examples: impressions, spend, reach, clicks, ctr, cpm, cpp, actions, conversions, purchase_roas |
time_range |
object | undefined |
Custom date range: { since: "YYYY-MM-DD", until: "YYYY-MM-DD" } |
time_increment |
string | number |
Time granularity: "all_days" (default), "monthly", or 1-90 for N-day periods |
level |
string |
Aggregation level: "account", "campaign", "adset", or "ad" |
breakdowns |
string[] | undefined |
Segmentation dimensions (e.g., age, gender, placement, country) |
action_attribution_windows |
string[] | undefined |
Attribution windows (e.g., "7d_click", "1d_view") |
action_breakdowns |
string[] | undefined |
Breakdown dimensions for actions |
get_campaign_insights
Retrieve aggregated performance metrics for a Facebook campaign, combining data from all its ad sets and ads.
Parameters
| Parameter | Type | Description |
|---|---|---|
campaign_id |
string |
Campaign ID to retrieve insights for |
Plus all common parameters above.
Example
Natural Language
How did campaign 120211556789 perform last week?
Show me spend and ROAS for my Summer Sale campaign
Direct Query
{
"tool": "get_campaign_insights",
"arguments": {
"campaign_id": "120211556789",
"fields": ["spend", "impressions", "purchase_roas", "actions"],
"time_range": {
"since": "2025-01-01",
"until": "2025-01-07"
}
}
}
get_adset_insights
Retrieve performance metrics for a specific Facebook ad set. Aggregates data from all ads within the ad set.
Parameters
| Parameter | Type | Description |
|---|---|---|
adset_id |
string |
Ad set ID to retrieve insights for |
Plus all common parameters above.
Example
Show me the performance of ad set 120211556789 broken down by age and gender
get_ad_insights
Retrieve performance metrics for a specific Facebook ad, including spend, impressions, clicks, CTR, CPM, and ROAS. Supports breakdown dimensions and custom date ranges.
Parameters
| Parameter | Type | Description |
|---|---|---|
ad_id |
string |
Ad ID to retrieve insights for |
Plus all common parameters above.
Example
What's the CTR and CPC for ad 120211556789 this month?
get_ad_account_insights
Retrieve aggregated performance metrics across all campaigns for a Facebook ad account. Supports level parameter for granular breakdown.
Parameters
| Parameter | Type | Description |
|---|---|---|
account_id |
string |
Facebook Ad Account ID (e.g., act_123456789) |
Plus all common parameters above.
Example
Natural Language
What's my total ad spend this month?
Show me account-level performance broken down by campaign
Direct Query
{
"tool": "get_ad_account_insights",
"arguments": {
"account_id": "act_123456789",
"fields": ["spend", "impressions", "reach", "purchase_roas"],
"time_range": {
"since": "2025-01-01",
"until": "2025-01-31"
},
"level": "campaign"
}
}
Related
- Campaign Tools Manage campaign configuration
- Ad Account Tools Discover and inspect accounts