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'
                  - '2024-01-07T00:00:00+00:00'
              required:
              - results
              - date_times
          required:
          - type
          - attributes
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    FlowSeriesReportEnum:
      type: string
      enum:
      - flow-series-report
    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
    SegmentValuesRequestDTOResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/SegmentValuesReportEnum'
        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'
            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
      required:
      - type
      - attributes
    PostFormValuesResponseDTO:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/FormValuesReportEnum'
            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:
                      form_id: abc123
                      form_version_id: 012tuy
                    statistics:
                      viewed_form: 90
                      submits: 9
                      submit_rate: 0.1
                  - groupings:
                      form_id: abc123
                      form_version_id: 756ghi
                    statistics:
                      viewed_form: 10
                      submits: 1
                      submit_rate: 0.1
              required:
              - results
          required:
          - type
          - attributes
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    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.

                    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:
                      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
    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
    FlowEnum:
      type: string
      enum:
      - flow
    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 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
          - interval
          - conversion_metric_id
      required:
      - type
      - attributes
    CampaignEnum:
      type: string
      enum:
      - campaign
    FormValuesRequestDTO:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/FormValuesRequestDTOResourceObject'
      required:
      - data
    FlowMessageEnum:
      type: string
      enum:
      - flow-message
    FormSeriesRequestDTO:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/FormSeriesRequestDTOResourceObject'
      required:
      - data
    SegmentValuesReportEnum:
      type: string
      enum:
      - segment-values-report
    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
    ObjectLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
      required:
      - self
    SegmentSeriesReportEnum:
      type: string
      enum:
      - segment-series-report
    SegmentSeriesRequestDTO:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/SegmentSeriesRequestDTOResourceObject'
      required:
      - data
    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
    FlowSeriesRequestDTO:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/FlowSeriesRequestDTOResourceObject'
      required:
      - data
    FlowValuesReportEnum:
      type: string
      enum:
      - flow-values-report
    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
              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
      required:
      - type
      - attributes
    CampaignValuesRequestDTO:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CampaignValuesRequestDTOResourceObject'
      required:
      - data
  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
  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`<br>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
x-readme:
  explorer-enabled: false
  proxy-enabled: true
  samples-enabled: true