Convert Experiences Reports API
Specification for different reports data that can be retrieved for experiences
OpenAPI Specification
openapi: 3.1.0
info:
title: Convert Accounts Experiences Reports API
description: 'Move your app forward with the Convert API. The Convert API allows
you to manage your Convert Experiences projects using code. The REST API is
an interface for managing and extending functionality of Convert. For
example, instead of creating and maintaining projects using the Convert
Experiences web dashboard you can create an experiment programmatically.
Additionally, if you prefer to run custom analysis on experiment results you
can leverage the API to pull data from Convert Experiences into your own
workflow. If you do not have a Convert account already, sign up for a free
developer account at https://www.convert.com/api/.
*[Convert API V1](/doc/v1) is still available and documentation can be found [here](/doc/v1) but using it is highly discouraged
as it will be phased out in the future*
'
version: 2.0.0
servers:
- url: https://api.convert.com/api/v2
description: Live API server
- url: https://apidev.convert.com/api/v2
description: DEV API server
- url: http://apidev.convert.com:5000/api/v2
description: DEV mocked API server
tags:
- name: Experiences Reports
description: Specification for different reports data that can be retrieved for experiences
paths:
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/report_settings:
get:
operationId: getExperienceReportSettings
summary: Get report settings for an experience
description: 'Retrieves the specific reporting settings for an experience. This includes configurations like confidence level,
statistical methodology (Frequentist/Bayesian), MAB strategy, primary metric, and outlier detection rules.
These settings govern how experiment results are calculated and displayed.
The Knowledge Base article "Experiment Report" (Stats Settings section) covers these.
'
tags:
- Experiences Reports
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
- name: experience_id
in: path
required: true
description: ID of the experience
schema:
type: integer
- name: report_token
in: header
required: false
description: Token to access the experience report in read-only mode.
schema:
type: string
responses:
'200':
$ref: '#/components/responses/ExperienceReportSettingsResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/aggregated_report:
post:
operationId: getExperienceAggregatedReport
summary: Get aggregated performance report for an experience
description: 'Retrieves the main performance report for a specific experience.
This report shows aggregated data for each variation, including visitor counts, conversions, conversion rates, improvement percentages,
and statistical confidence (or chance to win for Bayesian). Data is provided for all goals attached to the experience.
Supports filtering by date range and segments.
The Knowledge Base article "Experiment Report" details the metrics shown.
'
tags:
- Experiences Reports
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
- name: experience_id
in: path
required: true
description: ID of the experience
schema:
type: integer
- name: report_token
in: header
required: false
description: Token to access the experience report in read-only mode.
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/GetExperienceAggregatedReportRequest'
responses:
'200':
$ref: '#/components/responses/ExperienceAggregatedReportResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/daily_report:
post:
operationId: getExperienceDailyReport
summary: Get daily performance report for an experience
description: 'Retrieves a day-by-day breakdown of performance metrics (visitors, conversions, conversion rate, etc.) for a specific experience and goal.
This allows trend analysis and observation of how an experiment performs over time.
Supports filtering by date range and segments, and can show cumulative or non-cumulative data.
The Knowledge Base article "Experiment Report" (Graphs section) visualizes this type of data.
'
tags:
- Experiences Reports
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
- name: experience_id
in: path
required: true
description: ID of the experience
schema:
type: integer
- name: report_token
in: header
required: false
description: Token to access the experience report in read-only mode.
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/GetExperienceDailyReportRequest'
responses:
'200':
$ref: '#/components/responses/ExperienceDailyReportResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/daily_traffic_allocation:
post:
operationId: getExperienceDailyTrafficAllocation
summary: Get daily traffic allocation report for an MAB experience
description: 'Retrieves the day-by-day traffic allocation percentages for each variation in an experience that uses Multi-Armed Bandit (MAB) or auto-allocation.
This shows how Convert dynamically shifted traffic towards better-performing variations over time.
The Knowledge Base article "Multi-Armed Bandit (MAB) & Auto-Allocation in Convert" explains this feature.
'
tags:
- Experiences Reports
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
- name: experience_id
in: path
required: true
description: ID of the experience
schema:
type: integer
- name: report_token
in: header
required: false
description: Token to access the experience report in read-only mode.
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/GetExperienceDailyTrafficAllocationRequest'
responses:
'200':
$ref: '#/components/responses/ExperienceDailyTrafficAllocationResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/reset_report:
post:
operationId: resetExperienceReport
summary: Reset report data for an experience
description: 'Clears all accumulated visitor and conversion data for an experience''s report, effectively resetting its statistics to zero.
The start date of the experiment is also reset. This is useful if you want to restart data collection after making significant changes or for QA purposes.
The Knowledge Base article "Reset Experiment Data" warns: "If you want to prevent [carry-over effects], it is suggested that you clone your experiment instead of resetting the report".
'
tags:
- Experiences Reports
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
- name: experience_id
in: path
required: true
description: ID of the experience
schema:
type: integer
responses:
'200':
$ref: '#/components/responses/SuccessResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/export_report:
post:
operationId: exportExperienceReport
summary: Export an experience report (CSV/PDF)
description: 'Generates an export of an experience''s performance report in either CSV (aggregated or daily) or PDF format.
Returns a downloadable link for the generated file. Useful for offline analysis or sharing with stakeholders.
The Knowledge Base article "Experiment Report" (Export & Download section) describes this.
'
tags:
- Experiences Reports
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
- name: experience_id
in: path
required: true
description: ID of the experience
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/ExportExperienceReportRequest'
responses:
'200':
$ref: '#/components/responses/ExportExperienceReportResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/export_raw_data:
post:
operationId: exportExperienceRawData
summary: Export raw tracking data for an experience
description: 'Initiates a job to export the raw, event-level tracking data for a specific experience.
This data includes individual visitor bucketing events, conversions, and transactions.
The export is typically delivered as a link via email due to potential size.
Useful for in-depth custom analysis or importing into external data warehouses.
The Knowledge Base article "Experiment Report" (Export & Download section) mentions this.
'
tags:
- Experiences Reports
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
- name: experience_id
in: path
required: true
description: ID of the experience
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/ExportExperienceRawDataRequest'
responses:
'200':
$ref: '#/components/responses/ExportExperienceRawDataResponse'
default:
$ref: '#/components/responses/ErrorResponse'
/accounts/{account_id}/projects/{project_id}/experiences/{experience_id}/remove_report_data:
post:
operationId: removeExperienceReportData
summary: Remove specific data from an experience report
description: 'Allows for targeted deletion of report data for an experience based on date range and event type (view_experience, conversion, transaction).
For conversion and transaction events, specific goals can be targeted.
If `simulate` is true, returns a count of records that would be deleted without actual deletion. Otherwise, performs permanent deletion.
The Knowledge Base article "Remove Report Data Feature" details this.
'
tags:
- Experiences Reports
parameters:
- name: account_id
in: path
required: true
description: ID of the account that owns the retrieved/saved data
schema:
type: integer
- name: project_id
description: ID of the project to which save/retrieved data is connected
in: path
required: true
schema:
type: integer
- name: experience_id
in: path
required: true
description: ID of the experience
schema:
type: integer
requestBody:
$ref: '#/components/requestBodies/RemoveExperienceReportRequest'
responses:
'200':
$ref: '#/components/responses/RemoveExperienceReportResponse'
default:
$ref: '#/components/responses/ErrorResponse'
components:
schemas:
ReportingSegmentsCountry:
type: string
description: 'The two-letter ISO 3166-1 alpha-2 country code of the visitor, determined by IP geolocation.
Used for segmenting reports by country to analyze geographical performance.
Knowledge Base: "How Do I Target by Geographic Location Like City, Region or Country?".
'
maxLength: 2
minLength: 2
SE_ProcTypes:
type: string
description: 'The statistical methodology used for analyzing experiment results and determining winners.
- `frequentist`: Traditional hypothesis testing approach using p-values and confidence intervals (e.g., T-tests). KB: "Statistical Methods Used".
- `bayesian`: Bayesian statistical approach providing probabilities of one variation being better than another (e.g., Chance to Win). KB: "Statistical Models in Convert.com''s A/B Testing Platform".
'
enum:
- frequentist
- bayesian
RemoveExperienceReportResponseDataItem:
type: object
properties:
event:
$ref: '#/components/schemas/ExperienceReportRawDataEvents'
count:
type: integer
description: The number of records of this event type that were (or would be) deleted based on the request criteria.
ExportExperienceRawDataEvents:
description: 'Specifies the type of raw tracking events to be included in an export or targeted for removal.
- `view_experience`: Events logged when a visitor is first bucketed into an experience variation.
- `conversion`: Events logged when a visitor triggers a standard conversion goal.
- `transaction`: Events logged when a visitor triggers a revenue goal (includes transaction details).
'
type: string
enum:
- view_experience
- conversion
- transaction
ExperienceAggregatedReportResponseData:
type: object
properties:
data:
$ref: '#/components/schemas/ExperienceAggregatedReport'
SE_ProcSettings:
description: Overall settings for the statistical engine processing results for this experience.
oneOf:
- $ref: '#/components/schemas/SE_ProcSettingsFrequentist'
- $ref: '#/components/schemas/SE_ProcSettingsBayesian'
discriminator:
propertyName: stats_type
mapping:
frequentist: '#/components/schemas/SE_ProcSettingsFrequentist'
bayesian: '#/components/schemas/SE_ProcSettingsBayesian'
ReportingSegmentsSource:
type: string
description: 'The traffic source that brought the visitor to the site (e.g., ''google'', ''facebook.com'', ''direct'', ''newsletter'').
Derived from `utm_source` URL parameters or the HTTP referrer. Enables report segmentation by traffic source.
Knowledge Base: "How Do You Fill Medium, Keyword and Source Name?".
'
enum:
- campaign
- search
- referral
- direct
- ai_tool
ReportingSegmentsFilters:
type: object
description: 'A collection of filters used to segment experience report data based on various visitor attributes and traffic sources.
Applying these filters allows for deeper analysis of how different user groups interact with experience variations.
Knowledge Base: "Using Basic and Advanced Post segmentation".
'
properties:
devices:
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsDeviceCategories'
nullable: true
browsers:
description: Filter report data for visitors using one or more specified web browsers.
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsBrowser'
nullable: true
countries:
description: Filter report data for visitors from one or more specified countries (using 2-letter ISO codes).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCountry'
nullable: true
visitor_types:
description: Filter report data for 'new' or 'returning' visitors.
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsVisitorType'
nullable: true
campaigns:
description: Filter report data for visitors attributed to one or more specified marketing campaign names (from `utm_campaign`).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCampaign'
nullable: true
custom_segments:
description: Filter report data for visitors belonging to one or more specified custom Convert Audience segments (by segment ID).
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsCustomSegment'
nullable: true
sources:
description: Filter report data for visitors from one or more specified traffic sources (e.g., 'direct', 'search', 'referral').
type: array
items:
$ref: '#/components/schemas/ReportingSegmentsSource'
nullable: true
ExperienceDailyReportExtraDataItem:
type: object
properties:
type:
$ref: '#/components/schemas/ReportExtraStatsTypes'
stats:
type: array
description: An array of data points, each representing one day's aggregated value for this `type`.
items:
$ref: '#/components/schemas/StatsDataPoint'
ErrorData:
type: object
properties:
code:
type: integer
format: int32
message:
oneOf:
- type: string
- type: array
items:
type: string
fields:
oneOf:
- type: string
- type: array
items:
type: string
GetExperienceDailyTrafficAllocationRequestData:
allOf:
- $ref: '#/components/schemas/TimeRangeRequestData'
GetExperienceAggregatedReportRequestData:
allOf:
- type: object
description: Parameters needed to drill down the report.
properties:
goals:
type: array
description: 'A list of goal Id''s for which to return the reporting data.
If no ID is provided, the list of goals attached to the experience is being used;
'
items:
type: integer
nullable: true
metrics:
description: The list of metrics to return. If not provided, all available metrics will be returned.
type: array
items:
$ref: '#/components/schemas/MetricTypes'
nullable: true
- $ref: '#/components/schemas/BaseReportRequestData'
ReportExtraStatsTypes:
description: Types of aggregated daily statistics that can be included in the 'extra' section of a daily report.
type: string
enum:
- total_visitors
- avg_conversion_rate
- avg_revenue_visitor
- avg_products_ordered
StatsDataPoint:
type: object
description: Represents a single data point in a time series, typically for a specific day.
properties:
timestamp:
description: Unix timestamp (UTC, seconds since epoch) representing the start of the day for this data point.
type: number
value:
description: The numerical value of the metric or statistic for this data point (e.g., daily conversion rate, daily visitor count).
type: number
format: double
ExperienceVariationStatuses:
type: string
enum:
- stopped
- running
ExperienceAggregatedReportBase:
type: object
properties:
stats_methodology:
$ref: '#/components/schemas/SE_ProcTypes'
variations_data:
$ref: '#/components/schemas/ExperienceReportVariationsData'
RemoveExperienceReportEventTypeTransaction:
description: 'Specifies deletion of ''transaction'' (revenue) events, optionally filtered by specific goals and revenue amounts.
'
type: object
properties:
type:
type: string
description: Must be 'transaction'.
enum:
- transaction
goals:
type: array
description: '(Optional) A list of Goal IDs. If provided, only transaction events for these specific revenue goals will be deleted.
'
items:
type: integer
nullable: true
revenue_start_value:
type: number
description: (Optional) Delete only transactions where the revenue amount is greater than or equal to this value.
nullable: true
revenue_end_value:
type: number
description: (Optional) Delete only transactions where the revenue amount is less than or equal to this value.
nullable: true
required:
- type
RemoveExperienceReportEventTypeConversion:
description: 'Specifies deletion of ''conversion'' events, optionally filtered by specific goals.
'
type: object
properties:
type:
type: string
description: Must be 'conversion'.
enum:
- conversion
goals:
type: array
description: '(Optional) A list of Goal IDs. If provided, only conversion events for these specific goals will be deleted.
If omitted, conversion events for all goals (matching other criteria like date range/segments) might be deleted.
'
items:
type: integer
nullable: true
required:
- type
RemoveExperienceReportRequestData:
allOf:
- $ref: '#/components/schemas/BaseReportRequestData'
- type: object
description: Parameters needed to drill down the report.
properties:
events:
type: array
description: List of the events that would be targeted by the delete operation. If not provided, all the events would be targeted.
items:
oneOf:
- $ref: '#/components/schemas/RemoveExperienceReportEventTypeViewExperience'
- $ref: '#/components/schemas/RemoveExperienceReportEventTypeConversion'
- $ref: '#/components/schemas/RemoveExperienceReportEventTypeTransaction'
minItems: 1
simulate:
type: boolean
default: true
description: When simulate - true is passed, it will only return back an object with the numbers of how many records will be deleted, instead of deleting any records
required:
- start_time
- end_time
ExperienceAggregatedMetricNoStatistics:
allOf:
- type: object
properties:
metric_type:
type: string
enum:
- average_order_value
- average_products_per_order
required:
- metric_type
- $ref: '#/components/schemas/BaseMetricNoStatistics'
ExportExperienceRawDataResponseData:
type: object
properties:
data:
description: Contains the ID of the asynchronous job processing the raw data export.
type: object
properties:
jobId:
description: 'A unique identifier for the background job that is preparing the raw data export.
The user is typically notified (e.g., via email) with a download link once the job is complete.
'
type: string
SimpleAudienceSegment:
type: object
properties:
id:
description: The unique numerical identifier of the segment (audience).
type: integer
name:
description: The user-defined, friendly name of the segment.
type: string
SE_ProcSettingsFrequentist:
allOf:
- $ref: '#/components/schemas/SE_ProcSettingsBase'
- type: object
description: Stats Engine Settings needed for the Frequentist processing
properties:
stats_type:
enum:
- frequentist
confidence:
description: Confidence value to be used (in percent)
type: number
minimum: 50
maximum: 99
multipleOf: 1
power:
description: Statistical power value to be used (in percent)
type: number
minimum: 10
maximum: 99
multipleOf: 1
test_type:
description: The type of test applied to the data
type: string
default: two_tails
enum:
- one_tail
- one_tail_left
- one_tail_right
- two_tails
- sequential
multiple_comparison_correction:
description: Multiple comparison correction
type: string
enum:
- none
- bonferroni
- sidak
power_calculation_type:
description: Power calculation type
type: string
default: dynamic_mde
enum:
- dynamic_mde
- fixed_mde
fixed_mde:
description: Fixed minimum detectable effect (corresponding to the relative improvement in percent)
type: number
minimum: 0
maximum: 10000
mab_settings:
allOf:
- $ref: '#/components/schemas/SE_MabSettings'
nullable: true
MetricTypes:
type: string
description: 'The primary types of performance metrics calculated by the reporting engine for each goal.
- `conversion_rate`: The percentage of visitors who completed the goal (Conversions / Visitors).
- `avg_revenue_visitor`: Average Revenue Per Visitor (RPV = Total Revenue / Total Visitors). Applicable for revenue goals.
- `avg_products_ordered_visitor`: Average Products Per Visitor (APPV = Total Products Ordered / Total Visitors). Applicable for revenue goals tracking product counts.
- `average_order_value`: Average Order Value (AOV = Total Revenue / Total Conversions). Applicable for revenue goals tracking order value.
- `average_products_per_order`: Average Products Per Order (APPO = Total Products Ordered Per Visitor / Total Conversions). Applicable for revenue goals tracking product counts.
Knowledge Base: "Understanding Report Metrics in Convert".
'
enum:
- conversion_rate
- avg_revenue_visitor
- avg_products_ordered_visitor
- average_order_value
- average_products_per_order
UTC_Offset:
type: integer
description: 'The time offset from Coordinated Universal Time (UTC) in seconds.
For example, UTC-5 (EST) would be -18000. UTC+2 would be 7200.
Used for interpreting or displaying date/time information according to a specific timezone.
'
default: 0
minimum: -43200
maximum: 50400
ExperienceAggregatedMetricReportFrequentist:
oneOf:
- $ref: '#/components/schemas/ExperienceAggregatedMetricFrequentist'
- $ref: '#/components/schemas/ExperienceAggregatedMetricNoStatistics'
discriminator:
propertyName: metric_type
mapping:
conversion_rate: '#/components/schemas/ExperienceAggregatedMetricFrequentist'
avg_revenue_visitor: '#/components/schemas/ExperienceAggregatedMetricFrequentist'
avg_products_ordered_visitor: '#/components/schemas/ExperienceAggregatedMetricFrequentist'
average_order_value: '#/components/schemas/ExperienceAggregatedMetricNoStatistics'
average_products_per_order: '#/components/schemas/ExperienceAggregatedMetricNoStatistics'
ExperienceVariationBase:
type: object
properties:
name:
description: A user-defined, friendly name for the variation (e.g., "Original Homepage", "Variation B - Green Button", "Personalized Offer for New Users"). This name appears in reports and the Convert UI.
type: string
maxLength: 200
description:
description: An optional, more detailed explanation of what this variation entails or what changes it implements compared to the original or other variations.
type: string
maxLength: 2000
nullable: true
is_baseline:
type: boolean
description: 'If `true`, this variation is considered the baseline (control) against which other variations in the experience are compared for performance.
Typically, the "Original" variation is the baseline. Only one variation per experience can be the baseline.
Knowledge Base: "What is a Baseline?"
'
traffic_distribution:
description: 'The percentage of eligible traffic allocated to this specific variation.
The sum of `traffic_distribution` for all active variations within an experience should ideally be 100% of the traffic allocated to the experience itself.
For Multi-Armed Bandit (MAB) experiences, this value may be dynamically adjusted by the system.
Knowledge Base: "What is an Traffic Distribution?"
'
type: number
minimum: 0
maximum: 100
multipleOf: 0.0001
key:
description: 'A unique, machine-readable key or identifier for this variation within the project.
Often auto-generated from the name if not specified, but can be user-defined for easier programmatic reference (e.g., in Full Stack SDKs).
Example: "control", "treatment_A".
'
type: string
maxLength: 32
concurrency_key:
$ref: '#/components/schemas/ConcurrencyKey'
ExperienceAggregatedReportFrequentist:
allOf:
- $ref: '#/components/schemas/ExperienceAggregatedReportBase'
- type: object
properties:
stats_methodology:
type: string
enum:
- frequentist
reportData:
type: array
description: List of data for each of the analyzed goals
items:
$ref: '#/components/schemas/ExperienceAggregatedGoalReportFrequentist'
BaseReportRequestData:
allOf:
- $ref: '#/components/schemas/TimeRangeRequestData'
- type: object
description: Base Parameters needed to drill down the reports.
properties:
segments:
$ref: '#/components/schemas/ReportingSegmentsFilters'
stats_engine_processing:
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convert/refs/heads/main/openapi/convert-experiences-reports-api-openapi.yml