openapi: 3.0.2 info: title: A/B Testing API summary: >- The Algolia A/B Testing API lets you manage your Algolia A/B tests to optimize your search experience description: > ## Base URLs Base URLs for the A/B testing API: - `https://analytics.us.algolia.com` - `https://analytics.de.algolia.com` - `https://analytics.algolia.com` (routes requests to the closest of the above servers, based on your geographical location) Use the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics). **All requests must use HTTPS.** ## Availability and authentication Access to the A/B testing API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing). Add these headers to authenticate requests: - `x-algolia-application-id`. Your Algolia application ID. - `x-algolia-api-key`. An API key with the necessary permissions to make the request. The required access control list (ACL) to make a request is listed in each endpoint's reference. You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys). ## Rate limits You can make up to **100 requests per minute per app** to the A/B testing API. The response includes headers with information about the limits. ## Parameters Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding). Non-ASCII characters must be UTF-8 encoded. Plus characters (`+`) are interpreted as spaces. ## Response status and errors The A/B testing API returns JSON responses. Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response. Successful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses. Error responses have a `message` property with more information. ## Version The current version of the A/B Testing API is version 3, indicated by the `/3/` in each endpoint's URL. version: 3.0.0 servers: - url: https://analytics.{region}.algolia.com variables: region: enum: - us - de default: us - url: https://analytics.algolia.com security: - appId: [] apiKey: [] tags: - name: abtest x-displayName: A/B testing description: > Manage A/B tests. A/B tests are configurations one or more indices, usually your production index and an index with different settings that you want to test. externalDocs: url: https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing description: A/B testing. paths: /{path}: get: operationId: customGet summary: Send requests to the Algolia REST API description: This method lets you send requests to the Algolia REST API. parameters: - $ref: '#/components/parameters/PathInPath' - $ref: '#/components/parameters/Parameters' responses: '200': description: OK content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' tags: - abtesting-v3 post: operationId: customPost requestBody: description: Parameters to send with the custom request. content: application/json: schema: type: object summary: Send requests to the Algolia REST API description: This method lets you send requests to the Algolia REST API. parameters: - $ref: '#/components/parameters/PathInPath' - $ref: '#/components/parameters/Parameters' responses: '200': description: OK content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' tags: - abtesting-v3 put: operationId: customPut requestBody: description: Parameters to send with the custom request. content: application/json: schema: type: object summary: Send requests to the Algolia REST API description: This method lets you send requests to the Algolia REST API. parameters: - $ref: '#/components/parameters/PathInPath' - $ref: '#/components/parameters/Parameters' responses: '200': description: OK content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' tags: - abtesting-v3 delete: operationId: customDelete summary: Send requests to the Algolia REST API description: This method lets you send requests to the Algolia REST API. parameters: - $ref: '#/components/parameters/PathInPath' - $ref: '#/components/parameters/Parameters' responses: '200': description: OK content: application/json: schema: type: object '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' tags: - abtesting-v3 /3/abtests: post: tags: - abtesting-v3 operationId: addABTests x-acl: - editSettings summary: Create an A/B test description: Creates a new A/B test. requestBody: required: true content: application/json: schema: title: addABTestsRequest type: object additionalProperties: false properties: name: $ref: '#/components/schemas/name' hypothesis: $ref: '#/components/schemas/hypothesis' variants: type: array description: A/B test variants. minItems: 2 items: $ref: '#/components/schemas/AddABTestsVariant' metrics: type: array description: >- A/B test metrics involved in the test. Only these metrics will be considered when calculating results. items: $ref: '#/components/schemas/createMetric' configuration: $ref: '#/components/schemas/ABTestConfiguration' endAt: $ref: '#/components/schemas/endAt' required: - name - variants - metrics - endAt responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/ABTestResponse' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' get: tags: - abtesting-v3 operationId: listABTests x-acl: - analytics summary: List all A/B tests description: Lists all A/B tests you configured for this application. parameters: - name: offset in: query description: Position of the first item to return. required: false schema: type: integer default: 0 minimum: 0 - name: limit in: query description: Number of items to return. required: false schema: type: integer default: 10 - name: indexPrefix in: query description: >- Index name prefix. Only A/B tests for indices starting with this string are included in the response. example: dev_ schema: type: string - name: indexSuffix in: query description: >- Index name suffix. Only A/B tests for indices ending with this string are included in the response. example: _development schema: type: string - name: direction in: query description: > Sort order for A/B tests by start date. Use 'asc' for ascending or 'desc' for descending. Active A/B tests are always listed first. example: desc schema: $ref: '#/components/schemas/direction' - $ref: '#/components/parameters/Methods' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: title: listABTestsResponse type: object additionalProperties: false properties: abtests: $ref: '#/components/schemas/ABTests' count: type: integer description: Number of A/B tests. example: 10 total: type: integer description: Number of retrievable A/B tests. example: 12 required: - abtests - count - total '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /3/abtests/{id}: get: tags: - abtesting-v3 operationId: getABTest x-acl: - analytics summary: Retrieve A/B test details description: Retrieves the details for an A/B test by its ID. parameters: - $ref: '#/components/parameters/ID' - $ref: '#/components/parameters/Methods' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/ABTest' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' delete: tags: - abtesting-v3 operationId: deleteABTest x-acl: - editSettings summary: Delete an A/B test description: Deletes an A/B test by its ID. parameters: - $ref: '#/components/parameters/ID' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/ABTestResponse' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' /3/abtests/{id}/stop: post: tags: - abtesting-v3 operationId: stopABTest x-acl: - editSettings summary: Stop an A/B test description: | Stops an A/B test by its ID. You can't restart stopped A/B tests. parameters: - $ref: '#/components/parameters/ID' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/ABTestResponse' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' /3/abtests/estimate: post: tags: - abtesting-v3 operationId: estimateABTest x-acl: - analytics summary: Estimate the sample size and duration of an A/B test description: >- Given the traffic percentage and the expected effect size, this endpoint estimates the sample size and duration of an A/B test based on historical traffic. requestBody: required: true content: application/json: schema: title: estimateABTestRequest type: object additionalProperties: false properties: configuration: title: estimateConfiguration type: object description: >- A/B test configuration for estimating the sample size and duration using minimum detectable effect. properties: filters: $ref: '#/components/schemas/MetricsFilters' minimumDetectableEffect: $ref: '#/components/schemas/MinimumDetectableEffect' required: - minimumDetectableEffect variants: type: array description: A/B test variants. minItems: 2 items: $ref: '#/components/schemas/AddABTestsVariant' required: - configuration - variants responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/EstimateABTestResponse' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' /3/abtests/{id}/timeseries: get: tags: - abtesting-v3 operationId: getTimeseries x-acl: - analytics summary: Retrieve timeseries of an A/B test description: Retrieves timeseries for an A/B test by its ID. parameters: - $ref: '#/components/parameters/ID' - $ref: '#/components/parameters/StartDate' - $ref: '#/components/parameters/EndDate' - in: query name: metric description: >- Metrics to retrieve, as a comma-separated list. If not specified, all metrics are returned. style: form explode: false schema: type: array items: $ref: '#/components/schemas/MetricName' - $ref: '#/components/parameters/Methods' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/Timeseries' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': $ref: '#/components/responses/IndexNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /3/abtests/{id}/settings: get: tags: - abtesting-v3 operationId: getABTestSettings x-acl: - analytics summary: Retrieve captured A/B test settings description: > Retrieves the settings captured for each variant of an A/B test, and whether another active A/B test is using the control index. Settings are captured by the `saveVariantSettings` operation. The response includes an entry for the control (variant 1) alongside the captured variant, so the control's original configuration can be restored later. Returns `404` if the A/B test doesn't exist or no settings have been captured for it. parameters: - $ref: '#/components/parameters/ID' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/ABTestSettingsResponse' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': description: A/B test or captured settings not found. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' '422': $ref: '#/components/responses/UnprocessableEntity' /3/abtests/{id}/settings/{variantId}: post: tags: - abtesting-v3 operationId: saveVariantSettings x-acl: - analytics - editSettings summary: Capture a variant's settings and stop the A/B test description: > Captures the settings of the given variant and of the control, then stops the A/B test. The captured settings can later be applied to the control index with the `applyVariantSettings` operation, and read back with the `getABTestSettings` operation. The A/B test must have reached 80% of its planned duration. Earlier requests return `400`. Settings can only be captured once per A/B test. A second request returns `409`. `synonyms` and `enableRules` are not captured, so applying the captured settings never changes them on the control index. parameters: - $ref: '#/components/parameters/ID' - $ref: '#/components/parameters/VariantID' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SaveSettingsRequest' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': description: A/B test, variant, or index not found. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' /3/abtests/{id}/settings/{variantId}/apply: post: tags: - abtesting-v3 operationId: applyVariantSettings x-acl: - analytics - editSettings summary: Apply a variant's captured settings to the control index description: > Applies the captured settings of the given variant to the control index. The settings must first be captured with the `saveVariantSettings` operation. To revert previously applied settings on the control index, use this operation with the control variant (variant 1). Settings can be applied up to 14 days after the A/B test ends, and reverted up to 15 days after. Later requests return `400`. Each set of captured settings can only be applied once, and settings that were reverted can't be applied again. Both cases return `400`. The control index must not be in use by an active A/B test. Otherwise, the request returns `422`. parameters: - $ref: '#/components/parameters/ID' - $ref: '#/components/parameters/VariantID' responses: '200': description: OK headers: x-ratelimit-limit: $ref: '#/components/headers/x-ratelimit-limit' x-ratelimit-remaining: $ref: '#/components/headers/x-ratelimit-remaining' x-ratelimit-reset: $ref: '#/components/headers/x-ratelimit-reset' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/FeatureNotEnabled' '403': $ref: '#/components/responses/MethodNotAllowed' '404': description: A/B test, variant, or index not found. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' '422': $ref: '#/components/responses/UnprocessableEntity' /setClientApiKey: get: x-helper: true x-asynchronous-helper: false x-acl: [] tags: - abtesting-v3 operationId: setClientApiKey summary: Switch the API key used to authenticate requests description: | Switch the API key used to authenticate requests. parameters: - in: query name: apiKey description: API key to use for subsequent requests. required: true schema: type: string responses: '204': description: No content. components: securitySchemes: appId: type: apiKey in: header name: x-algolia-application-id description: Your Algolia application ID. apiKey: type: apiKey in: header name: x-algolia-api-key description: > Your Algolia API key with the necessary permissions to make the request. Permissions are controlled through access control lists (ACL) and access restrictions. The required ACL to make a request is listed in each endpoint's reference. parameters: PathInPath: name: path in: path description: Path of the endpoint, for example `1/newFeature`. required: true schema: type: string example: /keys Parameters: name: parameters in: query description: Query parameters to apply to the current query. schema: type: object additionalProperties: true Methods: in: query name: methods description: > Statistical analysis results to include, as a comma-separated list. When omitted, each test uses its configured method, or `frequentist` if no method is configured. Request both methods to include both sets of available results. This doesn't change the test configuration or compute missing results. Duplicate values aren't allowed. style: form explode: false schema: type: array minItems: 1 items: $ref: '#/components/schemas/AnalysisMethod' ID: in: path name: id description: Unique A/B test identifier. required: true schema: $ref: '#/components/schemas/abTestID' StartDate: in: query name: startDate description: Start date of the period to analyze, in `YYYY-MM-DD` format. schema: type: string example: '2022-09-19' EndDate: in: query name: endDate description: End date of the period to analyze, in `YYYY-MM-DD` format. schema: type: string example: '2023-01-21' VariantID: in: path name: variantId description: One-based index of the A/B test variant. The control is variant 1. required: true schema: type: integer minimum: 1 example: 2 schemas: ErrorBase: description: Error. type: object x-keep-model: true additionalProperties: true properties: message: type: string example: Invalid Application-Id or API-Key direction: type: string description: | Sort order for A/B tests by start date. Use 'asc' for ascending or 'desc' for descending. Active A/B tests are always listed first. enum: - asc - desc example: desc AnalysisMethod: type: string description: > A/B test statistical analysis method. When omitted, new A/B tests use `bayesian`. They use `frequentist` instead only if no primary metric that supports Bayesian analysis is available. The selected method is saved in the A/B test configuration. Older A/B tests, created before methods were saved, may have no method in their configuration. These tests use `frequentist`. enum: - bayesian - frequentist abTestID: type: integer description: Unique A/B test identifier. example: 224 updatedAt: type: string description: Date and time when the A/B test was last updated, in RFC 3339 format. example: '2023-06-15T15:06:44.400601Z' createdAt: type: string description: Date and time when the A/B test was created, in RFC 3339 format. example: '2023-06-15T15:06:04.249906Z' endAt: type: string description: End date and time of the A/B test, in RFC 3339 format. example: '2023-06-17T00:00:00Z' stoppedAt: type: string description: Date and time when the A/B test was stopped, in RFC 3339 format. example: '2023-06-15T15:06:44.400601Z' nullable: true name: type: string description: A/B test name. example: Custom ranking sales rank test hypothesis: type: string description: Expected outcome of the A/B test. example: Enabling the feature increases conversion rate Status: type: string description: > A/B test status. - `active`. The A/B test is live and search traffic is split between the two variants. - `stopped`. You stopped the A/B test. The A/B test data is still available for analysis. - `expired`. The A/B test was automatically stopped after reaching its end date. - `failed`. Creating the A/B test failed. example: active enum: - active - stopped - expired - failed description: type: string description: Description for this variant. example: Current production index index: type: string description: Index name of the A/B test variant (case-sensitive). example: delcourt_production trafficPercentage: type: integer description: Percentage of search requests each variant receives. minimum: 1 maximum: 99 example: 60 metricMetadata: type: object description: Metric specific metadata. properties: winsorizedValue: type: number format: double description: > Only present for `revenue` metrics. It is the amount exceeding the 95th percentile of global revenue transactions involved in the AB Test. This amount is not considered when calculating statistical significance. It is tied to a per revenue-currency pair contrary to other global filter effects (such as outliers and empty search count). mean: type: number format: double description: Mean value for this metric. example: 53.7 userCount: type: integer format: int64 description: > Only present for `winsorized_revenue_per_user`. Number of tracked users in this variant with a tracked purchase in the metric's currency (`dimension`), plus tracked users with no tracked purchase in any currency. Users who purchased only in other currencies are excluded. It's the sample size behind the mean, p-value, and intervals, and differs from the overall `user_count` metric. Omitted when the variant has no record for that currency. example: 4100 example: winsorizedValue: 888.8 mean: 53.7 evidenceStatus: type: string description: > Whether this variant metric's result is trustworthy yet. This doesn't mean the A/B test has ended, and it doesn't declare a winning variant. - `enough`. Enough evidence has accumulated to trust this metric's result for this variant. - `not_enough`. Evidence was computed but hasn't reached the threshold yet. - `collecting`. Evidence is still accumulating, so it's too early to report a verdict. - `no_data`. No usable data for this variant metric, and none is expected for it. - `unavailable`. Evidence can't be computed for this variant metric's comparison. example: not_enough enum: - enough - not_enough - collecting - no_data - unavailable metricEvidence: type: object description: > Evidence status for this variant metric's comparison with the control. Only present when the API has an evidence status for the comparison. Omitted when evidence isn't applicable or no status exists. properties: status: $ref: '#/components/schemas/evidenceStatus' required: - status bayesianMetricResult: type: object description: > Bayesian inference results for this variant metric. Omitted when Bayesian results aren't requested or no Bayesian result is available for this metric. Individual inference fields can be omitted when their values aren't available. properties: probabilityToBeBetter: type: number format: double description: Probability that this variant is better than the control. example: 0.991 relativeEffectCILow: type: number format: double description: >- Lower bound of the 95% credible interval for the relative effect (variant/control minus 1). example: 0.04 relativeEffectCIHigh: type: number format: double description: >- Upper bound of the 95% credible interval for the relative effect (variant/control minus 1). example: 0.39 evidence: $ref: '#/components/schemas/metricEvidence' metricResult: type: object properties: name: type: string description: Metric name. Revenue per search results use `revenue_per_search`. updatedAt: type: string description: Date and time when the metric was last updated, in RFC 3339 format. value: type: number format: double description: >- Metric value. For `revenue_per_search`, this is the winsorized mean revenue per search in the specified currency. valueCIHigh: type: number format: double description: > The upper bound of the 95% confidence interval for the metric value. The confidence interval is calculated using either the relative ratio or relative difference between the metric values for the control and the variant. Relative ratio is used for metrics that are ratios (e.g., click-through rate, conversion rate), while relative difference is used for continuous metrics (e.g., revenue). valueCILow: type: number format: double description: > The lower bound of the 95% confidence interval for the metric value. The confidence interval is calculated using either the relative ratio or relative difference between the metric values for the control and the variant. Relative ratio is used for metrics that are ratios (e.g., click-through rate, conversion rate), while relative difference is used for continuous metrics (e.g., revenue). pValue: type: number format: double description: | P-value for this variant compared to the control. Omitted when no p-value is available for this metric. dimension: type: string description: >- Dimension defined during test creation. For revenue metrics, including `revenue_per_search` and `winsorized_revenue_per_user`, this is the currency. metadata: $ref: '#/components/schemas/metricMetadata' criticalValue: type: number format: double description: > The value that was computed during error correction. It is used to determine significance of the metric pValue. The critical value is calculated using Bonferroni or Benjamini-Hochberg corrections, based on the given configuration during the A/B test creation. significant: type: boolean description: > Whether the pValue is significant or not based on the critical value and the error correction algorithm used. bayesian: $ref: '#/components/schemas/bayesianMetricResult' required: - name - updatedAt - value example: - name: addToCartCount updatedAt: '2025-06-15T15:06:44.400601Z' value: 5 - name: clickThroughRate updatedAt: '2025-05-15T17:52:15.644906Z' value: 0.20869847452125934 pValue: 0.004 bayesian: probabilityToBeBetter: 0.991 evidence: status: enough - name: revenue dimension: USD updatedAt: '2025-05-15T17:52:15.644906Z' value: 1200.5 pValue: 0.04 metadata: winsorizedValue: 80.2 - name: revenue dimension: EUR updatedAt: '2025-05-15T17:52:15.644906Z' value: 999.66 pValue: 0.04 metadata: winsorizedValue: 888.8 - name: revenue_per_search dimension: USD updatedAt: '2025-05-15T17:52:15.644906Z' value: 12.45 metadata: mean: 12.45 bayesian: probabilityToBeBetter: 0.991 relativeEffectCILow: 0.04 relativeEffectCIHigh: 0.39 evidence: status: unavailable - name: winsorized_revenue_per_user dimension: USD updatedAt: '2025-05-15T17:52:15.644906Z' value: 53.7 metadata: mean: 53.7 userCount: 4100 metrics: type: array description: All ABTest metrics that were defined during test creation. items: $ref: '#/components/schemas/metricResult' filterEffects: type: object description: A/B test filter effects resulting from configuration settings. properties: outliers: title: outliersFilter type: object description: >- Outliers removed from the A/B test as a result of configuration settings. example: usersCount: 1 trackedSearchesCount: 237 properties: usersCount: type: integer description: Number of users removed from the A/B test. example: 1 trackedSearchesCount: type: integer description: Number of tracked searches removed from the A/B test. example: 237 emptySearch: title: emptySearchFilter type: object description: >- Empty searches removed from the A/B test as a result of configuration settings. example: usersCount: 1 trackedSearchesCount: 237 properties: usersCount: type: integer description: Number of users removed from the A/B test. example: 1 trackedSearchesCount: type: integer description: Number of tracked searches removed from the A/B test. example: 237 variantMetadata: type: object description: Variant specific metadata. properties: filterEffects: $ref: '#/components/schemas/filterEffects' variant: type: object additionalProperties: false properties: description: $ref: '#/components/schemas/description' estimatedSampleSize: type: integer description: > Estimated number of searches, or users for user-level rates (metrics ending in `UsersRate`), required to achieve the desired statistical significance. The A/B test configuration must include a `minimumDetectableEffect` setting for this number to be included in the response. example: 0 index: $ref: '#/components/schemas/index' trafficPercentage: $ref: '#/components/schemas/trafficPercentage' metrics: $ref: '#/components/schemas/metrics' metadata: $ref: '#/components/schemas/variantMetadata' customSearchParameters: type: object description: > Search parameters applied to this variant when the same index is used for multiple variants. Only present if custom search parameters were provided during test creation. example: enablePersonalization: true personalizationImpact: 50 required: - index - description - trafficPercentage - metrics variants: type: array description: > A/B test variants. The first variant is your _control_ index, typically your production index. All of the additional variants are indexes with changed settings that you want to test against the control. items: $ref: '#/components/schemas/variant' EffectMetric: type: string description: > Metric for which you want to detect the smallest relative difference. Metrics ending in `UsersRate` are user-level rates: the share of tracked users with at least one search with a click, conversion, add-to-cart, or purchase. For these metrics, sample sizes count users instead of searches. enum: - addToCartRate - clickThroughRate - conversionRate - purchaseRate - noResultsRate - addToCartUsersRate - clickedUsersRate - convertedUsersRate - purchaseUsersRate MinimumDetectableEffect: type: object description: >- Configuration for the smallest difference between test variants you want to detect, used to estimate the required sample size. properties: size: type: number format: double minimum: 0 maximum: 1 description: > Smallest difference in an observable metric between variants. For example, to detect a 10% difference between variants, set this value to 0.1. metric: $ref: '#/components/schemas/EffectMetric' required: - size - metric MetricsFilterParameters: type: object additionalProperties: false description: > Values for a filter that needs them. The `core.hasExactCategoryFilter` filter requires both properties and matches the searches that had the exact filter `:`. Optional filters and filters in an OR group don't match. With `includes` false or omitted, the test counts every search except those searches. A test can have at most one `core.hasExactCategoryFilter` filter. Other filters don't accept parameters. properties: filterAttribute: type: string minLength: 1 description: >- Facet attribute of the category, for example `categories.lvl0`. Hierarchical facets have one attribute for each level. example: categories.lvl0 filterValue: type: string minLength: 1 description: Facet value of the category, exactly as the search sends it. example: Shoes MetricsFilter: type: object additionalProperties: false description: > Boolean filter applied to the A/B test population. Each filter targets a boolean metric and decides whether to include (true) or exclude (false) matching records. properties: domain: type: string description: Metric domain (for example `abtesting`, `core`, `personalization`). example: abtesting name: type: string description: Public metric name. example: isOutlier trackEffects: type: boolean description: >- Whether the experiment should record the effects of this filter. Not supported by `core.hasExactCategoryFilter`. includes: type: boolean description: >- If true, keep items that match the filter; if false, exclude them. Defaults to false. parameters: $ref: '#/components/schemas/MetricsFilterParameters' required: - domain - name MetricsFilters: type: array description: List of metric filters applied to the test population. items: $ref: '#/components/schemas/MetricsFilter' ErrorCorrectionType: type: string description: >- Multiple-testing correction method applied when evaluating metric significance. enum: - bonferroni - benjamini-hochberg PrimaryMetric: type: string description: > Primary metric for Bayesian analysis. Required when `method` is `bayesian`. When `method` is omitted and the test defaults to `bayesian`, the default primary metric is `conversion_rate`, or the first metric in `metrics` that supports Bayesian analysis if `metrics` doesn't include conversion rate. If the request includes a non-empty `metrics` list, this metric must be in that list. User-level rates (`*_users_rate`) are the share of tracked users with at least one such search. For `users_with_no_results_rate`, this is the share of tracked users with at least one search returning no results. Lower values are better. Add-to-cart rates, purchase rates, and revenue per search require access to revenue analytics. example: conversion_rate enum: - add_to_cart_rate - click_through_rate - conversion_rate - purchase_rate - revenue_per_search - add_to_cart_users_rate - clicked_users_rate - converted_users_rate - purchase_users_rate - users_with_no_results_rate ABTestConfiguration: title: configuration type: object description: A/B test configuration. properties: minimumDetectableEffect: $ref: '#/components/schemas/MinimumDetectableEffect' filters: $ref: '#/components/schemas/MetricsFilters' errorCorrection: $ref: '#/components/schemas/ErrorCorrectionType' method: $ref: '#/components/schemas/AnalysisMethod' primaryMetric: $ref: '#/components/schemas/PrimaryMetric' Decision: type: object additionalProperties: false description: > Outcome of the A/B test once a winner has been declared. Only present when a winning variant has been declared, so its presence indicates the test has been decided. properties: winnerVariantId: type: integer description: >- Identifier of the declared winning variant. The control variant is 1. example: 2 declaredAt: type: string description: >- Date and time when the winning variant was declared, in RFC 3339 format. example: '2026-06-16T00:00:00Z' required: - winnerVariantId - declaredAt ABTest: type: object additionalProperties: false properties: abTestID: $ref: '#/components/schemas/abTestID' updatedAt: $ref: '#/components/schemas/updatedAt' createdAt: $ref: '#/components/schemas/createdAt' endAt: $ref: '#/components/schemas/endAt' stoppedAt: $ref: '#/components/schemas/stoppedAt' name: $ref: '#/components/schemas/name' hypothesis: $ref: '#/components/schemas/hypothesis' status: $ref: '#/components/schemas/Status' variants: $ref: '#/components/schemas/variants' configuration: $ref: '#/components/schemas/ABTestConfiguration' decision: $ref: '#/components/schemas/Decision' required: - status - name - hypothesis - createdAt - endAt - updatedAt - abTestID - variants ABTests: oneOf: - type: array description: A/B tests. items: $ref: '#/components/schemas/ABTest' - type: 'null' abTestsVariant: type: object additionalProperties: false properties: index: $ref: '#/components/schemas/index' trafficPercentage: $ref: '#/components/schemas/trafficPercentage' description: $ref: '#/components/schemas/description' required: - index - trafficPercentage customSearchParams: type: object description: | Search parameters to add to the test variant. Only use this parameter if the two variants use the same index. example: typoTolerance: false synonyms: false additionalProperties: false properties: customSearchParameters: type: object required: - customSearchParameters x-discriminator-fields: - customSearchParameters abTestsVariantSearchParams: allOf: - $ref: '#/components/schemas/abTestsVariant' - $ref: '#/components/schemas/customSearchParams' AddABTestsVariant: oneOf: - title: Variant $ref: '#/components/schemas/abTestsVariant' - title: Variant with search parameters $ref: '#/components/schemas/abTestsVariantSearchParams' createMetric: type: object description: Defines a metric to be retrieved during an A/B test. properties: name: type: string description: Name of the metric. dimension: type: string description: >- Dimension of the metric, for example, in case of a revenue metric it could be USD, EUR... required: - name example: - name: revenue dimension: USD - name: conversionRate - name: clickThroughRate - name: trackedSearchCount taskID: type: integer format: int64 example: 1514562690001 description: > Unique identifier of a task. A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the [`task` operation](https://www.algolia.com/doc/rest-api/search/get-task) and this task ID. ABTestResponse: type: object additionalProperties: false properties: index: $ref: '#/components/schemas/index' abTestID: $ref: '#/components/schemas/abTestID' taskID: $ref: '#/components/schemas/taskID' required: - abTestID - index - taskID EstimateABTestResponse: type: object properties: durationDays: type: integer format: int64 description: >- Estimated number of days needed to reach the sample sizes required for detecting the configured effect. This value is based on historical traffic. example: 21 sampleSizes: type: array description: > Sample size estimates for each variant. The first element is the control variant. Each element is the estimated number of searches, or users for user-level rates (metrics ending in `UsersRate`), required to achieve the desired statistical significance. items: type: integer format: int64 description: >- Number of tracked searches, or tracked users for user-level rates, needed to be able to detect the configured effect for the control variant. example: 23415 MetricName: type: string enum: - search_count - tracked_search_count - user_count - tracked_user_count - no_result_count - tracked_no_result_count - add_to_cart_count - purchase_count - clicked_search_count - converted_search_count - click_through_rate - conversion_rate - add_to_cart_rate - purchase_rate - average_click_position - revenue - revenue_per_search - average_order_value - clicked_users_count - converted_users_count - add_to_cart_users_count - purchase_users_count - users_with_no_results_count - clicked_users_rate - converted_users_rate - add_to_cart_users_rate - purchase_users_rate - users_with_no_results_rate - avg_click_through_rate_per_user - avg_conversion_rate_per_user - avg_purchase_rate_per_user - avg_add_to_cart_rate_per_user - avg_click_position_per_user - winsorized_revenue_per_user - winsorized_revenue_per_purchaser metricDate: type: object properties: date: type: string description: Date where the metric was updated, in RFC 3339 format. example: '2025-06-15' metrics: $ref: '#/components/schemas/metrics' metricDates: type: array items: $ref: '#/components/schemas/metricDate' timeseriesVariant: type: object properties: dates: $ref: '#/components/schemas/metricDates' timeseriesVariants: type: array description: > A/B test timeseries variants. The first variant is your _control_ index, typically your production index. All of the additional variants are indexes with changed settings that you want to test against the control. items: $ref: '#/components/schemas/timeseriesVariant' Timeseries: type: object additionalProperties: false properties: abTestID: $ref: '#/components/schemas/abTestID' variants: $ref: '#/components/schemas/timeseriesVariants' required: - abTestID - variants FeatureSettings: type: object description: Feature-specific settings captured for a variant. additionalProperties: false properties: name: type: string description: Name of the feature the settings belong to. example: drr settings: description: Feature settings payload. The shape depends on the feature. required: - name - settings VariantSettings: type: object description: Settings captured for one A/B test variant. additionalProperties: false properties: variantId: type: integer description: >- One-based index of the variant within the A/B test. The control is variant 1. example: 2 applied: type: boolean description: >- Whether the variant's settings have been applied to the control index. featuresSettings: type: array description: Feature-specific settings captured for the variant. items: $ref: '#/components/schemas/FeatureSettings' indexSettings: type: object description: Index settings captured for the variant. applyTimestamp: type: string description: >- Date and time when the variant's settings were applied to the control index, in RFC 3339 format. example: '2023-06-17T00:00:00Z' revertTimestamp: type: string description: >- Date and time when the applied settings were reverted on the control index, in RFC 3339 format. example: '2023-06-18T00:00:00Z' declaredTimestamp: type: string description: >- Date and time when the variant's settings were captured, in RFC 3339 format. example: '2023-06-16T00:00:00Z' expiredTimestamp: type: string description: >- Date and time when the captured settings expired, in RFC 3339 format. example: '2023-07-16T00:00:00Z' required: - variantId - applied ABTestSettingsResponse: type: object description: Captured settings of an A/B test. additionalProperties: false properties: abtestSettings: type: array description: Captured settings for each variant of the A/B test. items: $ref: '#/components/schemas/VariantSettings' controlIndexInUse: type: boolean description: Whether another active A/B test is using the control index. required: - abtestSettings - controlIndexInUse SaveSettingsRequest: type: object description: Options for capturing a variant's settings. additionalProperties: false properties: saveFeaturesSettings: type: boolean description: >- Whether to also capture the variant's index settings and feature-specific settings. This must be true for A/B tests whose variants use different indices so that the captured variant settings can later be applied. default: false responses: BadRequest: description: Bad request or request arguments. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' FeatureNotEnabled: description: This feature is not enabled on your Algolia account. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' MethodNotAllowed: description: Method not allowed with this API key. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' IndexNotFound: description: Index not found. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' UnprocessableEntity: description: Unprocessable Entity. content: application/json: schema: $ref: '#/components/schemas/ErrorBase' Conflict: description: Conflict. content: application/json: schema: title: conflictResponse type: object additionalProperties: false required: - status - message properties: status: type: integer example: 409 description: Status code. message: type: string example: Conflict description: Response message. headers: x-ratelimit-limit: description: Number of allowed requests per one minute. example: 100 schema: type: integer x-ratelimit-remaining: description: Number of remaining requests in the current period. example: 99 schema: type: integer x-ratelimit-reset: description: >- Timestamp when the rate limit will reset, measured in seconds since the Unix epoch. example: 1710682486 schema: type: integer x-tagGroups: - name: General tags: - abtest