HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
API Reference

Reporting API overview

Our Reporting API allows you to fetch 1:1 matches of campaign and flow performance data shown in the Klaviyo UI. You can create two different types of reports:

  • Values report

    Returns requested statistics for a given campaign or flow over a provided time frame. For example, opens for a specified campaign over the last 12 months.

  • Series report

    Returns requested flow statistics broken down by a specified time interval (daily, hourly, weekly, or monthly) over a provided time frame. For example, weekly click rates for a flow email over the last 30 days.

Before you begin

  • Check out our general API overview to make sure you’re ready to get started with specific endpoints.
  • Make sure that you have flows:read and campaigns:read access for the Flow Reporting and Campaign Reporting endpoints, respectively.

The Query Metrics Aggregates endpoint

You may be using our Query Metric Aggregates endpoint to export reporting data for campaigns and flows. It’s important to note that data from the Query Metric Aggregates endpoint does not match the data reflected in the Klaviyo UI. While this endpoint allows you to filter and group campaign and flow data based on the time an event occurred, performance in the Klaviyo UI is calculated based on send date. We recommend our Reporting API to achieve this use case, which is built to fetch 1:1 matches of data shown in the Klaviyo UI.

Use cases

Here are some example use cases supported by the Reporting API:

  • Request 1:1 matches of campaign and flow performance data shown in the Klaviyo app.
  • Return the overall value of statistics for a given campaign or flow.
  • Request campaign and flow data by statistic, time frame, and metric ID.
  • Filter data by channel and/or campaign ID.

Data model

Values report

A values report request can have the following:

  • attributes

    • statistics (required)
      A list of statistics computed by Klaviyo (see Available statistics).

    • timeframe (required)
      An object that contains fields for setting a predefined time frame (key) or a custom time frame (start and end) to pull data from (max length: 1 year).

    • To set a predefined time frame, use:

    • To set a custom time frame, use:

      • start
        A datetime that represents the start of a custom time frame.
      • end
        A datetime that represents the end of a custom time frame.
    • conversion_metric_id (required)
      The ID of the conversion metric (e.g., the metric ID for Placed Order) used for calculating conversion-based statistics.

    • filter
      A JSON:API filter string for filtering the query.

📘

Note that conversion_metric_id is used for calculating conversion-based statistics. Other statistics fetched in a campaign or flows report will include all values, regardless of whether or not some values triggered conversions. For example, a query for opens will return all opens, including opens that did not trigger a conversion.

Series report

A series report request follows the same data model as a values report request, but it differs in that it additionally contains an interval field for breaking down performance over a specified time frame by day, week, etc. You can set the interval to daily, hourly, weekly, or monthly. If the interval is not specified, it will default to weekly.

Campaign values report

The request below to the Query Campaign Values endpoint queries opens and open rate statistics over the last 12 months:

curl --request POST \
     --url https://a.klaviyo.com/api/campaign-values-reports/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-06-15' \
     --data '
{
  "data": {
    "type": "campaign-values-report",
    "attributes": {
      "timeframe": {
        "key": "last_12_months"
      },
      "conversion_metric_id": "RESQ6t",
      "filter": "equals(campaign_id",\"01GMRWDSA0ARTAKE1SFX8JGXAY\")",

      "statistics": [
        "opens",
        "open_rate"
      ]
    }
  }
}
'
{
  "data": {
    "type": "campaign-values-report",
    "attributes": {
      "results": [
        {
          "groupings": {
            "send_channel": "email",
            "campaign_id": "01GMRWDSA0ARTAKE1SFX8JGXAY"
          },
          "statistics": {
            "opens": 123,
            "open_rate": 0.8253
          }
        }
      ]
    },
    "relationships": {
      "campaigns": {
        "data": [
          {
            "type": "campaign",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      }
    },
    "links": {
      "self": "string"
    }
  }
}

Each object in the results array returned in the response includes groupings (send channel and campaign ID) and their associated statistics (number of opens and open rate).

Flow values report

The example below uses the Query Flow Values endpoint to query statistics (clicks, unique clicks, and unique conversions) over a custom time frame:

curl --request POST \
     --url https://a.klaviyo.com/api/flow-values-reports/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-06-15 \
     --data '
{
  "data": {
    "type": "flow-values-report",
    "attributes": {
      "timeframe": {
        "start": "2024-05-08T00:00:00+00:00",
        "end": "2024-06-20T00:00:00+00:00"

      },
      "conversion_metric_id": "RESQ6t",
      "filter":"equals(flow_id,\"XVTP5Q\")",
      "statistics": [
        "clicks",
        "clicks_unique",
        "conversion_uniques"
      ]
    }
  }
}
'
{
  "data": {
    "type": "flow-values-report",
    "attributes": {
      "results": [
        {
          "groupings": {
            "flow_id": "XVTP5Q",
            "send_channel": "email",
            "flow_message_id": "01GMRWDSA0ARTAKE1SFX8JGXAY"
          },
          "statistics": {
            "clicks": 123,
            "clicks_unique": 98,
            "conversion_uniques": 3  
          }
        },
        {
          "groupings": {
            "flow_id": "XVTP5Q",
            "send_channel": "email",
            "flow_message_id": "01GJTHNWVG93F3KNX71SJ4FDBB"
          },
          "statistics": {
            "clicks": 342,
            "clicks_unique": 208,
            "conversion_uniques": 10 
          }
        }
      ]
    },
    "relationships": {
      "flows": {
        "data": [
          {
            "type": "flow",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "flow-messages": {
        "data": [
          {
            "type": "flow-message",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      }
    },
    "links": {
      "self": "string"
    }
  }
}

Flow series report

The example below uses the Query Flow Series endpoint to query statistics for clicks, delivery rate and open rate on a weekly interval over the last 30 days:

curl --request POST \
     --url https://a.klaviyo.com/api/flow-series-reports/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2024-06-15 \
     --data '
{
  "data": {
    "type": "flow-series-report",
    "attributes": {
      "timeframe": {
        "key": "last_30_days"
      },
      "interval": "weekly",
      "conversion_metric_id": "RESQ6t",
      "filter": "equals(flow_id,\"XVTP5Q\")",
      "statistics": [
        "clicks",
        "delivery_rate",
        "open_rate"
      ]
    }
  }
}
'
{
  "data": {
    "type": "flow-series-report",
    "attributes": {
      "results": [
        {
          "groupings": {
            "flow_id": "XVTP5Q",
            "send_channel": "email",
            "flow_message_id": "01GMRWDSA0ARTAKE1SFX8JGXAY"
          },
          "statistics": {
            "clicks": [
              123,
              156,
              144
            ],
      "delivery_rate": [
              1.00,
              0.56,
              0.84
            ],
            "open_rate": [
              0.8253,
              0.8722,
              0.8398
            ]
          }
        },
        {
          "groupings": {
            "flow_id": "XVTP5Q",
            "send_channel": "email",
            "flow_message_id": "01GJTHNWVG93F3KNX71SJ4FDBB"
          },
          "statistics": {
             "clicks": [
              123,
              156,
              144
            ],
      "delivery_rate": [
              1.00,
              0.56,
              0.84
            ],
            "open_rate": [
              0.8253,
              0.8722,
              0.8398
            ]
          }
        }
      ],
      "date_times": [
        "2024-01-05T00:00:00+00:00",
        "2024-01-06T00:00:00+00:00",
        "2024-01-07T00:00:00+00:00"
      ]
    },
    "relationships": {
      "flows": {
        "data": [
          {
            "type": "flow",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "flow-messages": {
        "data": [
          {
            "type": "flow-message",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      }
    },
    "links": {
      "self": "string"
    }
  }
}

Available statistics

📘

Conversion statistics are based on the conversion_metric_id provided in the request payload.

StatisticFormula
average_order_valueConversion value / Conversion
bounce_rate(Bounced emails + Bounced pushes) / (Received emails + Received pushes + Bounced emails + Bounced pushes)
bouncedEmail bounces + Push bounces
bounced_or_failedBounced emails + Failed SMS + Bounced pushes
bounced_or_failed_rate(Bounced emails + Failed SMS + Bounced pushes) / (Received emails + Received SMS + Received pushes + Bounced emails + Failed SMS + Bounced pushes)
click_rate(Unique email clicks + Unique SMS clicks) / (Received emails + Received SMS)
click_to_open_rateUnique email clicks / Unique email opens
clicksEmail clicks + SMS clicks
clicks_uniqueUnique email clicks + Unique SMS clicks
conversion_rateUnique conversions / (Received emails + Received SMS + Received pushes)
conversion_uniquesCount of unique conversions
conversion_valueCount of events for the provided conversion metric (e.g., the count of Placed Order events)
conversionsCount of conversions
deliveredReceived emails + Received SMS + Received pushes
delivery_rate(Received emails + Received SMS + Bounced pushes) / (Received emails + Received SMS + Received pushes + Bounced emails + Failed SMS + Bounced pushes)
failedFailed SMS
failed_rateFailed SMS / (Received SMS + Failed SMS)
open_rate(Unique email opens + Unique push opens) / (Received emails + Received push uniques)
opensEmail opens + Push opens
opens_uniqueUnique email opens + Unique push opens
recipientsReceived emails + Received SMS + Received pushes + Bounced emails + Failed SMS + Bounced pushes
revenue_per_recipientConversion value / (Received emails + Received SMS + Received pushes)
spam_complaint_rateEmail spam / Received emails
spam_complaintsCount of spam complaints
unsubscribe_rate(Unique email unsubscribes + Unique SMS unsubscribes) / (Received emails + Received SMS)
unsubscribe_uniquesCount of unique unsubscribes
unsubscribesCount of unsubscribes

Available time frames

📘

The available time frames below are relative to the time the user makes the call.

Time frameDescription
todayReturns same day data. Will respect the timezone of the account.
yesterdayReturns data from the day before. Will respect the timezone of the account.
this_weekReturns data from the current calendar week (Monday to Sunday).
last_7_daysReturns data from the past 7 days (including the day the user makes the call).
last_weekReturns data from the previous calendar week (Monday to Sunday).
this_monthReturns data from the current month.
last_30_daysReturns data from the last 30 days regardless of month.
last_monthReturns data from the previous calendar month.
last_90_daysReturns data from the last 90 days regardless of month.
last_3_monthsReturns data from the 3 previous months, (including the month the user makes the call).
last_365_daysReturns data from the last 365 days regardless of year.
last_12 monthsReturns data from the 12 previous months, (including the month the user makes the call).
this_yearReturns all data from the current calendar year.
last_yearReturns all data from the previous calendar year.