{ "openapi": "3.0.2", "info": { "title": "Klaviyo API", "version": "2026-07-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-series-reports": { "post": { "operationId": "query_flow_series", "summary": "Query Flow Series", "description": "Returns the requested flow analytics series 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_series.json)", "parameters": [ { "name": "fields[flow-series-report]", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-15/reference/api-overview#sparse-fieldsets", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "date_times", "id", "results" ] } }, "explode": false }, { "name": "page_cursor", "in": "query", "description": "For more information please visit https://developers.klaviyo.com/en/v2026-07-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-07-15" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/FlowSeriesRequestDTO" } } } }, "responses": { "200": { "description": "Success", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/PostFlowSeriesResponseDTO" } } } }, "4XX": { "$ref": "#/components/responses/ClientError" }, "5XX": { "$ref": "#/components/responses/ServerError" } }, "tags": [ "Reporting" ], "x-klaviyo-operation-aliases": [ "create_flow_sery_report", "create_flow_series_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" ] }, "FlowSeriesReportEnum": { "type": "string", "enum": [ "flow-series-report" ] }, "FlowSeriesRequestDTO": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlowSeriesRequestDTOResourceObject" } }, "required": [ "data" ] }, "FlowSeriesRequestDTOResourceObject": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FlowSeriesReportEnum" }, "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" } ] }, "interval": { "description": "The interval used to aggregate data within the series request.\nIf hourly is used, the timeframe cannot be longer than 7 days.\nIf daily is used, the timeframe cannot be longer than 60 days.\nIf monthly is used, the timeframe cannot be longer than 52 weeks.", "type": "string", "example": "weekly", "enum": [ "daily", "hourly", "monthly", "weekly" ] }, "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", "interval", "conversion_metric_id" ] } }, "required": [ "type", "attributes" ] }, "ObjectLinks": { "type": "object", "properties": { "self": { "type": "string", "format": "uri" } }, "required": [ "self" ] }, "PostFlowSeriesResponseDTO": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FlowSeriesReportEnum" }, "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.\nEach value in the results array corresponds to the date time at the same index.", "type": "array", "items": { "$ref": "#/components/schemas/SeriesData" }, "example": [ { "groupings": { "flow_id": "XVTP5Q", "send_channel": "email", "flow_message_id": "01GMRWDSA0ARTAKE1SFX8JGXAY" }, "statistics": { "opens": [ 123, 156, 144 ], "open_rate": [ 0.8253, 0.8722, 0.8398 ] } }, { "groupings": { "flow_id": "XVTP5Q", "send_channel": "email", "flow_message_id": "01GJTHNWVG93F3KNX71SJ4FDBB" }, "statistics": { "opens": [ 97, 98, 65 ], "open_rate": [ 0.7562, 0.761, 0.688 ] } } ] }, "date_times": { "description": "An array of date times which correspond to the equivalent index in the results data.", "type": "array", "items": { "type": "string", "format": "date-time" }, "example": [ "2024-01-05T00:00:00+00:00", "2024-01-06T00:00:00+00:00", "2024-01-07T00:00:00+00:00" ] } }, "required": [ "results", "date_times" ] }, "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" ] }, "SeriesData": { "type": "object", "properties": { "groupings": { "description": "Applied groupings and the values for this object", "type": "object" }, "statistics": { "description": "Requested statistics and their series result", "type": "object" } }, "required": [ "groupings", "statistics" ] }, "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" ] } }, "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-07-15/reference/api-overview#authentication", "x-default": "Klaviyo-API-Key your-private-api-key" } } }, "tags": [ { "name": "Reporting", "description": "reporting" } ] }