Skip to main content

Get Data Out of Klaviyo

Course overview
Lesson
4 min read

Pull data from Klaviyo using server-side APIs

Learn how Klaviyo uses server side APIs to get data out of Klaviyo.

Poppy & Pine's developer team sat down with stakeholders to plan the next phase of their Klaviyo integration roadmap. These requests made the top of the list:


1. Data science needs Klaviyo data in the warehouse to sharpen their lifetime value model.
2. The ERP (enterprise resource planning) system needs consent information and custom profile properties, like favorite flowers and birthdays.
3. Leadership needs a weekly dashboard on Klaviyo's impact.
4. Finance needs a report that reconciles with the ecommerce platform.

Same direction (out of Klaviyo). Four very different jobs. The model needs individual events. The ERP needs current profile data. Leadership needs attributed performance stats. Each one calls for a different tool and a different refresh schedule.

So which tool fits which job? Start with the three ways to pull data from Klaviyo.

The three tools to pull data from Klaviyo

Tool

What it returns

Use cases

Watch out for

Standard GET (/api/events, /api/profiles, /api/campaigns)

Returns raw records (individual events or profiles) in JSON:API format, paged with a cursor through links.next. Supports filters, sparse fieldsets (fields[...]), and includes for related resources. Results are paged. Follow links.next until it's null.

Row-level data. Poppy & Pine uses it to: pull Placed Order events into the warehouse for the lifetime value model; sync profiles with consent and custom properties (favorite flower, birthday) to the ERP; pull campaign names and send times for leadership's report.

No attribution logic. Large backfills are slow.

Query Metric Aggregates (POST /api/metric-aggregates)

Returns pre-aggregated counts, sums, or unique counts for one metric, bucketed by interval (hour, day, week, month), optionally grouped by dimensions such as $attributed_message, $flow, or $message.

Trend analysis on a single metric. Good for lightweight dashboards. Poppy & Pine uses Query Metric Aggregates to see daily revenue trends from placed orders. Useful for spotting trends over time.

Its numbers often do not match the Klaviyo UI because it filters and buckets by event time, while campaign and flow performance in the UI is based on send date. Setting a timezone does not remove that difference. However, setting the timezone explicitly controls the time boundaries used in the query. Only one metric per request. In the response, each value in a measurements array lines up by position with the dates array. sum_value adds up each event's value, so events sent without a value don't add to the total.

Reporting API (POST /api/campaign-values-reports, /api/flow-values-reports, and others)

Returns the same performance statistics shown in the Klaviyo UI (ex: opens, clicks, open rate, conversions) per campaign, flow, or message, using a conversion metric you specify.

Whenever the numbers must match what stakeholders see in Klaviyo. Poppy & Pine uses it for leadership's campaign performance in BigQuery, refreshed daily. It's the default for campaign and flow performance reporting in a warehouse.

Very tight rate limits. See Query Campaign Values for the current limits. You must batch carefully and request many statistics in a single call instead of one call per stat.

Common gotchas

Now let's look at some common gotchas when pulling data from Klaviyo. Each card shows a gotcha and an example. Flip it to see the workaround.
0 of 7 cards flipped
Gotcha
Metric Aggregates may not match the Klaviyo UI. Poppy & Pine's warehouse shows $48,000 from September's attributed order events, while its Klaviyo campaign report shows $51,000.
Workaround

If the numbers must match the UI, use the Reporting API instead. If you must use Query Metric Aggregates, set the timezone explicitly for the intended time boundaries, but note that this will not make the results match the UI: aggregates use event time, while campaign reporting uses send date.

Gotcha
Pagination stops after the first page. A profile sync finds only the first page of profiles because it never reads the next page.
Workaround

For paginated resource collections, follow links.next exactly as returned until it is null. Do not change filters or sort order while following the cursor. Check endpoint-specific page-size limits.

Gotcha
Missing or misused sparse fieldsets. A CRM sync labels every profile as having no consent because subscriptions were never requested.
Workaround

Request only what you need with fields[profile]=email,updated,properties, and use additional-fields[profile]=subscriptions or predictive_analytics when you need those. An absent subscriptions object is not an unsubscribed state.

Gotcha
A custom property is not a supported filter. A profile request using filter=equals(properties.loyalty_tier,"gold") returns a 400 error.
Workaround

Check the endpoint's supported filter fields. If it cannot filter by the custom property, a segment such as "Gold tier" can define the audience, and GET /api/segments/{id}/profiles can retrieve its members.

Gotcha
Reporting requests exceed the limit. A dashboard requests campaign performance once per campaign whenever someone loads the page and reaches the daily limit.
Workaround

Schedule extraction, request multiple statistics together, and serve stored results. Honor Retry-After on a 429.

Gotcha
A required campaign filter is missing on an older revision. GET /api/campaigns fails on a revision that requires a channel filter, even though authentication works.
Workaround

On revision 2026-10-15, use GET /api/campaign-messages, which filters by campaign_id, name, status, created, and updated. Older revisions of GET /api/campaigns may require a channel filter, such as filter=equals(messages.channel,'email'). Check the endpoint reference for your pinned revision.

Gotcha
An old example uses the wrong request shape. A v1 or v2 example from a blog does not work against the selected API revision.
Workaround

Always pin the revision header, and use the endpoint reference for that revision to update the request shape. Examples that call Klaviyo's retired v1/v2 legacy endpoints no longer work; verify other older examples against the pinned revision.

Ready to practice? The next lesson, Try it yourself, walks you through pulling Poppy & Pine's campaign performance in Postman.

Pull data from Klaviyo using server-side APIs