{
"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/flow-values-reports": {
"post": {
"operationId": "query_flow_values",
"summary": "Query Flow Values",
"description": "Returns the requested flow analytics values data
*Rate limits*:
Burst: `1/s`
Steady: `2/m`
Daily: `225/d`\n\n**Scopes:**\n`flows:read`\n\n[OpenAPI Spec](https://raw.githubusercontent.com/klaviyo/openapi/main/openapi/stable/apis/query_flow_values.json)",
"parameters": [
{
"name": "fields[flow-values-report]",
"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",
"results"
]
}
},
"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": "revision",
"in": "header",
"description": "API endpoint revision (format: YYYY-MM-DD[.suffix])",
"required": true,
"schema": {
"type": "string",
"default": "2026-04-15"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/vnd.api+json": {
"schema": {
"$ref": "#/components/schemas/FlowValuesRequestDTO"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/vnd.api+json": {
"schema": {
"$ref": "#/components/schemas/PostFlowValuesResponseDTO"
}
}
}
},
"4XX": {
"$ref": "#/components/responses/ClientError"
},
"5XX": {
"$ref": "#/components/responses/ServerError"
}
},
"tags": [
"Reporting"
],
"x-klaviyo-operation-aliases": [
"create_flow_value_report",
"create_flow_values_report"
],
"x-klaviyo-pre-release": "None",
"x-klaviyo-ratelimit": {
"burst": "1/s",
"steady": "2/m",
"daily": "225/d"
},
"x-klaviyo-scopes": [
"flows: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": {
"CustomTimeframe": {
"type": "object",
"properties": {
"start": {
"description": "A datetime that represents the start of a custom time frame. Offset is ignored and the company timezone is used.",
"type": "string",
"format": "date-time",
"example": "2022-11-08T00:00:00+00:00"
},
"end": {
"description": "A datetime that represents the end of a custom time frame. Offset is ignored and the company timezone is used.",
"type": "string",
"format": "date-time",
"example": "2022-11-08T00:00:00+00:00"
}
},
"required": [
"start",
"end"
]
},
"FlowEnum": {
"type": "string",
"enum": [
"flow"
]
},
"FlowMessageEnum": {
"type": "string",
"enum": [
"flow-message"
]
},
"FlowValuesReportEnum": {
"type": "string",
"enum": [
"flow-values-report"
]
},
"FlowValuesRequestDTO": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/FlowValuesRequestDTOResourceObject"
}
},
"required": [
"data"
]
},
"FlowValuesRequestDTOResourceObject": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/FlowValuesReportEnum"
},
"attributes": {
"type": "object",
"properties": {
"statistics": {
"description": "List of statistics to query for. All rate statistics will be returned in fractional form [0.0, 1.0]",
"type": "array",
"items": {
"type": "string",
"enum": [
"average_order_value",
"bounce_rate",
"bounced",
"bounced_or_failed",
"bounced_or_failed_rate",
"click_rate",
"click_to_open_rate",
"clicks",
"clicks_unique",
"conversion_rate",
"conversion_uniques",
"conversion_value",
"conversions",
"delivered",
"delivery_rate",
"failed",
"failed_rate",
"message_segment_count_sum",
"open_rate",
"opens",
"opens_unique",
"recipients",
"revenue_per_recipient",
"spam_complaint_rate",
"spam_complaints",
"text_message_credit_usage_amount",
"text_message_roi",
"text_message_spend",
"unsubscribe_rate",
"unsubscribe_uniques",
"unsubscribes"
],
"description": "Defined reporting metric"
},
"example": [
"opens",
"open_rate"
]
},
"timeframe": {
"description": "The time frame to pull data from (Max length: 1 year). See [available time frames](https://developers.klaviyo.com/en/reference/reporting_api_overview#available-time-frames).",
"oneOf": [
{
"$ref": "#/components/schemas/Timeframe"
},
{
"$ref": "#/components/schemas/CustomTimeframe"
}
]
},
"conversion_metric_id": {
"description": "ID of the metric to be used for conversion statistics",
"type": "string",
"example": "RESQ6t"
},
"group_by": {
"description": "List of attributes to group the data by.\nAllowed group-bys are flow_id, flow_message_id, flow_message_name, flow_name, send_channel, tag_id, tag_name, text_message_format, variation, variation_name.\nIf not passed in, the data will be grouped by flow_id, flow_message_id, send_channel.\nThe following group by attributes are required: flow_message_id, flow_id.",
"type": "array",
"items": {
"type": "string",
"enum": [
"flow_id",
"flow_message_id",
"flow_message_name",
"flow_name",
"send_channel",
"tag_id",
"tag_name",
"text_message_format",
"variation",
"variation_name"
],
"description": "Attributes to represent what is being grouped by for Flows"
},
"nullable": true
},
"filter": {
"description": "API filter string used to filter the query.\nScalar attributes (flow_id, flow_name, send_channel, flow_message_id, flow_message_name, text_message_format, variation, variation_name): Supported operators: equals, contains-any.\nList attributes (tag_id, tag_name): Supported operators: contains-any, contains-all.\nOnly one filter can be used per attribute.\nOnly AND can be used as a combination operator.\nMax of 100 items per list filter.\nWhen filtering on send_channel, allowed values are email, sms, push-notification, whatsapp.",
"type": "string",
"example": "and(equals(flow_id,\"abc123\"),contains-any(send_channel,[\"email\",\"sms\"]))",
"nullable": true
}
},
"required": [
"statistics",
"timeframe",
"conversion_metric_id"
]
}
},
"required": [
"type",
"attributes"
]
},
"ObjectLinks": {
"type": "object",
"properties": {
"self": {
"type": "string",
"format": "uri"
}
},
"required": [
"self"
]
},
"PostFlowValuesResponseDTO": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"type": {
"$ref": "#/components/schemas/FlowValuesReportEnum"
},
"attributes": {
"type": "object",
"properties": {
"results": {
"description": "An array of all the returned values data.\nEach object in the array represents one unique grouping and the results for that grouping.",
"type": "array",
"items": {
"$ref": "#/components/schemas/ValuesData"
},
"example": [
{
"groupings": {
"flow_id": "XVTP5Q",
"send_channel": "email",
"flow_message_id": "01GMRWDSA0ARTAKE1SFX8JGXAY"
},
"statistics": {
"opens": 123,
"open_rate": 0.8253
}
},
{
"groupings": {
"flow_id": "XVTP5Q",
"send_channel": "email",
"flow_message_id": "01GJTHNWVG93F3KNX71SJ4FDBB"
},
"statistics": {
"opens": 97,
"open_rate": 0.7562
}
}
]
}
},
"required": [
"results"
]
},
"relationships": {
"type": "object",
"properties": {
"flows": {
"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"
}
}
},
"flow-messages": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"type": {
"$ref": "#/components/schemas/FlowMessageEnum"
},
"id": {
"type": "string"
}
}
}
},
"links": {
"$ref": "#/components/schemas/RelationshipLinks"
}
}
}
}
}
},
"required": [
"type",
"attributes"
]
},
"links": {
"$ref": "#/components/schemas/ObjectLinks"
}
},
"required": [
"data"
]
},
"RelationshipLinks": {
"type": "object",
"properties": {
"self": {
"type": "string",
"format": "uri"
},
"related": {
"type": "string",
"format": "uri"
}
},
"required": [
"self",
"related"
]
},
"Timeframe": {
"type": "object",
"properties": {
"key": {
"description": "Pre-defined key that represents a set timeframe",
"type": "string",
"enum": [
"last_12_months",
"last_30_days",
"last_365_days",
"last_3_months",
"last_7_days",
"last_90_days",
"last_month",
"last_week",
"last_year",
"this_month",
"this_week",
"this_year",
"today",
"yesterday"
]
}
},
"required": [
"key"
]
},
"ValuesData": {
"type": "object",
"properties": {
"groupings": {
"description": "Applied groupings and the values for this object",
"type": "object"
},
"statistics": {
"description": "Requested statistics and their values results",
"type": "object"
}
},
"required": [
"groupings",
"statistics"
]
}
},
"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": "Reporting",
"description": "reporting"
}
]
}