Metrics API Overview

The Metrics API is used for historical event data in Klaviyo. This API is organized around REST. The API endpoints were designed to be predictable and resource-oriented and use HTTP response codes to indicate API errors. This means a single resource or endpoint can and often does provide different functionality based on the HTTP verb used to access it. JSON is returned in all responses from the API, including errors.

Libraries

We are working on adding the Metrics API to our existing libraries. If you want to be notified when those libraries have been updated you can watch the following repositories:

Python (https://github.com/klaviyo/python-klaviyo)
Ruby (https://github.com/klaviyo/ruby-klaviyo)
PHP (https://github.com/klaviyo/php-klaviyo)

API Endpoint

https://a.klaviyo.com

Summary of Resource URL Patterns

  • /api/v1/metrics
  • /api/v1/metrics/timeline
  • /api/v1/metric/{METRIC_ID}/timeline
  • /api/v1/metric/{METRIC_ID}/export

Authentication

You authenticate to the Metrics API by providing one of your private API keys as part of each request. You can manage your private API keys from your account. We allow you to have multiple API keys at once in case you need more than one.

Authentication happens via the api_key parameter in each request. It can be sent as part of the GET or POST parameters.

Klaviyo's API is served over HTTPS and all requests must be authenticated.

Your Private API key

To view your API key, you need to log in.

Errors

Our API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error from information provided as part of the request (e.g. the requested object doesn't exist, an invalid setting, etc.), and codes in the 5xx range indicate an error on Klaviyo's end.

The response of all API errors contain a message parameter which has developer-facing information about why the request failed.

HTTP Status Code Summary

  • 200 OK - The request completed successfully.
  • 400 Bad request - Request is missing or has a bad parameter.
  • 400 Not Authorized - Request is missing or has an invalid API key.
  • 404 Not Found - The requested resource doesn't exist.
  • 500 Server errors - Something is wrong on Klaviyo's end.

Versioning

When we make backwards incompatible changes to the API, we release new API versions, which are reflected in the API endpoints. The current version, v1, is the first version. In the future, if we switch to v2, we will provide documentation on the changes as well as new documentation detailing how to use the new API.

Metrics API

Listing metrics

Returns a list of all the metrics in Klaviyo.

Arguments
page
optional, integer, defaults to 0
For pagination, which page of results to return.
count
optional, integer, defaults to 50
For pagination, the number of results to return. The maximum number is 100.
Response

A dictionary with a data property that contains an array of all the metrics. Each entry is a separate metric object. If no metrics exist, the resulting array will be empty. This request should never return an error.

GET https://a.klaviyo.com/api/v1/metrics curl https://a.klaviyo.com/api/v1/metrics -G \ -d api_key=API_KEY { "end": 1, "object": "$list", "page_size": 50, "start": 0, "total": 2, "data": [ { "updated": "2014-11-03 17:28:09", "name": "Active on Site", "created": "2014-11-03 17:28:09", "object": "metric", "id": "3vtCwa", "integration": { "category": "API", "object": "integration", "id": "4qYGmQ", "name": "API" } }, { "updated": "2014-11-03 20:54:40", "name": "Added integration", "created": "2014-11-03 20:54:40", "object": "metric", "id": "8qYK7L", "integration": { "category": "API", "object": "integration", "id": "4qYGmQ", "name": "API" } ] }

Listing the complete event timeline

Returns a batched timeline of all events in your Klaviyo account.

Arguments
since
optional, string or integer
Either a Unix timestamp (UTC) to use as starting datetime, OR a UUID obtained from the next attribute of a prior API call. Defaults to current time.
count
optional, integer, defaults to 100
Number of events to return in a batch.
sort
optional, string, 'asc' or 'desc', defaults to 'desc'
Sort order to apply to timeline.
Response

A dictionary containing a list of metric event objects. Each event object contains information about what metric the event tracks, which person the event is related to, and any extra properties about the event. The next attribute should be passed as the since parameter to subsequent API calls to fetch the next batch of events.

GET https://a.klaviyo.com/api/v1/metrics/timeline curl https://a.klaviyo.com/api/v1/metrics/timeline -G \ -d api_key=API_KEY { "count": 1, "object": "$list", "data": [ { "object": "event", "id": "3EJ9cW", "person": { "id": "5ta2Hr", "$first_name": "George", "$last_name": "Washington", "$email": "george.washington@example.com", }, "event_name": "Placed Order", "statistic_id": "4Q8Y6N", "timestamp": "1400656845", "next": "31268980-edcb-11e3-8001-5b3d8e19a1ac", "event_properties": { "$extra": { "TotalTax": 0, "TotalDiscount": 0, "TotalShipping": 6, "Items": [ { "Description": null, "Price": 29, "Slug": "woodtooth", "Quantity": 1, "LineTotal": 29, "ProductID": "537c06c610bcf70400540c81", "Name": "Wooden Tooth" } ] }, "$value": 35, "IsDiscounted": false, "UsedCoupon": false } ] }

Listing the event timeline for a particular metric

Returns a batched timeline for one specific type of metric.

Arguments
since
optional, string or integer
Either a Unix timestamp (UTC) to use as starting datetime, OR a UUID obtained from the next attribute of a prior API call. Defaults to current time.
count
optional, integer, defaults to 100
Number of events to return in a batch.
sort
optional, string, 'asc' or 'desc', defaults to 'desc'
Sort order to apply to timeline.
Response

A dictionary containing a list of metric event objects. Each event object contains information about what metric the event tracks, which person the event is related to, and any extra properties about the event. The next attribute should be passed as the since parameter to subsequent API calls to fetch the next batch of events.

GET https://a.klaviyo.com/api/v1/metric/{{METRIC_ID}}/timeline curl https://a.klaviyo.com/api/v1/metric/4Q8Y6N/timeline -G \ -d api_key=API_KEY { "count": 1, "object": "$list", "data": [ { "object": "event", "id": "3EJ9cW", "person": { "id": "5ta2Hr", "$first_name": "George", "$last_name": "Washington", "$email": "george.washington@example.com", }, "event_name": "Placed Order", "statistic_id": "4Q8Y6N", "timestamp": "1400656845", "next": "31268980-edcb-11e3-8001-5b3d8e19a1ac", "event_properties": { "$extra": { "TotalTax": 0, "TotalDiscount": 0, "TotalShipping": 6, "Items": [ { "Description": null, "Price": 29, "Slug": "woodtooth", "Quantity": 1, "LineTotal": 29, "ProductID": "537c06c610bcf70400540c81", "Name": "Wooden Tooth" } ] }, "$value": 35, "IsDiscounted": false, "UsedCoupon": false } ] }

Exporting metric data

Export event data from Klaviyo, optionally filtering and segmented on available event properties. To ensure a correct response, enter parameters in the curl request as they are ordered below:

start_date
optional, string
Beginning of timeframe to pull event data for. The default value is 1 month ago.
end_date
optional, string
End of timeframe to pull event data for. The default is the current day
unit
optional, string
Granularity to bucket data points into - one of ‘day’, ‘week’, or ‘month’. Defaults to ‘day’.
measurement
optional, string or JSON-encoded list
Type of metric to fetch - one of ‘unique’, ‘count’, ‘value’, or ‘sum’. Defaults to ‘count’. For 'sum' a property name to operate on must be supplied as a JSON-encoded list like '["sum","ItemCount"]'
where
optional, JSON-encoded list
Conditions to use to filter the set of events. A max of 1 condition can be given. Where and by parameters cannot be specified at the same time.
by
optional, string
The name of a property to segment the event data on. Where and by parameters cannot be specified at the same time.
count
optional, integer
Maximum number of segments to return. The default value is 25.
Response

A dictionary relecting the input request parameters as well as a results property that contains a list of dictionaries - one per segment of the result set. Within each of those dictionaries is the name of the segment as well as a data property that is a list of the data points for that segment.

GET https://a.klaviyo.com/api/v1/metric/{{METRIC_ID}}/export curl https://a.klaviyo.com/api/v1/metric/8pg9Ab/export -G \ -d api_key=API_KEY \ -d start_date=2015-01-01 \ -d end_date=2015-01-31 \ -d unit='week' \ -d where='[["ItemCount","=",5]]' curl https://a.klaviyo.com/api/v1/metric/8pg9Ab/export -G \ -d api_key=API_KEY \ -d start_date=2015-01-01 \ -d end_date=2015-01-31 \ -d unit='week' \ --data-urlencode by='Accepts Marketing' { "metric": { "updated": "2015-02-12 18:51:41", "name": "Placed Order", "created": "2015-02-12 18:02:34", "object": "metric", "id": "8pg9Ab", "integration": { "category": "eCommerce", "object": "integration", "id": "9NgkTh", "name": "Shopify" } }, "end_date": "2015-01-31 00:00:00", "measurement": "c", "where": "", "start_date": "2015-01-01 00:00:00", "unit": "weekly", "by": "Accepts Marketing", "results": [ { "segment": "False", "data": [ { "date": "2015-01-05 00:00:00", "values": [ 5 ] }, { "date": "2015-01-26 00:00:00", "values": [ 2 ] } ] }, { "segment": "True", "data": [ { "date": "2015-01-05 00:00:00", "values": [ 1 ] } ] } ] }