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:
  - key
    A predefined key that represents a set time frame (see Available time frames).
- 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.

Statistic	Formula
`average_order_value`	Conversion value / Conversion
`bounce_rate`	(Bounced emails + Bounced pushes) / (Received emails + Received pushes + Bounced emails + Bounced pushes)
`bounced`	Email bounces + Push bounces
`bounced_or_failed`	Bounced 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_rate`	Unique email clicks / Unique email opens
`clicks`	Email clicks + SMS clicks
`clicks_unique`	Unique email clicks + Unique SMS clicks
`conversion_rate`	Unique conversions / (Received emails + Received SMS + Received pushes)
`conversion_uniques`	Count of unique conversions
`conversion_value`	Count of events for the provided conversion metric (e.g., the count of Placed Order events)
`conversions`	Count of conversions
`delivered`	Received 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)
`failed`	Failed SMS
`failed_rate`	Failed SMS / (Received SMS + Failed SMS)
`open_rate`	(Unique email opens + Unique push opens) / (Received emails + Received push uniques)
`opens`	Email opens + Push opens
`opens_unique`	Unique email opens + Unique push opens
`recipients`	Received emails + Received SMS + Received pushes + Bounced emails + Failed SMS + Bounced pushes
`revenue_per_recipient`	Conversion value / (Received emails + Received SMS + Received pushes)
`spam_complaint_rate`	Email spam / Received emails
`spam_complaints`	Count of spam complaints
`unsubscribe_rate`	(Unique email unsubscribes + Unique SMS unsubscribes) / (Received emails + Received SMS)
`unsubscribe_uniques`	Count of unique unsubscribes
`unsubscribes`	Count of unsubscribes

Available time frames

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

Time frame	Description
`today`	Returns same day data. Will respect the timezone of the account.
`yesterday`	Returns data from the day before. Will respect the timezone of the account.
`this_week`	Returns data from the current calendar week (Monday to Sunday).
`last_7_days`	Returns data from the past 7 days (including the day the user makes the call).
`last_week`	Returns data from the previous calendar week (Monday to Sunday).
`this_month`	Returns data from the current month.
`last_30_days`	Returns data from the last 30 days regardless of month.
`last_month`	Returns data from the previous calendar month.
`last_90_days`	Returns data from the last 90 days regardless of month.
`last_3_months`	Returns data from the 3 previous months, (including the month the user makes the call).
`last_365_days`	Returns data from the last 365 days regardless of year.
`last_12 months`	Returns data from the 12 previous months, (including the month the user makes the call).
`this_year`	Returns all data from the current calendar year.
`last_year`	Returns all data from the previous calendar year.