get_adset_insights

Instructions

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"),
  };