get_campaign_metrics

Retrieve specific performance metrics for Klaviyo email campaigns, including open rates, click rates, and delivery statistics, within defined date ranges.

Input Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	ID of the campaign to retrieve metrics for
`metrics`	No	Specific metrics to retrieve (e.g., ['open_rate', 'click_rate', 'delivered', 'bounce_rate'])
`start_date`	No	Start date for metrics (ISO format)
`end_date`	No	End date for metrics (ISO format)
`conversion_metric_id`	No	ID of the metric to use for conversion statistics

Implementation Reference

src/tools/reporting.js:23-112 (handler)

The handler function that executes the get_campaign_metrics tool. It constructs a payload for the Klaviyo /campaign-values-reports/ endpoint, handles timeframe and statistics validation, includes fallback logic, and returns formatted results or error.

async (params) => {
  try {
    logger.info(`Retrieving campaign metrics for campaign ID: ${params.id}`);

    // Prepare statistics list with valid names
    const statistics = params.metrics || DEFAULT_STATISTICS.standard;

    // Validate statistics to ensure they're supported by the API
    const validatedStatistics = statistics.filter(stat => VALID_CAMPAIGN_STATISTICS.includes(stat));

    if (validatedStatistics.length === 0) {
      logger.warn(`No valid statistics provided for campaign metrics. Using default: ${DEFAULT_STATISTICS.basic}`);
      validatedStatistics.push(...DEFAULT_STATISTICS.basic);
    }

    // Create payload for the reporting API
    const payload = {
      data: {
        type: "campaign-values-report",
        attributes: {
          statistics: validatedStatistics,
          filter: FILTER_TEMPLATES.campaignId(params.id),
          conversion_metric_id: params.conversion_metric_id || API_CONFIG.defaultConversionMetricId
        }
      }
    };

    // Add timeframe - either predefined or custom dates
    if (params.start_date && params.end_date) {
      payload.data.attributes.timeframe = {
        start: params.start_date,
        end: params.end_date
      };
      logger.debug(`Using custom timeframe: ${params.start_date} to ${params.end_date}`);
    } else {
      // Default to last 30 days
      payload.data.attributes.timeframe = {
        key: API_CONFIG.defaultTimeframe
      };
      logger.debug(`Using default timeframe: ${API_CONFIG.defaultTimeframe}`);
    }

    logger.debug('Campaign metrics request payload', payload);

    // Define the fallback function
    const fallbackFn = async (error) => {
      logger.warn(`Error retrieving campaign metrics with initial parameters: ${error.message}. Attempting fallback.`);
      
      // Fallback to minimal statistics set
      const fallbackPayload = {
        data: {
          type: "campaign-values-report",
          attributes: {
            statistics: DEFAULT_STATISTICS.basic,
            timeframe: {
              key: API_CONFIG.defaultTimeframe
            },
            conversion_metric_id: API_CONFIG.defaultConversionMetricId,
            filter: FILTER_TEMPLATES.campaignId(params.id)
          }
        }
      };

      logger.debug('Campaign metrics fallback payload', fallbackPayload);
      
      const fallbackResults = await klaviyoClient.post('/campaign-values-reports/', fallbackPayload);
      logger.info(`Successfully retrieved basic campaign metrics for campaign ID: ${params.id} using fallback`);
      
      return fallbackResults;
    };

    // Use the post method with the fallback function
    const results = await klaviyoClient.post('/campaign-values-reports/', payload, fallbackFn);

    logger.info(`Successfully retrieved campaign metrics for campaign ID: ${params.id}`);

    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
    };
  } catch (error) {
    logger.error(`Failed to retrieve campaign metrics (including fallback attempt): ${error.message}`, {
      campaignId: params.id
    });

    return {
      content: [{ type: "text", text: `Error retrieving campaign metrics (including fallback attempt): ${error.message}` }],
      isError: true
    };
  }
},

src/tools/reporting.js:16-22 (schema)

Zod schema defining the input parameters for the get_campaign_metrics tool: campaign ID (required), optional metrics list, date range, and conversion metric ID.

{
  id: z.string().describe("ID of the campaign to retrieve metrics for"),
  metrics: z.array(z.string()).optional().describe("Specific metrics to retrieve (e.g., ['open_rate', 'click_rate', 'delivered', 'bounce_rate'])"),
  start_date: z.string().optional().describe("Start date for metrics (ISO format)"),
  end_date: z.string().optional().describe("End date for metrics (ISO format)"),
  conversion_metric_id: z.string().optional().describe("ID of the metric to use for conversion statistics")
},

src/tools/reporting.js:14-114 (registration)

Direct registration of the get_campaign_metrics tool using server.tool within the registerReportingTools function.

server.tool(
  "get_campaign_metrics",
  {
    id: z.string().describe("ID of the campaign to retrieve metrics for"),
    metrics: z.array(z.string()).optional().describe("Specific metrics to retrieve (e.g., ['open_rate', 'click_rate', 'delivered', 'bounce_rate'])"),
    start_date: z.string().optional().describe("Start date for metrics (ISO format)"),
    end_date: z.string().optional().describe("End date for metrics (ISO format)"),
    conversion_metric_id: z.string().optional().describe("ID of the metric to use for conversion statistics")
  },
  async (params) => {
    try {
      logger.info(`Retrieving campaign metrics for campaign ID: ${params.id}`);

      // Prepare statistics list with valid names
      const statistics = params.metrics || DEFAULT_STATISTICS.standard;

      // Validate statistics to ensure they're supported by the API
      const validatedStatistics = statistics.filter(stat => VALID_CAMPAIGN_STATISTICS.includes(stat));

      if (validatedStatistics.length === 0) {
        logger.warn(`No valid statistics provided for campaign metrics. Using default: ${DEFAULT_STATISTICS.basic}`);
        validatedStatistics.push(...DEFAULT_STATISTICS.basic);
      }

      // Create payload for the reporting API
      const payload = {
        data: {
          type: "campaign-values-report",
          attributes: {
            statistics: validatedStatistics,
            filter: FILTER_TEMPLATES.campaignId(params.id),
            conversion_metric_id: params.conversion_metric_id || API_CONFIG.defaultConversionMetricId
          }
        }
      };

      // Add timeframe - either predefined or custom dates
      if (params.start_date && params.end_date) {
        payload.data.attributes.timeframe = {
          start: params.start_date,
          end: params.end_date
        };
        logger.debug(`Using custom timeframe: ${params.start_date} to ${params.end_date}`);
      } else {
        // Default to last 30 days
        payload.data.attributes.timeframe = {
          key: API_CONFIG.defaultTimeframe
        };
        logger.debug(`Using default timeframe: ${API_CONFIG.defaultTimeframe}`);
      }

      logger.debug('Campaign metrics request payload', payload);

      // Define the fallback function
      const fallbackFn = async (error) => {
        logger.warn(`Error retrieving campaign metrics with initial parameters: ${error.message}. Attempting fallback.`);
        
        // Fallback to minimal statistics set
        const fallbackPayload = {
          data: {
            type: "campaign-values-report",
            attributes: {
              statistics: DEFAULT_STATISTICS.basic,
              timeframe: {
                key: API_CONFIG.defaultTimeframe
              },
              conversion_metric_id: API_CONFIG.defaultConversionMetricId,
              filter: FILTER_TEMPLATES.campaignId(params.id)
            }
          }
        };

        logger.debug('Campaign metrics fallback payload', fallbackPayload);
        
        const fallbackResults = await klaviyoClient.post('/campaign-values-reports/', fallbackPayload);
        logger.info(`Successfully retrieved basic campaign metrics for campaign ID: ${params.id} using fallback`);
        
        return fallbackResults;
      };

      // Use the post method with the fallback function
      const results = await klaviyoClient.post('/campaign-values-reports/', payload, fallbackFn);

      logger.info(`Successfully retrieved campaign metrics for campaign ID: ${params.id}`);

      return {
        content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
      };
    } catch (error) {
      logger.error(`Failed to retrieve campaign metrics (including fallback attempt): ${error.message}`, {
        campaignId: params.id
      });

      return {
        content: [{ type: "text", text: `Error retrieving campaign metrics (including fallback attempt): ${error.message}` }],
        isError: true
      };
    }
  },
  { description: "Get performance metrics for a specific campaign (open rates, click rates, etc.)" }
);

src/server.js:38-38 (registration)
Invocation of registerReportingTools(server) which includes the registration of get_campaign_metrics along with other reporting tools.
```
registerReportingTools(server);
```

Klaviyo MCP Server