Sparse fieldsets
Learn how to request specific fields from resources.
Sparse fieldsets allow you to request only specific fields from a resource or collection. Note that support for this functionality is endpoint-specific. Refer to the fields
query parameter in our API reference documentation.
Sparse fieldsets syntax
Sparse fieldsets are specified using ?fields[TYPE]=field1,field2
as a query parameter, where TYPE
is the singular resource type, e.g., profile
, from which to select only field1
and field2.
The specified field(s) must be in a comma-separated list. Watch out for whitespaces before or after each comma.
Example request and response
A request to Get Catalogs Variants returns a considerable amount of data, including up to 15 different attributes per catalog variant. Large responses like these can lead to extra HTTP responses and data stored in memory. It’s likely you are only interested in a fraction of this data. Fortunately, this customization can be achieved with sparse fieldsets.
The following request to Get Catalogs Variant uses sparse fieldsets to return only external_id
and title
attributes from each catalog variant in the response:
curl --request GET \
--url'https://a.klaviyo.com/api/catalog-variants/?fields[catalog-variant]=external_id,title'\
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-09-15'
{
"data": [
{
"type": "catalog-variant",
"id": "$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-MEDIUM",
"attributes": {
"external_id": "SAMPLE-DATA-ITEM-1-VARIANT-MEDIUM",
"title": "Ocean Blue Shirt (Sample) Variant Medium"
},
"relationships": {
"item": {
"links": {
"self": "https://a.klaviyo.com/api/catalog-variants/$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-MEDIUM/relationships/item/",
"related": "https://a.klaviyo.com/api/catalog-variants/$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-MEDIUM/item/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/catalog-variants/$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-MEDIUM/"
}
},
{
"type": "catalog-variant",
"id": "$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-LARGE",
"attributes": {
"external_id": "SAMPLE-DATA-ITEM-1-VARIANT-LARGE",
"title": "Ocean Blue Shirt (Sample) Variant Large"
},
"relationships": {
"item": {
"links": {
"self": "https://a.klaviyo.com/api/catalog-variants/$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-LARGE/relationships/item/",
"related": "https://a.klaviyo.com/api/catalog-variants/$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-LARGE/item/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/catalog-variants/$custom:::$default:::SAMPLE-DATA-ITEM-1-VARIANT-LARGE/"
}
}
],
"links": {
"self": "https://a.klaviyo.com/api/catalog-variants?fields[catalog-variant]=external_id,title",
"next": null,
"prev": null
}
}
Note that the relationships
and links
fields are still fully populated in the response. Each attribute
object only contains the external_id
and title
fields as requested.
Sparse fieldsets with included resource types
You can specify sparse fieldsets for included resource types. For example, you might want to retrieve profile email addresses linked to a list of events. To do this, you must use the include
query parameter to include the profile
resource. Then, you can set profile
as the resource type and email
as a field as shown in the example below:
curl --request GET \
--url'https://a.klaviyo.com/api/events?include=profile&fields[profile]=email'\
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-09-15'
{
"data": [
{
"type": "event",
"id": "4v7eCFTjDyX",
"attributes": {
"timestamp": 1691679684,
"event_properties": {
"browser": "Firefox",
"os": "Windows",
"page": "http://www.example.com/landing",
"$event_id": "sample_data_gen:b80a551a-061e-42d1-8890-432006b54c8b"
},
"datetime": "2023-08-10 15:01:24+00:00",
"uuid": "c5e3fa00-378e-11ee-8001-08175e8dffb7"
},
"relationships": {
"profile": {
"data": {
"type": "profile",
"id": "01H7FZEVHAZB1TNK8KBVGE0YZR"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4v7eCFTjDyX/relationships/profile/",
"related": "https://a.klaviyo.com/api/events/4v7eCFTjDyX/profile/"
}
},
"metric": {
"data": {
"type": "metric",
"id": "XWCLtq"
},
"links": {
"self": "https://a.klaviyo.com/api/events/4v7eCFTjDyX/relationships/metric/",
"related": "https://a.klaviyo.com/api/events/4v7eCFTjDyX/metric/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/4v7eCFTjDyX/"
}
},
...
],
"included": [
{
"type": "profile",
"id": "01H7FZEVHAZB1TNK8KBVGE0YZR",
"attributes": {
"email": "[email protected]"
},
"relationships": {
"lists": {
"links": {
"self": "https://a.klaviyo.com/api/profiles/01H7FZEVHAZB1TNK8KBVGE0YZR/relationships/lists/",
"related": "https://a.klaviyo.com/api/profiles/01H7FZEVHAZB1TNK8KBVGE0YZR/lists/"
}
},
"segments": {
"links": {
"self": "https://a.klaviyo.com/api/profiles/01H7FZEVHAZB1TNK8KBVGE0YZR/relationships/segments/",
"related": "https://a.klaviyo.com/api/profiles/01H7FZEVHAZB1TNK8KBVGE0YZR/segments/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/profiles/01H7FZEVHAZB1TNK8KBVGE0YZR/"
}
},
...
],
"links": {
"self": "https://a.klaviyo.com/api/events?include=profile&fields[profile]=email",
"next": null,
"prev": null
}
}
Note that the included
field of the response payload contains a list of profiles with its attributes
limited to the email
field as requested.
Note that sparse fieldsets can only be used on fields that exist across a resource. For example, across the event resource, you can use sparse fieldsets to only return the
event_properties
field. However, you cannot use sparse fieldsets to only return specific fields within theevent_properties
field itself.
Additional fields
You can use ?additional-fields
as a query parameter to return additional fields not shown by default in the response body. This query parameter shares the same syntax as sparse fieldsets, i.e., ?additional-fields[TYPE]=field,
where TYPE
is the singular resource type, e.g., profile
, and field
is the additional field. Support for additional-fields
is endpoint-specific.
Example request and response
The following request to Get List uses the ?additional-fields
query parameter to return profile_count
, a field representing the number of profiles on a given list:
curl --request GET \
--url'https://a.klaviyo.com/api/lists/RB89mt/?additional-fields[list]=profile_count'\
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-09-15'
{
"data": {
"type": "list",
"id": "RB89mt",
"attributes": {
"name": "Profile List",
"created": "2023-06-05T14:49:54+00:00",
"updated": "2023-06-06T14:20:50+00:00",
"profile_count": 10
},
"relationships": {
"profiles": {
"links": {
"self": "https://a.klaviyo.com/api/lists/RB89mt/relationships/profiles/",
"related": "https://a.klaviyo.com/api/lists/RB89mt/profiles/"
}
},
"tags": {
"links": {
"self": "https://a.klaviyo.com/api/lists/RB89mt/relationships/tags/",
"related": "https://a.klaviyo.com/api/lists/RB89mt/tags/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/lists/RB89mt/"
}
}
}
Predictive analytics
The ?additional-fields
parameter allows you to retrieve predictive analytics via API, which are valuable for monitoring metrics such as customer lifetime value (CLV) and order predictions for profiles.
Note that, to be eligible for predictive analytics, your account must meet the following conditions:
- At least 500 customers have placed an order.
- You have an ecommerce integration or use our API to send placed orders.
- You have at least 180 days of order history, including orders within the last 30 days.
- You have customers who have placed 3 or more orders.
Learn more about Klaviyo's predictive analytics.
The full list of predictive analytics fields that can be returned for a profile are:
Field | Description |
---|---|
historic_clv | Total value of all historically placed orders. |
predicted_clv | Predicted value of all placed orders in the next 365 days. |
total_clv | Sum of historic and predicted CLV. |
historic_number_of_orders | Number of placed orders. |
predicted_number_of_orders | Predicted number of placed orders in the next 365 days. |
average_days_between_orders | Average number of days between orders, over all time. |
average_order_value | Average value of historically placed orders. |
churn_probability | Probability that the customer will never make another purchase, or churn. |
expected_date_of_next_order | Expected date of next order, calculated at the time of their most recent order. |
Note that you can use sparse fieldsets to request for only a field(s) not included by default in the response. For example, you can request for additional fields with sparse fieldsets to include only
predictive_analytics
in the response. Be sure to use both query parameters in your request.
SDK example (Node, PHP, Python, Ruby)
This SDK example shows how to request events along with their related profile attributes limited to external_id
and title
fields:
import { ConfigWrapper, Events } from 'klaviyo-api';
ConfigWrapper(process.env["KLAVIYO_PRIVATE_API_KEY"]));
const eventsList = await Events.getEvents({fieldsProfile:["external_id","title"],include:["profile"]});
$klaviyo->Events->getEvents(
$fields_event=NULL,
$fields_metric=NULL,
$fields_profile=['external_id','title'],
$include=['profile'],
$page_cursor=NULL
);
klaviyo.Events.get_events(
fields_profile=['external_id','title'],
include=['profile']
)
opts = {
fields_profile: ["external_id","title"],
include: ['profile']
}
response = KlaviyoAPI::Events.get_events(opts)
Additional resources
Updated 9 months ago