Metrics API overview

Before you begin

Check out our general API overview to make sure you’re ready to get started with specific endpoints.

Our Metrics API enables a zoomed out view of your metric data so that you can dive deeper into your business’s performance with Klaviyo. A metric is a category of event, or action a person can take. For example, when a customer places an order, a Placed Order event is created for the profile, that event being an instance of the Placed Order metric. All Placed Order events collected or sent via the same mechanism (a given integration or our APIs) will share the same Placed Order metric represented by its metric_id.

The Metrics API allows you to fetch metric information, including a given metric’s metric_id, which can then be used to query aggregate metric data. These metrics include:

• Native Klaviyo metrics.
• Other integration-specific (e.g., Shopify) metrics.
• Custom metrics.

Use cases

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

• Retrieve a metric’s ID (metric_id) and use it to query and aggregate event data associated with the metric.
• Filter metrics by integration name and/or category, e.g., Shopify-created metrics.
• Query aggregate event data associated with a metric by passing a JSON request body with metric attributes and filters (e.g., aggregate Placed Order events that span over a holiday weekend).

Data model

A retrieved metric will have the following:

• id

  The metric id.

• name

  The metric name, e.g, Opened Email.

• created

  The timestamp of when the metric was created.

• updated

  The timestamp of when the metric was last updated.

• integration

  The integration object used to capture the metric, e.g., Klaviyo.

  • id

    The integration ID.

  • name

    The name of the integration, e.g., Klaviyo.

  • category

    The category of the integration, e.g., Internal for Klaviyo.

Get Metrics

The Get Metrics endpoint is useful for retrieving information about multiple metrics on your account, including their names, IDs, and the integrations used to capture them. Similarly, the Get Metric endpoint is useful for fetching the same information about a single metric at a time.

You can use sparse fieldsets to only show the desired fields in your response. See the example request to Get Metrics below:

curl --request GET \
     --url 'https://a.klaviyo.com/api/metrics/?filter=equals(integration.name,"Klaviyo")&fields[metric]=name,integration.id,integration.name' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2023-10-15'

{
    "data": [
        {
            "type": "metric",
            "id": "REcTBe",
            "attributes": {
                "name": "Sent SMS",
                "integration": {
                    "id": "0rG4eQ",
                    "name": "Klaviyo"
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/metrics/REcTBe/"
            }
        },
        {
            "type": "metric",
            "id": "RcsmFp",
            "attributes": {
                "name": "Marked Email as Spam",
                "integration": {
                    "id": "0rG4eQ",
                    "name": "Klaviyo"
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/metrics/RcsmFp/"
            }
        },
    ...
}

Note that an equals filter, ?filter=equals(integration.name,"Klaviyo"), has been applied to only include native Klaviyo metrics in the response. Sparse fieldsets are also used to only display the metric’s name, integration.id, and integration.name.

Query metrics

The Metrics API allows for filtering and including certain metric data, such as filtering by native Klaviyo metrics like Opened Email or Clicked Email. Check out the supported query parameters below and test them out with our latest Postman collection. Note that support for given operators and fields is endpoint-specific. Review the API reference documentation for more information on allowed fields and query operators.

🚧

Filtering by integration.name and/or integration.category is case-sensitive. The integration.name should identically match the brand name of the integration it references. See the table below for acceptable values.

Query Metric Aggregates

🚧

When using the Query Metric Aggregates endpoint to export data, the dates you filter and group by are determined by the time the event occurred, not the send date of the campaign or flow. This differs from the performance data shown in Klaviyo's UI, which is calculated by send date. For campaign and flow performance data as displayed in the app, we recommend using the Reporting API.

The Query Metrics Aggregates endpoint is useful for pulling aggregated metric data out of Klaviyo and creating your own custom reports. For example, if you wanted to directly retrieve a count of how many orders had been placed on a monthly basis for the past year, you can make a query for a Placed Order metric:

curl --request POST \
     --url https://a.klaviyo.com/api/metric-aggregates/ \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: 2023-10-15' \
     --data '
{
  "data": {
    "type": "metric-aggregate",
    "attributes": {
      "measurements": ["count"],
      "filter": [
          "greater-or-equal(datetime,2023-01-01T00:00:00Z)",
          "less-than(datetime,2024-01-01T00:00:00Z)"
      ],
      "metric_id": "XWKwsS",
      "interval": "month",
      "page_size": 500,
      "timezone": "UTC"
    }
  }
}
'

Our Query Metrics Aggregates endpoint offers robust support for filtering results and grouping by time, event, or profile. Some use cases include:

• Extracting email engagement or ecommerce event data from Klaviyo to send to a data warehouse (e.g., syncing event data to Snowflake).
• Analyzing a count of SMS events by timezone.
• Reviewing Clicked Email events to compare engagement between different email versions sent out for A/B testing.

For a comprehensive list of native Klaviyo metrics and their associated attributes for grouping and filtering, refer to the list of supported attributes.

Next steps

Try out the following:

• Retrieve a metric_id from a call to Get Metrics with your Klaviyo test account via Postman.
• Use the Create Event endpoint to create events for this metric over a period of time.
• Use the retrieved metric_id to make a call to the Query Metric Aggregates endpoint. Try out the endpoint with native Klaviyo metrics and/or other integrations.

Additional resources

• Use the Query Metric Aggregates endpoint
• Export data from Klaviyo
• Supported attributes (for filtering and grouping with the Query Metric Aggregates endpoint)