openapi: 3.0.2
info:
title: Klaviyo Accounts Reporting 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: []
tags:
- name: Reporting
description: reporting
paths:
/api/campaign-values-reports:
post:
operationId: query_campaign_values
summary: Query Campaign Values
description: 'Returns the requested campaign analytics values data<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `2/m`<br>Daily: `225/d`
**Scopes:**
`campaigns:read`'
parameters:
- 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/CampaignValuesRequestDTO'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/PostCampaignValuesResponseDTO'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Reporting
x-klaviyo-operation-aliases:
- create_campaign_value_report
- create_campaign_values_report
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 1/s
steady: 2/m
daily: 225/d
x-klaviyo-scopes:
- campaigns:read
/api/flow-values-reports:
post:
operationId: query_flow_values
summary: Query Flow Values
description: 'Returns the requested flow analytics values data<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `2/m`<br>Daily: `225/d`
**Scopes:**
`flows:read`'
parameters:
- 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
/api/flow-series-reports:
post:
operationId: query_flow_series
summary: Query Flow Series
description: 'Returns the requested flow analytics series data<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `2/m`<br>Daily: `225/d`
**Scopes:**
`flows:read`'
parameters:
- 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/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
/api/form-values-reports:
post:
operationId: query_form_values
summary: Query Form Values
description: 'Returns the requested form analytics values data.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `2/m`<br>Daily: `225/d`
**Scopes:**
`forms:read`'
parameters:
- 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/FormValuesRequestDTO'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/PostFormValuesResponseDTO'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Reporting
x-klaviyo-operation-aliases:
- create_form_value_report
- create_form_values_report
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 1/s
steady: 2/m
daily: 225/d
x-klaviyo-scopes:
- forms:read
/api/form-series-reports:
post:
operationId: query_form_series
summary: Query Form Series
description: 'Returns the requested form analytics series data.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `2/m`<br>Daily: `225/d`
**Scopes:**
`forms:read`'
parameters:
- 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/FormSeriesRequestDTO'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/PostFormSeriesResponseDTO'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Reporting
x-klaviyo-operation-aliases:
- create_form_sery_report
- create_form_series_report
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 1/s
steady: 2/m
daily: 225/d
x-klaviyo-scopes:
- forms:read
/api/segment-values-reports:
post:
operationId: query_segment_values
summary: Query Segment Values
description: 'Returns the requested segment analytics values data.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `2/m`<br>Daily: `225/d`
**Scopes:**
`segments:read`'
parameters:
- 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/SegmentValuesRequestDTO'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/PostSegmentValuesResponseDTO'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Reporting
x-klaviyo-operation-aliases:
- create_segment_value_report
- create_segment_values_report
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 1/s
steady: 2/m
daily: 225/d
x-klaviyo-scopes:
- segments:read
/api/segment-series-reports:
post:
operationId: query_segment_series
summary: Query Segment Series
description: 'Returns the requested segment analytics series data.<br><br>*Rate limits*:<br>Burst: `1/s`<br>Steady: `2/m`<br>Daily: `225/d`
**Scopes:**
`segments:read`'
parameters:
- 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/SegmentSeriesRequestDTO'
responses:
'200':
description: Success
content:
application/vnd.api+json:
schema:
$ref: '#/components/schemas/PostSegmentSeriesResponseDTO'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
tags:
- Reporting
x-klaviyo-operation-aliases:
- create_segment_sery_report
- create_segment_series_report
x-klaviyo-pre-release: None
x-klaviyo-ratelimit:
burst: 1/s
steady: 2/m
daily: 225/d
x-klaviyo-scopes:
- segments:read
components:
schemas:
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.
Each 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
FlowValuesRequestDTO:
type: object
properties:
data:
$ref: '#/components/schemas/FlowValuesRequestDTOResourceObject'
required:
- data
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
RelationshipLinks:
type: object
properties:
self:
type: string
format: uri
related:
type: string
format: uri
required:
- self
- related
PostFormSeriesResponseDTO:
type: object
properties:
data:
type: object
properties:
type:
$ref: '#/components/schemas/FormSeriesReportEnum'
attributes:
type: object
properties:
results:
description: 'An array of all the returned values data.
Each object in the array represents one unique grouping and the results for that grouping.
Each value in the results array corresponds to the date time at the same index.'
type: array
items:
$ref: '#/components/schemas/SeriesData'
example:
- groupings:
form_id: abc123
statistics:
viewed_form:
- 100
- 120
- 140
submits:
- 20
- 22
- 28
- groupings:
form_id: def456
statistics:
viewed_form:
- 200
- 300
- 400
submits:
- 20
- 25
- 30
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
required:
- type
- attributes
links:
$ref: '#/components/schemas/ObjectLinks'
required:
- data
CampaignValuesRequestDTOResourceObject:
type: object
properties:
type:
$ref: '#/components/schemas/CampaignValuesReportEnum'
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.
Allowed group-bys are campaign_id, campaign_message_id, campaign_message_name, group, group_name, send_channel, tag_id, tag_name, text_message_format, variation, variation_name.
If not passed in, the data will be grouped by campaign_id, campaign_message_id, send_channel.
The following group by attributes are required: campaign_id, campaign_message_id'
type: array
items:
type: string
enum:
- campaign_id
- campaign_message_id
- campaign_message_name
- group
- group_name
- send_channel
- tag_id
- tag_name
- text_message_format
- variation
- variation_name
description: Attributes to represent what is being grouped by / filtered on for Campaigns
nullable: true
filter:
description: 'API filter string used to filter the query.
Scalar attributes (send_channel, campaign_id, campaign_message_id, campaign_message_name, variation, variation_name, text_message_format): Supported operators: equals, contains-any.
List attributes (tag_id, tag_name): Supported operators: contains-any, contains-all.
Only one filter can be used per attribute.
Only AND can be used as a combination operator.
Max of 100 items per list filter.
When filtering on send_channel, allowed values are email, sms, push-notification, whatsapp.'
type: string
example: and(equals(campaign_id,"abc123"),contains-any(send_channel,["email","sms"]))
nullable: true
required:
- statistics
- timeframe
- conversion_metric_id
required:
- type
- attributes
SegmentValuesRequestDTO:
type: object
properties:
data:
$ref: '#/components/schemas/SegmentValuesRequestDTOResourceObject'
required:
- data
FormSeriesRequestDTOResourceObject:
type: object
properties:
type:
$ref: '#/components/schemas/FormSeriesReportEnum'
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:
- closed_form
- closed_form_uniques
- qualified_form
- qualified_form_uniques
- submit_rate
- submits
- submitted_form_step
- submitted_form_step_uniques
- viewed_form
- viewed_form_step
- viewed_form_step_uniques
- viewed_form_uniques
description: Defined form reporting metric
example:
- viewed_form
- submit_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.
If hourly is used, the timeframe cannot be longer than 7 days.
If daily is used, the timeframe cannot be longer than 60 days.
If monthly is used, the timeframe cannot be longer than 52 weeks.'
type: string
example: weekly
enum:
- daily
- hourly
- monthly
- weekly
group_by:
description: 'List of attributes to group the data by.
Allowed group-bys are form_id, form_version_id.
If not passed in, the data will be grouped by form_id.
If a group by has prerequisites, they must be passed in together. The prerequisites for form_version_id is form_id'
type: array
items:
type: string
enum:
- form_id
- form_version_id
description: Attributes to represent what is being grouped by for Forms
nullable: true
filter:
description: 'API filter string used to filter the query.
Allowed filters are form_id, form_version_id.
Allowed operators are equals, any.
Only one filter can be used per attribute, only AND can be used as a combination operator.
Max of 100 messages per ANY filter.'
type: string
example: and(equals(form_id,"abc123"),any(form_version_id,["xyz123","ghi456"]))
nullable: true
required:
- statistics
- timeframe
- interval
required:
- type
- attributes
FormValuesReportEnum:
type: string
enum:
- form-values-report
SegmentSeriesRequestDTOResourceObject:
type: object
properties:
type:
$ref: '#/components/schemas/SegmentSeriesReportEnum'
attributes:
type: object
properties:
statistics:
description: List of statistics to query for.
type: array
items:
type: string
enum:
- members_added
- members_removed
- net_members_changed
- total_members
description: Defined segment reporting metric
example:
- total_members
- net_members_changed
timeframe:
description: 'The time frame to pull data from (Max length: 1 year). Data is unavailable before June 1st, 2023. Please use a time frame after this date. 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.
If hourly is used, the timeframe cannot be longer than 7 days.
If daily is used, the timeframe cannot be longer than 60 days.
If monthly is used, the timeframe cannot be longer than 52 weeks.'
type: string
example: weekly
enum:
- daily
- hourly
- monthly
- weekly
filter:
description: 'API filter string used to filter the query.
Allowed filters are segment_id.
Allowed operators are equals, any.
Only one filter can be used per attribute.
Max of 100 messages per ANY filter.'
type: string
example: any(segment_id,["xyz123","ghi456"])
nullable: true
required:
- statistics
- timeframe
- interval
required:
- type
- attributes
CampaignValuesReportEnum:
type: string
enum:
- campaign-values-report
FormSeriesReportEnum:
type: string
enum:
- form-series-report
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
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.
Allowed 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.
If not passed in, the data will be grouped by flow_id, flow_message_id, send_channel.
The 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.
Scalar attributes (flow_id, flow_name, send_channel, flow_message_id, flow_message_name, text_message_format, variation, variation_name): Supported operators: equals, contains-any.
List attributes (tag_id, tag_name): Supported operators: contains-any, contains-all.
Only one filter can be used per attribute.
Only AND can be used as a combination operator.
Max of 100 items per list filter.
When 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
PostSegmentSeriesResponseDTO:
type: object
properties:
data:
type: object
properties:
type:
$ref: '#/components/schemas/SegmentSeriesReportEnum'
attributes:
type: object
properties:
results:
description: 'An array of all the returned values data.
Each object in the array represents one unique grouping and the results for that grouping.
Each value in the results array corresponds to the date time at the same index.'
type: array
items:
$ref: '#/components/schemas/SeriesData'
example:
- groupings:
segment_id: abc123
statistics:
total_members:
- 120
- 185
- 240
net_members_changed:
- 40
- 62
- 88
- groupings:
segment_id: def456
statistics:
total_members:
- 103
- 163
- 213
net_members_changed:
- 36
- 66
- 86
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'
# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/klaviyo/refs/heads/main/openapi/klaviyo-reporting-api-openapi.yml