Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
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:
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
PostSegmentValuesResponseDTO:
type: object
properties:
data:
type: object
properties:
type:
$ref: '#/components/schemas/SegmentValuesReportEnum'
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:
segment_id: abc123
statistics:
total_members: 120
net_members_changed: 53
- groupings:
segment_id: def123
statistics:
total_members: 250
net_members_changed: 113
required:
- results
required:
- type
- attributes
links:
$ref: '#/components/schemas/ObjectLinks'
required:
- data
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
PostCampaignValuesResponseDTO:
type: object
properties:
data:
type: object
properties:
type:
$ref: '#/components/schemas/CampaignValuesReportEnum'
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:
send_channel: email
campaign_id: 01GMRWDSA0ARTAKE1SFX8JGXAY
campaign_message_id: 01GMRWDSA0ARTAKE1SFX8JGXAY
statistics:
opens: 123
open_rate: 0.8253
- groupings:
send_channel: email
campaign_id: 01GJTHNWVG93F3KNX71SJ4FDBB
campaign_message_id: 01GJTHNWVG93F3KNX71SJ4FDBB
statistics:
opens: 97
open_rate: 0.7562
required:
- results
relationships:
type: object
properties:
campaigns:
type: object
properties:
data:
type: array
items:
type: object
required:
- type
- id
properties:
type:
$ref: '#/components/schemas/CampaignEnum'
id:
type: string
links:
$ref: '#/components/schemas/RelationshipLinks'
required:
- type
- attributes
links:
$ref: '#/components/schemas/ObjectLinks'
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.
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
- 'null'
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
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
- 'null'
example: and(equals(flow_id,"abc123"),contains-any(send_channel,["email","sms"]))
required:
- statistics
- timeframe
- conversion_metric_id
required:
- type
- attributes
FlowEnum:
type: string
enum:
- flow
CampaignValuesReportEnum:
type: string
enum:
- campaign-values-report
FlowSeriesRequestDTO:
type: object
properties:
data:
$ref: '#/components/schemas/FlowSeriesRequestDTOResourceObject'
required:
- data
FormValuesRequestDTOResourceObject:
type: object
properties:
type:
$ref: '#/components/schemas/FormValuesReportEnum'
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'
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
- 'null'
items:
type: string
enum:
- form_id
- form_version_id
description: Attributes to represent what is being grouped by for Forms
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
- 'null'
example: and(equals(form_id,"abc123"),any(form_version_id,["xyz123","ghi456"]))
required:
- statistics
- timeframe
required:
- type
- attributes
CampaignValuesRequestDTO:
type: object
properties:
data:
$ref: '#/components/schemas/CampaignValuesRequestDTOResourceObject'
required:
- data
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'
- '2024-01-07T00:00:00+00:00'
required:
- results
- date_times
required:
- type
- attributes
links:
$ref: '#/components/schemas/ObjectLinks'
required:
- data
SegmentSeriesRequestDTO:
type: object
properties:
data:
$ref: '#/components/schemas/SegmentSeriesRequestDTOResourceObject'
required:
- data
SegmentValuesRequestDTO:
type: object
properties:
data:
$ref: '#/components/schemas/SegmentValuesRequestDTOResourceObject'
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
- 'null'
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
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
- 'null'
example: and(equals(campaign_id,"abc123"),contains-any(send_channel,["email","sms"]))
required:
- statistics
- timeframe
- conversion_metric_id
required:
- type
- attributes
RelationshipLinks:
type: object
properties:
self:
type: string
format: uri
related:
type: string
format: uri
required:
- self
- related
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.
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
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
# --- 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