> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Klaviyo data source in Adriel.

## Introduction

Klaviyo is a marketing-automation platform built for e-commerce, focused on email and SMS campaigns with deep e-commerce attribution. Its data model centers on Lists and Segments (audience definitions), Flows (event-triggered automations), Campaigns (one-off sends), and Forms (on-site sign-up captures). Klaviyo records every customer interaction as a metric — placed orders, viewed products, started checkout, opened email — which powers both segmentation and reporting.

This data source is the metric-aggregate variant. It queries Klaviyo's metric-aggregates endpoint live and can report any event metric in the account, broken down by event property. Because it aggregates by the time each event occurred, it is best for flexible cross-metric analysis — comparing engagement and revenue events alongside paid-media spend — rather than reproducing Klaviyo's in-app campaign and flow reports. For send-date-aligned campaign, flow, and form reporting that matches Klaviyo's UI, use the separate [Klaviyo Reporting data reference](/data-sources/g-n/klaviyo-reporting/data-reference).

As an email-marketing connector, engagement and revenue metrics are standardized so widgets can aggregate alongside ad-platform sources without additional configuration.

To connect this data source, see [How to connect Klaviyo to Adriel](/data-sources/g-n/klaviyo/how-to-connect).

## Data refresh strategy

### Architecture data

Catalogs of lists, segments, flows, campaigns, and forms are fetched on demand when a dashboard loads. There is no daily architecture sync — entities created in Klaviyo become available immediately.

### Reports data

Report data is read from Klaviyo's metric-aggregates endpoint on demand on every dashboard load, so send, open, click, and conversion counts always reflect the current state in Klaviyo. There is no daily cache.

**Event-time attribution.** Dates are filtered and grouped by the time each event occurred, not by the campaign or flow send date. An email sent before the selected date range can therefore contribute to results inside the range if its opens, clicks, or conversions land there. This differs from Klaviyo's in-app reports, which are calculated on send date, so totals may not match. For send-date-aligned figures, use the [Klaviyo Reporting data reference](/data-sources/g-n/klaviyo-reporting/data-reference).

## Architecture levels

Account → List / Segment → Flow / Campaign / Form → Message → Event

* **Account** — a single Klaviyo account authorized via a private API key.
* **List / Segment** — a list is an explicit subscriber group; a segment is a dynamic, rule-based audience.
* **Flow / Campaign / Form** — a flow is an automated, event-triggered series; a campaign is a single send; a form is an on-site sign-up capture.
* **Message** — an individual email or SMS within a flow or campaign.
* **Event** — a single recipient action (opened, clicked, placed order, started checkout, and so on).

## Date range limits

The connector fetches a maximum of **1 year** of data per query; requests for a wider range are truncated to the most recent year. When a query includes no date breakdown, results are aggregated at a **monthly** interval by default.

## Metrics

<Note>
  **How to read the columns**
  **Data type** uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
  **API Key** in code style like `klaviyo:Opened Email` is the connector's field name for a Klaviyo event metric (event metric names carry the `klaviyo:` prefix). *Italic text* describes how a value is produced when it doesn't map cleanly to a single event metric.
</Note>

<Note>
  **Metrics are built from the account's metric catalog.** This variant can report any metric Klaviyo tracks for the account, and each metric is available in three aggregations — **count** (total events), **unique** (distinct profiles), and **value** (monetary total, for metrics that carry a value such as Placed Order). The metrics below are common examples; the exact catalog varies by account.
</Note>

### Email & SMS engagement

| Metric               | Description                                                               | Data type  | API Key                        |
| -------------------- | ------------------------------------------------------------------------- | ---------- | ------------------------------ |
| Received Email       | Emails delivered to recipients.                                           | Number     | `klaviyo:Received Email`       |
| Opened Email         | Email opens (count aggregation) or distinct openers (unique aggregation). | Number     | `klaviyo:Opened Email`         |
| Clicked Email        | Email link clicks, total or distinct.                                     | Number     | `klaviyo:Clicked Email`        |
| Bounced Email        | Emails that bounced.                                                      | Number     | `klaviyo:Bounced Email`        |
| Marked Email as Spam | Recipients who reported the email as spam.                                | Number     | `klaviyo:Marked Email as Spam` |
| Unsubscribed         | Unsubscribe events.                                                       | Number     | `klaviyo:Unsubscribed`         |
| Received SMS         | SMS messages delivered.                                                   | Number     | `klaviyo:Received SMS`         |
| Clicked SMS          | SMS link clicks.                                                          | Number     | `klaviyo:Clicked SMS`          |
| Open rate            | Unique opens divided by deliveries.                                       | Percentage | *Adriel-computed*              |
| Click rate           | Unique clicks divided by deliveries.                                      | Percentage | *Adriel-computed*              |

### Revenue & conversions

| Metric                | Description                                                                     | Data type | API Key                                    |
| --------------------- | ------------------------------------------------------------------------------- | --------- | ------------------------------------------ |
| Placed Order          | Purchase-conversion events.                                                     | Number    | `klaviyo:Placed Order`                     |
| Ordered Product       | Product-level order events.                                                     | Number    | `klaviyo:Ordered Product`                  |
| Started Checkout      | Checkout-start events.                                                          | Number    | `klaviyo:Started Checkout`                 |
| Conversion value      | Revenue from the value aggregation of a conversion metric such as Placed Order. | Currency  | *value aggregation of a conversion metric* |
| Revenue per recipient | Conversion value divided by recipients.                                         | Currency  | *Adriel-computed*                          |

### Contacts & sign-ups

| Metric             | Description               | Data type | API Key                      |
| ------------------ | ------------------------- | --------- | ---------------------------- |
| Viewed Product     | Product-page view events. | Number    | `klaviyo:Viewed Product`     |
| Active on Site     | On-site activity events.  | Number    | `klaviyo:Active on Site`     |
| Subscribed to List | List subscription events. | Number    | `klaviyo:Subscribed to List` |
| Viewed Form        | Sign-up form views.       | Number    | `klaviyo:Viewed Form`        |
| Submitted Form     | Sign-up form submissions. | Number    | `klaviyo:Submitted Form`     |

## Breakdowns

<Note>
  When a record has no value for the chosen breakdown property, it appears under the bucket `Unassigned` rather than being excluded. Date breakdowns default to a monthly interval when no other date grouping is applied.
</Note>

### Campaigns & flows

| Breakdown          | Description                                                   | API Key                       |
| ------------------ | ------------------------------------------------------------- | ----------------------------- |
| Flow               | The flow that generated the event.                            | `klaviyo:$flow`               |
| Attributed flow    | The flow credited with an attributed event.                   | `klaviyo:$attributed_flow`    |
| Attributed channel | The channel (email or SMS) credited with an attributed event. | `klaviyo:$attributed_channel` |
| Campaign channel   | The channel of the originating campaign.                      | `klaviyo:$campaign_channel`   |
| Flow channel       | The channel of the originating flow.                          | `klaviyo:$flow_channel`       |
| Campaign name      | The campaign that generated the event.                        | `klaviyo:Campaign Name`       |

### Messages & variations

| Breakdown             | Description                                      | API Key                          |
| --------------------- | ------------------------------------------------ | -------------------------------- |
| Message               | The message that generated the event.            | `klaviyo:$message`               |
| Attributed message    | The message credited with an attributed event.   | `klaviyo:$attributed_message`    |
| Message name          | The message name.                                | `klaviyo:Message Name`           |
| Message type          | The message type.                                | `klaviyo:Message Type`           |
| Variation             | The message variation.                           | `klaviyo:$variation`             |
| Attributed variation  | The variation credited with an attributed event. | `klaviyo:$attributed_variation`  |
| Message send cohort   | The send cohort of the message.                  | `klaviyo:$message_send_cohort`   |
| Variation send cohort | The send cohort of the variation.                | `klaviyo:$variation_send_cohort` |
| Subject               | The email subject line.                          | `klaviyo:Subject`                |

### Contacts & audience

| Breakdown | Description                                 | API Key           |
| --------- | ------------------------------------------- | ----------------- |
| List      | The list associated with the event.         | `klaviyo:List`    |
| Form      | The sign-up form associated with the event. | `klaviyo:form_id` |

### Delivery & engagement

| Breakdown        | Description                       | API Key                    |
| ---------------- | --------------------------------- | -------------------------- |
| Bounce type      | The type of bounce recorded.      | `klaviyo:Bounce Type`      |
| Failure source   | The source of a send failure.     | `klaviyo:Failure Source`   |
| Failure type     | The type of send failure.         | `klaviyo:Failure Type`     |
| Method           | The send method.                  | `klaviyo:Method`           |
| Client canonical | The canonical mail or SMS client. | `klaviyo:Client Canonical` |
| Client name      | The mail or SMS client name.      | `klaviyo:Client Name`      |
| Client type      | The mail or SMS client type.      | `klaviyo:Client Type`      |
| Email domain     | The recipient's email domain.     | `klaviyo:Email Domain`     |
| URL              | The clicked URL.                  | `klaviyo:URL`              |

### SMS

| Breakdown         | Description                         | API Key                     |
| ----------------- | ----------------------------------- | --------------------------- |
| From number       | The sending phone number.           | `klaviyo:From Number`       |
| From phone region | The region of the sending number.   | `klaviyo:From Phone Region` |
| To number         | The recipient phone number.         | `klaviyo:To Number`         |
| To phone region   | The region of the recipient number. | `klaviyo:To Phone Region`   |

### Time

<Note>
  These groupings are provided by Adriel rather than returned as Klaviyo event properties.
</Note>

| Breakdown | Description                                                                  |
| --------- | ---------------------------------------------------------------------------- |
| Daily     | Split reports by day.                                                        |
| Weekly    | Split reports by week.                                                       |
| Monthly   | Split reports by calendar month (the default when no date breakdown is set). |

## Limitations

* **Event-time attribution, not send date** — dates are grouped by when each event occurred, so totals may not match Klaviyo's in-app campaign and flow reports, which use send date. Use the [Klaviyo Reporting data reference](/data-sources/g-n/klaviyo-reporting/data-reference) for send-date-aligned figures.
* **1-year query window** — a single query fetches at most one year of data; wider ranges are truncated to the most recent year.
* **Account-specific metric catalog** — available metrics come from the account's own Klaviyo metric catalog, each in count, unique, and value aggregations. Metrics not tracked in the account are not available.
* **Empty breakdown values bucket as "Unassigned"** — records with no value for the selected property are grouped under `Unassigned` rather than dropped.
* **Rate limits may slow first render** — metric-aggregate requests are throttled to 1 request per 500 ms shared across all accounts, with up to 10 sub-queries per request; a single page of results is returned per sub-query, so very large dashboards can take longer to render the first time.
* **No token refresh** — authentication uses a private API key with no OAuth or refresh flow; if the key is revoked in Klaviyo, subsequent reads fail until it is replaced.

## API references

* [Klaviyo Query Metric Aggregates](https://developers.klaviyo.com/en/reference/query_metric_aggregates)
* [Klaviyo Get Metrics](https://developers.klaviyo.com/en/reference/get_metrics)
* [Klaviyo API overview and versioning](https://developers.klaviyo.com/en/reference/api_overview)
* [Klaviyo rate limits and error handling](https://developers.klaviyo.com/en/docs/rate_limits_and_error_handling)

## See also

* [How to connect Klaviyo to Adriel](/data-sources/g-n/klaviyo/how-to-connect) (paired how-to)
* [Klaviyo Reporting data reference](/data-sources/g-n/klaviyo-reporting/data-reference) — send-date-aligned form, flow, and campaign reporting that matches Klaviyo's UI
* [Mailchimp data reference](/data-sources/g-n/mailchimp/data-reference) — alternative email-marketing platform with a simpler list/campaign model