get_ad_insights

Instructions

Implementation Reference

• src/tools/insights.ts:124-126 (handler)

  The handler function for get_ad_insights. It takes args containing an ad_id, constructs a Meta Graph API path /{ad_id}/insights, builds query params via insightsParams with level='ad', and makes a GET request via metaGet.

    handler: async (args) =>
      metaGet(`/${String(args.ad_id)}/insights`, insightsParams(args, "ad")),
  },

• src/tools/insights.ts:120-123 (schema)

  Input schema for get_ad_insights: requires ad_id (string) plus optional shared parameters like date_preset, time_range, breakdowns, action_breakdowns, time_increment, filtering, fields, limit, and after.

  inputSchema: {
    ad_id: z.string(),
    ...SHARED_INPUT_SCHEMA,
  },

• src/tools/insights.ts:115-126 (registration)

  The full tool definition for get_ad_insights registered as part of the insightsTools array exported from src/tools/insights.ts. This array is imported in both src/index.ts and src/http.ts and registered via McpServer.registerTool().

  {
    name: "get_ad_insights",
    description:
      "Pull performance metrics for ONE ad. Same fields/breakdowns as get_campaign_insights. " +
      "Use this to compare creative performance at the individual-ad level.",
    inputSchema: {
      ad_id: z.string(),
      ...SHARED_INPUT_SCHEMA,
    },
    handler: async (args) =>
      metaGet(`/${String(args.ad_id)}/insights`, insightsParams(args, "ad")),
  },

• src/tools/insights.ts:40-55 (helper)

  Helper function insightsParams builds query parameters for Meta insights API calls. It sets the level (e.g., 'ad'), joins fields array into comma-separated string, handles time_range vs date_preset, and conditionally adds breakdowns, action_breakdowns, time_increment, filtering, limit, and after.

  function insightsParams(args: Record<string, unknown>, level: string): Record<string, unknown> {
    const params: Record<string, unknown> = {
      level,
      fields: (args.fields as string[] | undefined)?.join(",") ?? DEFAULT_INSIGHTS_FIELDS,
    };
    if (args.time_range) params.time_range = args.time_range;
    else params.date_preset = args.date_preset ?? "last_7d";
  
    if (args.breakdowns) params.breakdowns = args.breakdowns;
    if (args.action_breakdowns) params.action_breakdowns = args.action_breakdowns;
    if (args.time_increment !== undefined) params.time_increment = args.time_increment;
    if (args.filtering) params.filtering = args.filtering;
    if (args.limit !== undefined) params.limit = args.limit;
    if (args.after) params.after = args.after;
    return params;
  }

• src/tools/insights.ts:31-32 (helper)

  Default fields constant used by insightsParams when no custom fields are provided.

  const DEFAULT_INSIGHTS_FIELDS =
    "spend,impressions,clicks,cpc,cpm,ctr,reach,frequency,actions,conversions,cost_per_conversion,cost_per_action_type,purchase_roas,video_30_sec_watched_actions,inline_link_clicks";