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.
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)
https://a.klaviyo.com
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.
To view your API key, you need to log in.
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.
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.
Returns a list of all the metrics in Klaviyo.
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"
}
]
}
Returns a batched timeline of all events in your Klaviyo account.
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
}
]
}
Returns a batched timeline for one specific type of metric.
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
}
]
}
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:
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 ]
}
]
}
]
}