Bulk Export APIs overview (beta)

OpenAPI Spec

The Bulk Export endpoints are part of the beta Events and Profiles specs:

• Events bulk export: beta/categories/events.json
• Profiles bulk export: beta/categories/profiles.json

Before you begin

Check out our general API overview before getting started with specific endpoints.

🚧

Access required

The Bulk Export APIs are invite-only during beta. Access is limited to allow-listed API keys and OAuth applications, and is granted selectively — submitting a request does not guarantee access. To request access, submit this form. Access is granted either at the OAuth app level (for approved partners building a multi-tenant integration across their install base) or at the account level (for a customer requesting access for their own account). During beta we review requests periodically and enable access at our discretion. We are evaluating a pricing model during this invite-only beta period and would welcome your feedback; eligibility, availability, and terms may change before GA.

🚧

These endpoints are in Beta and require the revision: 2026-07-15.pre header. Endpoint paths and request/response shapes may change before GA.

The Bulk Export APIs let approved partners and businesses export large volumes of historical event and profile data from Klaviyo through asynchronous jobs. Instead of paginating through the standard Get Events or Get Profiles endpoints, you create an export job, poll it until it completes, and download a single compressed file. This is designed for one-time backfills, migrations, and analytics loads — not for real-time, incremental syncs.

There are two APIs:

• Events bulk export — export events for a given metric within a date range. See Create Event Bulk Export Job.
• Profiles bulk export — export the profiles in a given list or segment. See Create Profile Bulk Export Job.

Use cases

The Bulk Export APIs support the following use cases:

• Model training and enrichment: pull a large, historical set of events or profiles to train predictive models or hydrate a feature store during onboarding, where the pattern is a lagging, ad-hoc load rather than continuous real-time ingestion.
• Historical backfill: seed a data warehouse or lake with a full history of a metric's events, or a full membership snapshot of a list or segment.
• Migration and audit: export a segment's profiles for a one-time migration, reconciliation, or compliance audit.

Required scopes

Access is gated separately from scopes (see the access callout above), but your API key or OAuth app still needs the appropriate read scopes for the data you're exporting:

• Events bulk export: events:read and metrics:read
• Profiles bulk export: profiles:read, lists:read, and segments:read

How bulk export works

Bulk export is a three-step, asynchronous flow:

1. Create a job. POST to the relevant create endpoint with your export parameters. A successful request returns 202 Accepted with a job id. The export runs in the background.
2. Poll for status. Retrieve the job by its id to check its status. When the job is complete, the response includes the file's expiration and size.
3. Download the file. Once complete, request the job's download to receive the exported data as a compressed CSV. Download URLs are short-lived — retrieve and download promptly, and create a new job if the file has expired.

Example: create an event bulk export job

curl --request POST \
  --url 'https://a.klaviyo.com/api/event-bulk-export-jobs' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'revision: 2026-07-15.pre' \
  --data '
{
  "data": {
    "type": "event-bulk-export-job",
    "attributes": {
      "start_date": "2026-01-01T00:00:00Z",
      "end_date": "2026-06-30T23:59:59Z"
    },
    "relationships": {
      "metric": {
        "data": {
          "type": "metric",
          "id": "WsRuHm"
        }
      }
    }
  }
}
'

Example: create a profile bulk export job

curl --request POST \
  --url 'https://a.klaviyo.com/api/profile-bulk-export-jobs' \
  --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'revision: 2026-07-15.pre' \
  --data '
{
  "data": {
    "type": "profile-bulk-export-job",
    "attributes": {},
    "relationships": {
      "segment": {
        "data": {
          "type": "segment",
          "id": "01H2XYZABCDEFGHJKMNPQRSTVW"
        }
      }
    }
  }
}
'

For a profile export, provide either a list or a segment relationship — not both.

Limitations

• Beta and invite-only. These endpoints require the revision: 2026-07-15.pre header and are only callable by allow-listed API keys and OAuth applications. Non-allow-listed callers receive a 403.
• Historical, not real-time. Bulk export is built for large, ad-hoc loads. For ongoing, incremental data sync, use the standard Events and Profiles endpoints or webhooks.
• Download URLs expire. Completed export files are available for a limited time; create a new job if a file has expired.
• Profile exports are scoped to one group. Each profile export job targets a single list or segment.

Additional resources

• Create Event Bulk Export Job
• Create Profile Bulk Export Job
• Set up OAuth
• Rate limits, status codes, and errors