Sparse fieldsets

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 the event_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.

📘
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.

📘
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)

Sparse fieldsets syntax

🚧

Example request and response

Sparse fieldsets with included resource types

🚧

Additional fields

Example request and response

Predictive analytics

📘

📘

SDK example (Node, PHP, Python, Ruby)

Additional resources