get_adset_insights
Retrieve performance insights for a specific ad set, including metrics such as impressions, clicks, spend, and actions, with optional age, gender, or region breakdowns and custom date ranges.
Instructions
Get performance insights for a specific ad set.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| adset_id | Yes | Ad Set ID | |
| fields | No | Comma-separated insight fields | impressions,clicks,spend,reach,frequency,cpc,cpm,ctr,actions,cost_per_action_type |
| breakdowns | No | Breakdown dimensions: age,gender,country,region,placement,device_platform | |
| date_preset | No | Date preset: TODAY,YESTERDAY,LAST_7D,LAST_14D,LAST_30D,THIS_MONTH,LAST_MONTH,THIS_QUARTER,LAST_QUARTER,THIS_YEAR,LAST_YEAR | |
| time_range | No | JSON string {since,until} in YYYY-MM-DD format | |
| time_increment | No | Time granularity: all_days, 1, 7, monthly | |
| filtering | No | JSON string for filtering | |
| level | No | Aggregation level: campaign, adset, ad |
Implementation Reference
- src/tools/insights.ts:50-65 (handler)Handler function for get_adset_insights tool. Takes an adset_id and optional insight params, makes a GET request to Meta Graph API /{adset_id}/insights, and returns the JSON response with rate limit info.
server.tool( "get_adset_insights", "Get performance insights for a specific ad set.", { adset_id: z.string().describe("Ad Set ID"), ...insightParams, }, async ({ adset_id, ...params }) => { try { const { data, rateLimit } = await client.get(`/${adset_id}/insights`, { ...params }); return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] }; } catch (error) { return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } ); - src/tools/insights.ts:53-56 (schema)Input schema for get_adset_insights. Requires adset_id (string) and accepts all shared insight params (fields, breakdowns, date_preset, time_range, time_increment, filtering, level).
{ adset_id: z.string().describe("Ad Set ID"), ...insightParams, }, - src/tools/insights.ts:50-65 (registration)Registration of the 'get_adset_insights' tool via server.tool() within the registerInsightTools function in insights.ts.
server.tool( "get_adset_insights", "Get performance insights for a specific ad set.", { adset_id: z.string().describe("Ad Set ID"), ...insightParams, }, async ({ adset_id, ...params }) => { try { const { data, rateLimit } = await client.get(`/${adset_id}/insights`, { ...params }); return { content: [{ type: "text" as const, text: JSON.stringify({ ...data as object, _rateLimit: rateLimit }, null, 2) }] }; } catch (error) { return { content: [{ type: "text" as const, text: `Failed: ${error instanceof Error ? error.message : String(error)}` }], isError: true }; } } ); - src/tools/insights.ts:5-13 (helper)Shared insightParams schema object reused by get_adset_insights and other insight tools, defining default fields and optional params like breakdowns, date_preset, time_range, time_increment, filtering, and level.
const insightParams = { fields: z.string().optional().default("impressions,clicks,spend,reach,frequency,cpc,cpm,ctr,actions,cost_per_action_type").describe("Comma-separated insight fields"), breakdowns: z.string().optional().describe("Breakdown dimensions: age,gender,country,region,placement,device_platform"), date_preset: z.string().optional().describe("Date preset: TODAY,YESTERDAY,LAST_7D,LAST_14D,LAST_30D,THIS_MONTH,LAST_MONTH,THIS_QUARTER,LAST_QUARTER,THIS_YEAR,LAST_YEAR"), time_range: z.string().optional().describe("JSON string {since,until} in YYYY-MM-DD format"), time_increment: z.string().optional().describe("Time granularity: all_days, 1, 7, monthly"), filtering: z.string().optional().describe("JSON string for filtering"), level: z.string().optional().describe("Aggregation level: campaign, adset, ad"), };