Sorting
Learn how to use our JSON:API sorting feature.
Sort syntax
Klaviyo’s JSON:API sorting syntax can be used across all supported endpoints in our new APIs. Please note that support for given fields is unique to each endpoint. Refer to the sort query parameter in the API reference documentation.
For endpoints that support sort operations, you can set sort to a field name in the response body such as datetime, for example. The sorting direction can be ascending (default) or descending.
The following example shows how to retrieve a sorted list of events by datetime in ascending order (oldest to newest):
curl --request GET \
--url 'https://a.klaviyo.com/api/events/?sort=datetime' \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-07-15'
{
"data": [
{
"type": "event",
"id": "4sDShKQjrdT",
"attributes": {
"timestamp": 1690229757,
"event_properties": {
"Carrier Delivery Status": "delivered",
"extra": {
"Message Body": "Klaviyo Sample Data: This is an example SMS received message body.",
"Message ID": "01H64RPNNC42DZNR9EHDGPWTSH"
},
"From Number": "+15005550006",
"From Phone Region": "US",
"Message Format": "SMS",
"Message Name": "Internal Klaviyo - Test Campaign Name",
"Message Type": "campaign",
"Segment Count": 1,
"To Number": "55896",
"To Phone Region": "US",
"$event_id": "sample_data_gen:1665417e-c31a-42dd-a444-04d5edb48b3e"
},
"datetime": "2023-07-24 20:15:57+00:00",
"uuid": "e60d7c80-2a5e-11ee-8001-c1ee7c948be0"
},
"relationships": {
"profile": {
"data": {
"type": "profile",
"id": "01H64RPM2KR4VDGBWQHFVT6032"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4sDShKQjrdT/relationships/profile/",
"related": "https://a.klaviyo.com/api/events/4sDShKQjrdT/profile/"
}
},
"metric": {
"data": {
"type": "metric",
"id": "WwY7Gb"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4sDShKQjrdT/relationships/metric/",
"related": "https://a.klaviyo.com/api/events/4sDShKQjrdT/metric/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/4sDShKQjrdT/"
}
},
{
"type": "event",
"id": "4vGfpcpPRGL",
"attributes": {
"timestamp": 1692028246,
"event_properties": {
"custom_value": "newer event time value",
"$event_id": "YjpZcE"
},
"datetime": "2023-08-14 15:50:46+00:00",
"uuid": "55084f00-3aba-11ee-8001-a3e96a3d92dc"
},
"relationships": {
"profile": {
"data": {
"type": "profile",
"id": "01H7TBW70G8RYXHF9D91K4W72J"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/relationships/profile/",
"related": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/profile/"
}
},
"metric": {
"data": {
"type": "metric",
"id": "TQpx2b"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/relationships/metric/",
"related": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/metric/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/"
}
}
],
"links": {
"self": "https://a.klaviyo.com/api/events/?sort=datetime",
"next": null,
"prev": null
}
}
You can retrieve events by datetime in descending order (newest to oldest) by using a - prefix as shown below:
curl --request GET \
--url 'https://a.klaviyo.com/api/events/?filter=profile&sort=-datetime' \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-07-15'
{
"data": [
{
"type": "event",
"id": "4vGfpcpPRGL",
"attributes": {
"timestamp": 1692028246,
"event_properties": {
"custom_value": "newer event time value",
"$event_id": "YjpZcE"
},
"datetime": "2023-08-14 15:50:46+00:00",
"uuid": "55084f00-3aba-11ee-8001-a3e96a3d92dc"
},
"relationships": {
"profile": {
"data": {
"type": "profile",
"id": "01H7TBW70G8RYXHF9D91K4W72J"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/relationships/profile/",
"related": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/profile/"
}
},
"metric": {
"data": {
"type": "metric",
"id": "TQpx2b"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/relationships/metric/",
"related": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/metric/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/"
}
},
{
"type": "event",
"id": "4sDShKQjrdT",
"attributes": {
"timestamp": 1690229757,
"event_properties": {
"Carrier Delivery Status": "delivered",
"extra": {
"Message Body": "Klaviyo Sample Data: This is an example SMS received message body.",
"Message ID": "01H64RPNNC42DZNR9EHDGPWTSH"
},
"From Number": "+15005550006",
"From Phone Region": "US",
"Message Format": "SMS",
"Message Name": "Internal Klaviyo - Test Campaign Name",
"Message Type": "campaign",
"Segment Count": 1,
"To Number": "55896",
"To Phone Region": "US",
"$event_id": "sample_data_gen:1665417e-c31a-42dd-a444-04d5edb48b3e"
},
"datetime": "2023-07-24 20:15:57+00:00",
"uuid": "e60d7c80-2a5e-11ee-8001-c1ee7c948be0"
},
"relationships": {
"profile": {
"data": {
"type": "profile",
"id": "01H64RPM2KR4VDGBWQHFVT6032"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4sDShKQjrdT/relationships/profile/",
"related": "https://a.klaviyo.com/api/events/4sDShKQjrdT/profile/"
}
},
"metric": {
"data": {
"type": "metric",
"id": "WwY7Gb"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4sDShKQjrdT/relationships/metric/",
"related": "https://a.klaviyo.com/api/events/4sDShKQjrdT/metric/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/4sDShKQjrdT/"
}
}
],
"links": {
"self": "https://a.klaviyo.com/api/events/?sort=-datetime",
"next": null,
"prev": null
}
}
Example request and response
In the following example, we make a request to get email campaigns and sort them in descending order (oldest to newest) with the created_at field:
curl --request GET \
--url 'https://a.klaviyo.com/api/campaigns/?filter=equals(messages.channel,’email’)&sort=created_at' \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-07-15'
{
"data": [
{
"type": "campaign",
"id": "01H64RPN6K46BFY3G87KB742ZK",
"attributes": {
"name": "Internal Klaviyo - Test Campaign Name",
"status": "Sent",
"archived": false,
"audiences": {
"included": [
"VKT4tu"
],
"excluded": []
},
"send_options": {
"use_smart_sending": false,
"ignore_unsubscribes": false
},
"tracking_options": {
"is_add_utm": false,
"utm_params": [],
"is_tracking_clicks": true,
"is_tracking_opens": true
},
"send_strategy": {
"method": "immediate",
"options_static": null,
"options_throttled": null,
"options_sto": null
},
"created_at": "2023-07-24T20:15:57.149220+00:00",
"scheduled_at": null,
"updated_at": "2023-07-24T20:15:57.149249+00:00",
"send_time": null
},
"relationships": {
"campaign-messages": {
"data": [
{
"type": "campaign-message",
"id": "01H64RPN72SBJ2MC2BYCZ23QMY"
}
],
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H64RPN6K46BFY3G87KB742ZK/relationships/campaign-messages/",
"related": "https://a.klaviyo.com/api/campaigns/01H64RPN6K46BFY3G87KB742ZK/campaign-messages/"
}
},
"tags": {
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H64RPN6K46BFY3G87KB742ZK/relationships/tags/",
"related": "https://a.klaviyo.com/api/campaigns/01H64RPN6K46BFY3G87KB742ZK/tags/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H64RPN6K46BFY3G87KB742ZK/"
}
},
{
"type": "campaign",
"id": "01H7AZ0HEP1E6J65B0M0AM5N7D",
"attributes": {
"name": "August 8 Test Campaign",
"status": "Draft",
"archived": false,
"audiences": {
"included": [
"Seu3Hc"
],
"excluded": []
},
"send_options": {
"use_smart_sending": false,
"ignore_unsubscribes": false
},
"tracking_options": {
"is_add_utm": false,
"utm_params": [],
"is_tracking_clicks": true,
"is_tracking_opens": true
},
"send_strategy": {
"method": "static",
"options_static": {
"datetime": "2023-08-08T04:00:00+00:00",
"is_local": false,
"send_past_recipients_immediately": null
},
"options_throttled": null,
"options_sto": null
},
"created_at": "2023-08-08T16:17:20.863711+00:00",
"scheduled_at": null,
"updated_at": "2023-08-08T16:19:53.275045+00:00",
"send_time": null
},
"relationships": {
"campaign-messages": {
"data": [
{
"type": "campaign-message",
"id": "01H7AZ0HF35HBTCAQXNR55TKTT"
}
],
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H7AZ0HEP1E6J65B0M0AM5N7D/relationships/campaign-messages/",
"related": "https://a.klaviyo.com/api/campaigns/01H7AZ0HEP1E6J65B0M0AM5N7D/campaign-messages/"
}
},
"tags": {
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H7AZ0HEP1E6J65B0M0AM5N7D/relationships/tags/",
"related": "https://a.klaviyo.com/api/campaigns/01H7AZ0HEP1E6J65B0M0AM5N7D/tags/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/campaigns/01H7AZ0HEP1E6J65B0M0AM5N7D/"
}
}
],
"links": {
"self": "https://a.klaviyo.com/api/campaigns/?filter=equals(messages.channel,%27email%27)&sort=created_at",
"next": null,
"prev": null
}
}
Note that sorting by multiple fields is not supported.
SDK example (Node, PHP, Python, Ruby)
This example shows how to sort events by datetime with Klaviyo’s SDKs:
import { ConfigWrapper, EventsApi } from 'klaviyo-api'
const eventsApi = new EventsApi(ConfigWrapper("<Your Private Key Here>"))
const events = await eventsApi.getEvents({sort: '-datetime'})
$klaviyo->Events->getEvents(
$fields_event=['event_properties'],
$fields_metric=NULL,
$fields_profile=NULL,
$filter="equals(metric_id,\"UMTLbD\")",
$include=NULL,
$page_cursor=NULL,
$sort='-datetime'
);
klaviyo.Events.get_events(
fields_event=['event_properties'],
filter="equals(metric_id,\"aBc123\")",
sort='-datetime'
)
opts = {
sort: '-datetime'
}
response = KlaviyoAPI::Events.get_events(opts)
Additional resources
Updated over 1 year ago