{ "openapi": "3.0.2", "info": { "title": "Klaviyo API", "version": "2026-04-15", "description": "The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.", "contact": { "name": "Klaviyo Developer Experience Team", "email": "developers@klaviyo.com", "url": "https://developers.klaviyo.com" }, "termsOfService": "https://www.klaviyo.com/legal/api-terms", "license": { "name": "License", "url": "https://www.klaviyo.com/legal" } }, "servers": [ { "url": "https://a.klaviyo.com", "description": "Production" } ], "security": [ { "Klaviyo-API-Key": [] } ], "paths": { "/api/events": { "get": { "operationId": "get_events", "summary": "Get Events", "description": "Get all events in an account\n\nRequests can be sorted by the following fields:\n`datetime`, `timestamp`\n\n[Custom metrics](https://developers.klaviyo.com/en/reference/custom_metrics_api_overview) are not supported in the `metric_id` filter.\n\nReturns a maximum of 200 events per page.

*Rate limits*:
Burst: `350/s`
Steady: `3500/m`\n\n**Scopes:**\n`events:read`\n\n[OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable/apis/get_events.json)", "parameters": [ { "name": "fields[attribution]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id" ] } }, "explode": false }, { "name": "fields[event]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "datetime", "event_properties", "id", "timestamp", "uuid" ] } }, "explode": false }, { "name": "fields[metric]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "created", "id", "integration", "name", "updated" ] } }, "explode": false }, { "name": "fields[profile]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "created", "email", "external_id", "first_name", "id", "image", "last_event_date", "last_name", "locale", "location", "location.address1", "location.address2", "location.city", "location.country", "location.ip", "location.latitude", "location.longitude", "location.region", "location.timezone", "location.zip", "organization", "phone_number", "properties", "title", "updated" ] } }, "explode": false }, { "name": "filter", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#filtering
Allowed field(s)/operator(s):
`metric_id`: `equals`
`profile_id`: `equals`
`profile`: `has`
`datetime`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`
`timestamp`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`", "schema": { "type": "string", "example": "equals(metric_id,'example')" } }, { "name": "include", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#relationships", "schema": { "type": "array", "items": { "type": "string", "enum": [ "attributions", "metric", "profile" ] } }, "explode": false }, { "name": "page[cursor]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#pagination", "required": false, "schema": { "type": "string" } }, { "name": "page[size]", "in": "query", "description": "Default: 200. Min: 1. Max: 1000.", "required": false, "schema": { "type": "integer", "default": 200, "maximum": 1000, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sorting", "schema": { "type": "string", "enum": [ "datetime", "-datetime", "timestamp", "-timestamp" ] } }, { "name": "revision", "in": "header", "description": "API endpoint revision (format: YYYY-MM-DD[.suffix])", "required": true, "schema": { "type": "string", "default": "2026-04-15" } } ], "responses": { "200": { "description": "Success", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/GetEventResponseCollectionCompoundDocument" } } } }, "4XX": { "$ref": "#/components/responses/ClientError" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "tags": [ "Events" ], "x-klaviyo-filters": { "metric_id": { "operators": { "single": [ "equals" ], "list": [ "equals" ] }, "value": { "type": "string" } }, "profile_id": { "operators": { "single": [ "equals" ] }, "value": { "type": "string" } }, "profile": { "operators": { "none": [ "has" ] } }, "datetime": { "operators": { "single": [ "greater-or-equal", "greater-than", "less-or-equal", "less-than" ] }, "value": { "type": "string", "format": "date-time" } }, "timestamp": { "operators": { "single": [ "greater-or-equal", "greater-than", "less-or-equal", "less-than" ] }, "value": { "type": "number" } } }, "x-klaviyo-pre-release": "None", "x-klaviyo-ratelimit": { "burst": "350/s", "steady": "3500/m" }, "x-klaviyo-scopes": [ "events:read" ] } } }, "components": { "responses": { "ClientError": { "description": "Client Error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "title", "detail" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } } } } } }, "required": [ "errors" ] } } } }, "ServerError": { "description": "Server Error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "required": [ "id", "code", "title", "detail" ], "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "source": { "type": "object", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" } } } } } } }, "required": [ "errors" ] } } } } }, "schemas": { "AttributionEnum": { "type": "string", "enum": [ "attribution" ] }, "AttributionResponseObjectResource": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/AttributionEnum" }, "id": { "description": "The ID of the attribution", "type": "string", "example": "925e385b52fb405715f3616c337cc65c" }, "relationships": { "type": "object", "properties": { "event": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/EventEnum" }, "id": { "description": "Event", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "attributed-event": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/EventEnum" }, "id": { "description": "Attributed Event", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "campaign": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CampaignEnum" }, "id": { "description": "Attributed Campaign", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "campaign-message": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CampaignMessageEnum" }, "id": { "description": "Attributed Campaign Message", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "flow": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FlowEnum" }, "id": { "description": "Attributed Flow", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "flow-message": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FlowMessageEnum" }, "id": { "description": "Attributed Flow Message", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "flow-message-variation": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FlowMessageEnum" }, "id": { "description": "Attributed Flow Message Variation", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } } }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "id", "links" ] }, "CampaignEnum": { "type": "string", "enum": [ "campaign" ] }, "CampaignMessageEnum": { "type": "string", "enum": [ "campaign-message" ] }, "CollectionLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "prev": { "type": "string", "format": "uri" }, "next": { "type": "string", "format": "uri" } }, "required": [ "self" ] }, "EventEnum": { "type": "string", "enum": [ "event" ] }, "EventResponseObjectResource": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/EventEnum" }, "id": { "description": "The Event ID", "type": "string" }, "attributes": { "type": "object", "properties": { "timestamp": { "description": "Event timestamp in seconds", "type": "integer", "nullable": true }, "event_properties": { "description": "Event properties, can include identifiers and extra properties", "type": "object", "nullable": true }, "datetime": { "description": "Event timestamp in ISO8601 format (YYYY-MM-DDTHH:MM:SS+hh:mm)", "type": "string", "format": "date-time", "example": "2022-11-08T01:23:45+00:00", "nullable": true }, "uuid": { "description": "A unique identifier for the event, this can be used as a cursor in pagination", "type": "string", "nullable": true } } }, "relationships": { "type": "object", "properties": { "profile": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ProfileEnum" }, "id": { "description": "Profile ID of the associated profile, if available", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "metric": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/MetricEnum" }, "id": { "description": "The Metric ID", "type": "string" } }, "required": [ "type", "id" ] }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "attributions": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/AttributionEnum" }, "id": { "description": "Attributions for this event", "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } } }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "id", "attributes", "links" ] }, "FlowEnum": { "type": "string", "enum": [ "flow" ] }, "FlowMessageEnum": { "type": "string", "enum": [ "flow-message" ] }, "GetEventResponseCollectionCompoundDocument": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventResponseObjectResource" } }, "links": { "$ref": "#/components/schemas/CollectionLinks" }, "included": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/MetricResponseObjectResource" }, { "$ref": "#/components/schemas/ProfileResponseObjectResource" }, { "$ref": "#/components/schemas/AttributionResponseObjectResource" } ] } } }, "required": [ "data" ] }, "ListEnum": { "type": "string", "enum": [ "list" ] }, "MetricEnum": { "type": "string", "enum": [ "metric" ] }, "MetricResponseObjectResource": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/MetricEnum" }, "id": { "description": "The Metric ID", "type": "string" }, "attributes": { "type": "object", "properties": { "name": { "description": "The name of the metric", "type": "string", "nullable": true }, "created": { "description": "Creation time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)", "type": "string", "nullable": true }, "updated": { "description": "Last updated time in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)", "type": "string", "nullable": true }, "integration": { "description": "The integration associated with the event", "type": "object", "nullable": true } } }, "relationships": { "type": "object", "properties": { "flow-triggers": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/FlowEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } } }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "id", "attributes", "links" ] }, "ObjectLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" } }, "required": [ "self" ] }, "ProfileEnum": { "type": "string", "enum": [ "profile" ] }, "ProfileLocation": { "type": "object", "properties": { "address1": { "description": "First line of street address", "type": "string", "example": "89 E 42nd St", "nullable": true }, "address2": { "description": "Second line of street address", "type": "string", "example": "1st floor", "nullable": true }, "city": { "description": "City name", "type": "string", "example": "New York", "nullable": true }, "country": { "description": "Country name", "type": "string", "example": "United States", "nullable": true }, "latitude": { "description": "Latitude coordinate. We recommend providing a precision of four decimal places.", "example": "40.7128", "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "longitude": { "description": "Longitude coordinate. We recommend providing a precision of four decimal places.", "example": "74.0060", "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "region": { "description": "Region within a country, such as state or province", "type": "string", "example": "NY", "nullable": true }, "zip": { "description": "Zip code", "type": "string", "example": "10017", "nullable": true }, "timezone": { "description": "Time zone name. We recommend using time zones from the IANA Time Zone Database.", "type": "string", "example": "America/New_York", "nullable": true }, "ip": { "description": "IP Address", "type": "string", "example": "127.0.0.1", "nullable": true } } }, "ProfileResponseObjectResource": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ProfileEnum" }, "id": { "description": "Primary key that uniquely identifies this profile. Generated by Klaviyo.", "type": "string", "example": "01GDDKASAP8TKDDA2GRZDSVP4H", "nullable": true }, "attributes": { "type": "object", "properties": { "email": { "description": "Individual's email address", "type": "string", "example": "sarah.mason@klaviyo-demo.com", "nullable": true }, "phone_number": { "description": "Individual's phone number in E.164 format", "type": "string", "example": "+15005550006", "nullable": true }, "external_id": { "description": "A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system.", "type": "string", "nullable": true }, "first_name": { "description": "Individual's first name", "type": "string", "example": "Sarah", "nullable": true }, "last_name": { "description": "Individual's last name", "type": "string", "example": "Mason", "nullable": true }, "organization": { "description": "Name of the company or organization within the company for whom the individual works", "type": "string", "example": "Example Corporation", "nullable": true }, "locale": { "description": "The locale of the profile, in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)", "type": "string", "example": "en-US", "nullable": true }, "title": { "description": "Individual's job title", "type": "string", "example": "Regional Manager", "nullable": true }, "image": { "description": "URL pointing to the location of a profile image", "type": "string", "example": "https://images.pexels.com/photos/3760854/pexels-photo-3760854.jpeg", "nullable": true }, "created": { "description": "Date and time when the profile was created, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)", "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00", "nullable": true }, "updated": { "description": "Date and time when the profile was last updated, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)", "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00", "nullable": true }, "last_event_date": { "description": "Date and time of the most recent event the triggered an update to the profile, in ISO 8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm)", "type": "string", "format": "date-time", "example": "2022-11-08T00:00:00+00:00", "nullable": true }, "location": { "$ref": "#/components/schemas/ProfileLocation", "nullable": true }, "properties": { "description": "An object containing key/value pairs for any custom properties assigned to this profile", "type": "object", "example": { "pseudonym": "Dr. Octopus" }, "nullable": true } } }, "relationships": { "type": "object", "properties": { "lists": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/ListEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "segments": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/SegmentEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "push-tokens": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/PushTokenEnum" }, "id": { "type": "string" } } } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } } } }, "links": { "$ref": "#/components/schemas/ObjectLinks" } }, "required": [ "type", "attributes", "links" ] }, "PushTokenEnum": { "type": "string", "enum": [ "push-token" ] }, "RelationshipLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" }, "related": { "type": "string", "format": "uri" } }, "required": [ "self", "related" ] }, "SegmentEnum": { "type": "string", "enum": [ "segment" ] } }, "securitySchemes": { "Klaviyo-API-Key": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`
For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#authentication", "x-default": "Klaviyo-API-Key your-private-api-key" } } }, "tags": [ { "name": "Events", "description": "events" } ] }