Skip to main content

Klaviyo

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Support Level
Airbyte
Connector Version
3.0.0 (last updated 11 minutes ago)
Sync Success Rate
High
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
Definition ID
95e8cffd-b8c4-4039-968e-d32fb4a69bde

This page contains the setup guide and reference information for the Klaviyo source connector.

Prerequisites​

Setup guide​

Step 1: Set up Klaviyo​

  1. Create a Klaviyo account
  2. Create a Private API key. Make sure you selected all scopes corresponding to the streams you would like to replicate. You can find which scope is required for a specific stream by navigating to the relevant API documentation for the streams Airbyte supports.

Step 2: Set up the Klaviyo connector in Airbyte​

For Airbyte Cloud​

  1. Log into your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Klaviyo from the Source type dropdown.
  4. Enter a name for the Klaviyo connector.
  5. For Api Key, enter the Klaviyo Private API key.
  6. For Start Date, enter a UTC date and time in YYYY-MM-DDTHH:MM:SSZ format (for example, 2017-01-25T00:00:00Z). Airbyte replicates data added on or after this date. This field is optional; if you leave it blank, Airbyte replicates the last year of data. The metrics stream is an exception and always syncs all metric definitions (see Metrics stream).
  7. (Optional) Select Disable Fetching Predictive Analytics to stop the connector from requesting predictive analytics data. See Performance considerations.
  8. For Number of concurrent threads, enter the number of worker threads the sync uses. Defaults to 10; the maximum is 50. Lower this value if syncs hit Klaviyo rate limits, and raise it only if your Klaviyo plan's rate limit tier allows more throughput.
  9. For Lookback Window (Days), enter the number of days to look back when syncing data in incremental mode. This helps capture any late-arriving data. Defaults to 0 days if not provided. Only applies to the events_detailed stream; for Flow Series Reports, use Reporting Lookback Window (Days) instead.
  10. (Optional) For Reporting Lookback Window (Days), enter the number of days of Flow Series Reports data to re-sync on every incremental run. Klaviyo revises conversion attribution after a send, so set this to at least your attribution window to pick up those revisions. Re-synced days replace the rows already written for them. Defaults to 0. See Analytics streams for details.
  11. (Optional) For Report Stream Conversion Metric IDs, enter a comma-separated list of Klaviyo metric IDs to limit the Campaign Values Reports and Flow Series Reports streams to specific conversion metrics. If not provided, the connector fetches reports for all metrics, which can be slow due to rate limits. See Analytics streams for details.
  12. (Optional) For Event Stream Metric IDs, enter a comma-separated list of Klaviyo metric IDs to filter the Events and Events Detailed streams to specific metrics. If not provided, all events are synced. See Event stream filtering below.
  13. Click Set up source.

For Airbyte Open Source​

  1. Navigate to the Airbyte Open Source dashboard.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Klaviyo from the Source type dropdown.
  4. Enter a name for the Klaviyo connector.
  5. For Api Key, enter the Klaviyo Private API key.
  6. For Start Date, enter a UTC date and time in YYYY-MM-DDTHH:MM:SSZ format (for example, 2017-01-25T00:00:00Z). Airbyte replicates data added on or after this date. This field is optional; if you leave it blank, Airbyte replicates the last year of data. The metrics stream is an exception and always syncs all metric definitions (see Metrics stream).
  7. (Optional) Select Disable Fetching Predictive Analytics to stop the connector from requesting predictive analytics data. See Performance considerations.
  8. For Number of concurrent threads, enter the number of worker threads the sync uses. Defaults to 10; the maximum is 50. Lower this value if syncs hit Klaviyo rate limits, and raise it only if your Klaviyo plan's rate limit tier allows more throughput.
  9. For Lookback Window (Days), enter the number of days to look back when syncing data in incremental mode. This helps capture any late-arriving data. Defaults to 0 days if not provided. Only applies to the events_detailed stream; for Flow Series Reports, use Reporting Lookback Window (Days) instead.
  10. (Optional) For Reporting Lookback Window (Days), enter the number of days of Flow Series Reports data to re-sync on every incremental run. Klaviyo revises conversion attribution after a send, so set this to at least your attribution window to pick up those revisions. Re-synced days replace the rows already written for them. Defaults to 0. See Analytics streams for details.
  11. (Optional) For Report Stream Conversion Metric IDs, enter a comma-separated list of Klaviyo metric IDs to limit the Campaign Values Reports and Flow Series Reports streams to specific conversion metrics. If not provided, the connector fetches reports for all metrics, which can be slow due to rate limits. See Analytics streams for details.
  12. (Optional) For Event Stream Metric IDs, enter a comma-separated list of Klaviyo metric IDs to filter the Events and Events Detailed streams to specific metrics. If not provided, all events are synced. See Event stream filtering below.
  13. Click Set up source.

Supported sync modes​

The Klaviyo source connector supports the following sync modes:

Supported Streams​

Metrics stream​

The Metrics stream always syncs all metric definitions, regardless of the configured Start Date. Metric definitions are reference data needed to interpret other streams (for example, joining relationships.data.metric.id in events to a metric name), and the Klaviyo API does not support filtering metrics by date. On subsequent incremental syncs, only new and updated metric definitions are emitted. If older metric definitions are missing after upgrading from a previous connector version, clear/reset the metrics stream to backfill them.

This stream requires the metrics:read scope on your API key.

Streams that filter incrementally after fetching​

The Metrics, Lists, Lists Detailed, and Segments streams request every record from Klaviyo on each sync and then discard records older than the cursor position. Start Date and incremental sync therefore reduce how many records these streams emit, but not how many API requests they make. Expect sync duration for these streams to scale with the total number of lists, segments, and metrics in your account rather than with the amount of new data.

Analytics streams​

The Campaign Values Reports and Flow Series Reports streams provide performance analytics from Klaviyo's Reporting API.

Flow Series Reports emits one record per calendar day per flow message, with each statistics field holding that day's value. Its date field is the day the row reports on, and it forms part of the primary key (date, flow_id, flow_message_id, send_channel, conversion_metric_id), so a day read again comes back under the identity it already had.

Campaign Values Reports has no per-day breakdown: the endpoint returns a single aggregate for the whole period the connector requests, and date is the midnight that closes that period. A row dated 2024-06-15T00:00:00+00:00 therefore covers everything up to the end of 2024-06-14. Its primary key is date, campaign_id, campaign_message_id, send_channel, and conversion_metric_id.

The connector requests both reports in windows of up to 30 days. On a first sync, each Campaign Values Reports row therefore aggregates up to 30 days of activity; later incremental syncs request only the days since the previous sync, so their rows cover shorter periods.

Report periods always cover whole calendar days in your Klaviyo account's (company) timezone. Klaviyo ignores the timezone offset in a custom report timeframe and interprets the timeframe in the company timezone configured for your account, while presenting the timestamps it returns with a +00:00 offset. If your start date includes a time of day, the first period is extended back to the midnight before it. Every sync stops at the end of the last complete day, so the current day's data arrives with the next sync rather than the current one.

Klaviyo keeps revising conversion attribution after a send, by default for up to 5 days and up to 90 days if you have raised the attribution window in your account settings. Numbers first reported for a day therefore keep changing for a while. Use Reporting Lookback Window (Days) to re-sync the last few days of Flow Series Reports on every incremental run and pick those revisions up; set it to at least your attribution window. On a destination that deduplicates on the primary key, each re-synced day replaces the row already written for it; in append mode each re-synced day adds an extra row per sync instead. This setting does not apply to Campaign Values Reports, because that endpoint reports a single aggregate per requested period rather than per-day values, so a re-read there could only add a second row covering the same days.

These streams require the following API key scopes:

  • Campaign Values Reports: campaigns:read
  • Flow Series Reports: flows:read

Both streams also need metrics:read, because the connector lists your account's metrics to decide which conversion metrics to request reports for.

Both streams partition data by conversion metric. By default, the connector fetches reports for all metrics in your account. You can use the optional Report Stream Conversion Metric IDs configuration field to specify a comma-separated list of metric IDs (for example, RESQ6t,ABC123) to limit reporting to specific conversion metrics.

warning

These analytics endpoints have strict Klaviyo API rate limits (see documentation): 1 request per second burst, 2 requests per minute steady, and 225 requests per day. Because the connector makes a separate API request for each metric and each time window, syncing all metrics can take several hours and may exceed the daily rate limit. Specify only the conversion metrics you need using the Report Stream Conversion Metric IDs field.

Not all Klaviyo metrics support conversion value queries. For example, metrics without a $value property cannot be queried for values data. The connector automatically skips these unsupported metrics and continues syncing the remaining ones. If you see fewer results than expected, verify that your selected metrics support values data in Klaviyo.

To find your conversion metric IDs:

  1. Log into your Klaviyo account.
  2. Navigate to Analytics > Metrics.
  3. Select the metric you want to track conversions for (for example, "Placed Order").
  4. Copy the metric ID from the URL, or use the Metrics stream to list all available metrics and their IDs.

Event stream filtering​

The Events and Events Detailed streams can filter server-side by metric ID, using the Event Stream Metric IDs configuration field. Both streams require the events:read scope on your API key.

Klaviyo's metric_id filter only supports the equals operator, so the connector issues a separate set of requests for each metric ID you configure. Each additional metric ID multiplies the number of API requests per sync. If syncs hit Klaviyo rate limits, reduce the number of configured metrics or lower the Number of concurrent threads setting.

note

Klaviyo's Get Events endpoint doesn't support custom metrics in the metric_id filter. Filter on built-in metrics only, such as Placed Order or Opened Email.

A metric ID you add to an existing configuration syncs from the stream's current cursor position onward. The connector doesn't backfill that metric's older events. To sync history for a newly added metric, clear the affected stream after you update the configuration.

To find metric IDs, go to Analytics > Metrics in your Klaviyo account, or use the Metrics stream to list all available metrics and their IDs.

Performance considerations​

The connector is restricted by Klaviyo rate limits.

The Klaviyo connector should not run into Klaviyo API limitations under normal usage. Create an issue if you encounter any rate limit issues that are not automatically retried successfully.

The Campaigns Detailed stream contains fields estimated_recipient_count and campaign_message in addition to info from the Campaigns stream. Additional time is needed to fetch extra data.

The Lists Detailed stream contains field profile_count in addition to info from the Lists stream. Additional time is needed to fetch extra data due to Klaviyo API limitation.

The Events Detailed stream contains field name for metric relationship - addition to info.

The Profiles stream can experience transient API errors under heavy load. To mitigate this, you can use the Disable Fetching Predictive Analytics setting to improve the success rate of syncs. This setting only affects the predictive_analytics field. Subscription and consent data on profile records is unaffected and is always fetched.

warning

Using the Disable Fetching Predictive Analytics setting means records on the Profiles stream will no longer contain the predictive_analytics field, and workflows depending on this field will stop working.

Data type map​

Integration TypeAirbyte Type
stringstring
numbernumber
arrayarray
objectobject

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
string
api_key
boolean
disable_fetching_predictive_analytics
string
event_metric_ids
integer
lookback_window
string
metric_ids
integer
num_workers
integer
reporting_lookback_window
string
start_date

Changelog​

Expand to review
VersionDatePull RequestSubject
3.0.02026-08-1475495Emit one record per calendar day with scalar statistics in flow_series_reports, add a reporting lookback window for that stream, and align both report streams to whole-day windows to stop boundary double-counting (refresh the schema and clear both report streams)
2.21.12026-08-1183991Update dependencies
2.21.02026-08-0775301Add optional metric ID filtering for the events and events_detailed streams
2.20.02026-08-0561338Sync all metric definitions in the metrics stream regardless of the configured start date (existing connections: clear/reset the metrics stream to backfill older metric definitions)
2.19.32026-07-2883194Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override
2.19.22026-07-281082Roll Cloud back to 2.19.0 — 2.19.1 is built on SDM 7.23.7, which breaks bundled custom components
2.19.12026-07-2882475Update dependencies
2.19.02026-07-1581637Default start date to one year back when not provided
2.18.62026-07-1481870Update dependencies
2.18.52026-06-3081120Update dependencies
2.18.42026-06-2380514Update dependencies
2.18.32026-06-2276919fix(source-klaviyo): Add missing unsubscribe and spam complaint fields to reporting streams
2.18.22026-06-1679898Update dependencies
2.18.12026-06-0979342Update dependencies
2.18.02026-06-0476941Add new segments stream
2.17.92026-06-0278784Update dependencies
2.17.82026-04-2877313Update dependencies
2.17.72026-04-2577008Fix sync failure when conversion metrics do not support values data queries in flow_series_reports and campaign_values_reports streams
2.17.62026-04-2175707Update dependencies
2.17.52026-04-1675180Restore subscriptions field to profiles stream additional-fields[profile] parameter, fixing a regression introduced in v2.16.x where the subscriptions data was no longer fetched from the Klaviyo API
2.17.42026-04-1376276Rename "concurrent workers" to "concurrent threads" in connector spec
2.17.32026-03-1774995Update dependencies
2.17.22026-03-1074435Update dependencies
2.17.12026-03-0373958Update dependencies
2.17.02026-02-1973642Add new analytics streams: Flow Series Reports and Campaign Values Reports
2.16.152026-02-1773540Update dependencies
2.16.142026-02-1073058Update dependencies
2.16.132026-02-0372750Update dependencies
2.16.122026-01-2072040Update dependencies
2.16.112026-01-1970208Add chunking to events_detailed stream to fix full refresh stalling and incremental mode returning zero rows
2.16.102026-01-1471461Update dependencies
2.16.92025-12-1870783Update dependencies
2.16.82025-11-2570028Update dependencies
2.16.72025-11-1869457Update dependencies
2.16.62025-10-2968983Update dependencies
2.16.52025-10-2168298Update dependencies
2.16.42025-10-1468028Update dependencies
2.16.32025-10-0767517Update dependencies
2.16.22025-09-3066643Update dependencies
2.16.12025-09-0966070Update dependencies
2.16.02025-09-0865990Revert the v2.15.0 change, which caused subscriptions data to stop being fetched on the profiles stream (fixed in v2.17.5)
2.15.02025-09-0765935Fetch subscriptions data on the profiles stream
2.14.222025-08-2565509Fix custom migrations to reference DeclarativeStream Pydantic model instead of runtime component
2.14.212025-08-2365317Update dependencies
2.14.202025-08-0964618Update dependencies
2.14.192025-08-0264210Update dependencies
2.14.182025-07-2663815Update dependencies
2.14.172025-07-1963482Update dependencies
2.14.162025-07-1263154Update dependencies
2.14.152025-07-0562631Update dependencies
2.14.142025-06-2862167Update dependencies
2.14.132025-06-2161858Update dependencies
2.14.122025-06-1460653Update dependencies
2.14.112025-05-1059260Update dependencies
2.14.102025-04-2958123Add missing fields for events_detailed stream for attributions
2.14.92025-04-2658192Update dependencies
2.14.82025-04-1257751Update dependencies
2.14.72025-04-0557033Update dependencies
2.14.62025-03-2956634Update dependencies
2.14.52025-03-2256017Update dependencies
2.14.42025-03-1455772Add back step to streams that can process date ranges in parallel
2.14.32025-03-0855479Update dependencies
2.14.22025-03-0354720Add event_properties option to events request
2.14.12025-03-0154770Update dependencies
2.14.02025-02-2654166Migrate to Manifest-only
2.13.12025-02-2254369Update dependencies
2.13.02025-02-1851551Upgrade to API v2024-10-15
2.12.12025-02-1552710Update dependencies
2.12.02025-02-1153223Add API Budget
2.11.112025-01-2752563Fix lists_detailed incremental sync
2.11.102025-01-2552285Update dependencies
2.11.92025-01-1151198Update dependencies
2.11.82025-01-0951010Fix AirbyteMessage serialization with integers bigger than 64 bits
2.11.72025-01-0450893Update dependencies
2.11.62024-12-2850653Update dependencies
2.11.52024-12-2150088Update dependencies
2.11.42024-12-1449250Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
2.11.32024-12-1249144Update dependencies
2.11.22024-12-0248748Bump CDK to evict non retriable requests to avoid high memory usage
2.11.12024-11-2648710Retry on "Temporary failure in name resolution"
2.11.02024-11-1848452Enable concurrency for syncs that don't have client-side filtering
2.10.142024-11-0748391Remove custom datetime cursor dependency
2.10.132024-11-0548331Update dependencies
2.10.122024-10-2947797Update dependencies
2.10.112024-10-2847043Update dependencies
2.10.102024-10-1446741Add checkpointing to events stream to improve large syncs after clear data
2.10.92024-10-1246787Update dependencies
2.10.82024-10-0546503Update dependencies
2.10.72024-09-2846174Update dependencies
2.10.62024-09-2145813Update dependencies
2.10.52024-09-1445530Update dependencies
2.10.42024-09-0745244Update dependencies
2.10.32024-08-3145064Update dependencies
2.10.22024-08-3044930Fix typing in profiles stream for field attributes.location.region
2.10.12024-08-2444628Update dependencies
2.10.02024-08-1844366Add field[metrics] to events stream
2.9.42024-08-1744317Update dependencies
2.9.32024-08-1243806Update dependencies
2.9.22024-08-1043613Update dependencies
2.9.12024-08-0343247Update dependencies
2.9.02024-08-0142891Migrate to CDK v4.X and remove custom BackoffStrategy implementation
2.8.22024-07-3142895Add config option disable_fetching_predictive_analytics to prevent 503 Service Unavailable errors
2.8.12024-07-2742664Update dependencies
2.8.02024-07-1942121Migrate to CDK v3.9.0
2.7.82024-07-2042185Update dependencies
2.7.72024-07-0840608Update the events_detailed stream to improve efficiency using the events API
2.7.62024-07-1341903Update dependencies
2.7.52024-07-1041548Update dependencies
2.7.42024-07-0941211Update dependencies
2.7.32024-07-0640770Update dependencies
2.7.22024-06-2640401Update dependencies
2.7.12024-06-2240032Update dependencies
2.7.02024-06-0839350Add events_detailed stream
2.6.42024-06-0638879Implement CheckpointMixin for handling state in Python streams
2.6.32024-06-0438935[autopull] Upgrade base image to v1.2.1
2.6.22024-05-0837789Move stream schemas and spec to manifest
2.6.12024-05-0738010Add error handler for 5XX status codes
2.6.02024-04-1937370Add streams campaigns_detailed and lists_detailed
2.5.02024-04-1536264Migrate to low-code
2.4.02024-04-1136989Update Campaigns schema
2.3.02024-03-1936267Pin airbyte-cdk version to ^0
2.2.02024-02-2735637Fix predictive_analytics field in stream profiles
2.1.32024-02-1535336Added type transformer for the profiles stream.
2.1.22024-02-0935088Manage dependencies with Poetry.
2.1.12024-02-0734998Add missing fields to stream schemas
2.1.02023-12-0733237Continue syncing streams even when one of the stream fails
2.0.22023-12-0533099Fix filtering for archived records stream
2.0.12023-11-0832291Add logic to have regular checkpointing schedule
2.0.02023-11-0332128Use the latest API for streams campaigns, email_templates, events, flows, global_exclusions, lists, and metrics
1.1.02023-10-2331710Make start_date config field optional
1.0.02023-10-1831565Add new known fields for 'events' stream
0.5.02023-10-1931611Add date-time format for datetime field in Events stream
0.4.02023-10-1831562Add archived field to Flows stream
0.3.32023-10-1331379Skip streams that the connector no longer has access to
0.3.22023-06-2027498Do not store state in the future
0.3.12023-06-0827162Anonymize check connection error message
0.3.02023-02-1823236Add Email Templates stream
0.2.02023-03-1323968Add Profiles stream
0.1.132023-02-1322942Specified date formatting in specification
0.1.122023-01-3022071Fix Events stream schema
0.1.112023-01-2722012Set AvailabilityStrategy for streams explicitly to None
0.1.102022-09-2917422Update CDK dependency
0.1.92022-09-2817304Migrate to per-stream state.
0.1.62022-07-2014872Increase test coverage
0.1.52022-07-1214617Set max_retries = 10 for lists stream.
0.1.42022-04-1511723Enhance klaviyo source for flows stream and update to events stream.
0.1.32021-12-098592Improve performance, make Global Exclusions stream incremental and enable Metrics stream.
0.1.22021-10-196952Update schema validation in SAT
Was this page helpful?