{ "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\n\nBase URLs for the A/B testing API:\n\n- `https://analytics.us.algolia.com`\n- `https://analytics.de.algolia.com`\n- `https://analytics.algolia.com` (routes requests to the closest of the above servers, based on your geographical location)\n\nUse the URL that matches your [analytics region](https://dashboard.algolia.com/account/infrastructure/analytics).\n\n**All requests must use HTTPS.**\n\n## Availability and authentication\n\nAccess to the A/B testing API is available as part of the [Premium or Elevate plans](https://www.algolia.com/pricing).\n\nAdd these headers to authenticate requests:\n\n- `x-algolia-application-id`. Your Algolia application ID.\n- `x-algolia-api-key`. An API key with the necessary permissions to make the request.\n The required access control list (ACL) to make a request is listed in each endpoint's reference.\n\nYou can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account/api-keys).\n\n## Rate limits\n\nYou can make up to **100 requests per minute per app** to the A/B testing API.\nThe response includes headers with information about the limits.\n\n## Parameters\n\nQuery parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).\nNon-ASCII characters must be UTF-8 encoded.\nPlus characters (`+`) are interpreted as spaces.\n\n## Response status and errors\n\nThe A/B testing API returns JSON responses.\nSince JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.\n\nSuccessful responses return `2xx` statuses. Client errors return `4xx` statuses. Server errors return `5xx` statuses.\nError responses have a `message` property with more information.\n\n## Version\n\nThe current version of the A/B Testing API is version 3, indicated by the `/3/` in each endpoint's URL.\n", "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.\n\nA/B tests are configurations one or more indices, usually your production index and an index with different settings that you want to test.\n" } ], "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" } } }, "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" } } }, "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" } } }, "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" } } } }, "/3/abtests": { "post": { "tags": [ "abtest" ], "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": [ "abtest" ], "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.\nUse 'asc' for ascending or 'desc' for descending. Active A/B tests are always listed first.\n", "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": [ "abtest" ], "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": [ "abtest" ], "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": [ "abtest" ], "operationId": "stopABTest", "x-acl": [ "editSettings" ], "summary": "Stop an A/B test", "description": "Stops an A/B test by its ID.\n\nYou can't restart stopped A/B tests.\n", "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": [ "abtest" ], "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": [ "abtest" ], "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": [ "abtest" ], "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.\n\nSettings 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.\n\nReturns `404` if the A/B test doesn't exist or no settings have been captured for it.\n", "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": [ "abtest" ], "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.\n\nThe captured settings can later be applied to the control index with the `applyVariantSettings` operation, and read back with the `getABTestSettings` operation.\n\nThe A/B test must have reached 80% of its planned duration. Earlier requests return `400`.\n\nSettings can only be captured once per A/B test. A second request returns `409`.\n\n`synonyms` and `enableRules` are not captured, so applying the captured settings never changes them on the control index.\n", "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": [ "abtest" ], "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.\n\nThe 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).\n\nSettings can be applied up to 14 days after the A/B test ends, and reverted up to 15 days after. Later requests return `400`.\n\nEach set of captured settings can only be applied once, and settings that were reverted can't be applied again. Both cases return `400`.\n\nThe control index must not be in use by an active A/B test. Otherwise, the request returns `422`.\n", "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": [ "Api Key" ], "operationId": "setClientApiKey", "summary": "Switch the API key used to authenticate requests", "description": "Switch the API key used to authenticate requests.\n", "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.\nPermissions are controlled through access control lists (ACL) and access restrictions.\nThe required ACL to make a request is listed in each endpoint's reference.\n" } }, "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.\nWhen omitted, each test uses its configured method, or `frequentist` if no method is configured.\nRequest both methods to include both sets of available results. This doesn't change the test configuration or compute missing results.\nDuplicate values aren't allowed.\n", "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.\nUse 'asc' for ascending or 'desc' for descending.\nActive A/B tests are always listed first.\n", "enum": [ "asc", "desc" ], "example": "desc" }, "AnalysisMethod": { "type": "string", "description": "A/B test statistical analysis method.\nWhen omitted, new A/B tests use `bayesian`.\nThey use `frequentist` instead only if no primary metric that supports Bayesian analysis is available.\nThe selected method is saved in the A/B test configuration.\nOlder A/B tests, created before methods were saved, may have no method in their configuration.\nThese tests use `frequentist`.\n", "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.\n\n- `active`. The A/B test is live and search traffic is split between the two variants.\n- `stopped`. You stopped the A/B test. The A/B test data is still available for analysis.\n- `expired`. The A/B test was automatically stopped after reaching its end date.\n- `failed`. Creating the A/B test failed.\n", "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.\nIt 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.\nIt is tied to a per revenue-currency pair contrary to other\nglobal filter effects (such as outliers and empty search count).\n" }, "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`.\nNumber 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.\nUsers who purchased only in other currencies are excluded.\nIt's the sample size behind the mean, p-value, and intervals, and differs from the overall `user_count` metric.\nOmitted when the variant has no record for that currency.\n", "example": 4100 } }, "example": { "winsorizedValue": 888.8, "mean": 53.7 } }, "evidenceStatus": { "type": "string", "description": "Whether this variant metric's result is trustworthy yet.\nThis doesn't mean the A/B test has ended, and it doesn't declare a winning variant.\n\n- `enough`. Enough evidence has accumulated to trust this metric's result for this variant.\n- `not_enough`. Evidence was computed but hasn't reached the threshold yet.\n- `collecting`. Evidence is still accumulating, so it's too early to report a verdict.\n- `no_data`. No usable data for this variant metric, and none is expected for it.\n- `unavailable`. Evidence can't be computed for this variant metric's comparison.\n", "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.\nOnly present when the API has an evidence status for the comparison. Omitted when evidence isn't applicable or no status exists.\n", "properties": { "status": { "$ref": "#/components/schemas/evidenceStatus" } }, "required": [ "status" ] }, "bayesianMetricResult": { "type": "object", "description": "Bayesian inference results for this variant metric.\nOmitted when Bayesian results aren't requested or no Bayesian result is available for this metric.\nIndividual inference fields can be omitted when their values aren't available.\n", "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\neither the relative ratio or relative difference between the metric values for the control and the variant.\nRelative ratio is used for metrics that are ratios (e.g., click-through rate, conversion rate),\nwhile relative difference is used for continuous metrics (e.g., revenue).\n" }, "valueCILow": { "type": "number", "format": "double", "description": "The lower bound of the 95% confidence interval for the metric value. The confidence interval is calculated using\neither the relative ratio or relative difference between the metric values for the control and the variant.\nRelative ratio is used for metrics that are ratios (e.g., click-through rate, conversion rate),\nwhile relative difference is used for continuous metrics (e.g., revenue).\n" }, "pValue": { "type": "number", "format": "double", "description": "P-value for this variant compared to the control.\nOmitted when no p-value is available for this metric.\n" }, "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.\nThe critical value is calculated using Bonferroni or Benjamini-Hochberg corrections, based on the given\nconfiguration during the A/B test creation.\n" }, "significant": { "type": "boolean", "description": "Whether the pValue is significant or not based on the critical value and the error correction algorithm used.\n" }, "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.\n\nThe A/B test configuration must include a `minimumDetectableEffect` setting for this number to be included in the response.\n", "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.\nOnly present if custom search parameters were provided during test creation.\n", "example": { "enablePersonalization": true, "personalizationImpact": 50 } } }, "required": [ "index", "description", "trafficPercentage", "metrics" ] }, "variants": { "type": "array", "description": "A/B test variants.\n\nThe first variant is your _control_ index, typically your production index.\nAll of the additional variants are indexes with changed settings that you want to test against the control.\n", "items": { "$ref": "#/components/schemas/variant" } }, "EffectMetric": { "type": "string", "description": "Metric for which you want to detect the smallest relative difference.\nMetrics 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.\nFor these metrics, sample sizes count users instead of searches.\n", "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.\nFor example, to detect a 10% difference between variants, set this value to 0.1.\n" }, "metric": { "$ref": "#/components/schemas/EffectMetric" } }, "required": [ "size", "metric" ] }, "MetricsFilterParameters": { "type": "object", "additionalProperties": false, "description": "Values for a filter that needs them.\nThe `core.hasExactCategoryFilter` filter requires both properties and matches the searches that had the exact filter `:`.\nOptional filters and filters in an OR group don't match.\nWith `includes` false or omitted, the test counts every search except those searches.\nA test can have at most one `core.hasExactCategoryFilter` filter.\nOther filters don't accept parameters.\n", "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\nand decides whether to include (true) or exclude (false) matching records.\n", "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`.\nWhen `method` is omitted and the test defaults to `bayesian`, the default primary metric is `conversion_rate`,\nor the first metric in `metrics` that supports Bayesian analysis if `metrics` doesn't include conversion rate.\nIf the request includes a non-empty `metrics` list, this metric must be in that list.\nUser-level rates (`*_users_rate`) are the share of tracked users with at least one such search.\nFor `users_with_no_results_rate`, this is the share of tracked users with at least one search returning no results. Lower values are better.\nAdd-to-cart rates, purchase rates, and revenue per search require access to revenue analytics.\n", "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.\nOnly present when a winning variant has been declared, so its presence indicates the test has been decided.\n", "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.\nOnly use this parameter if the two variants use the same index.\n", "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.\n\nA successful API response means that a task was added to a queue.\nIt might not run immediately.\nYou can check the task's progress with the [`task` operation](https://www.algolia.com/doc/rest-api/search/get-task) and this task ID.\n" }, "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.\nEach element is the estimated number of searches, or users for user-level rates (metrics ending in `UsersRate`), required to achieve the desired statistical significance.\n", "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.\n\nThe first variant is your _control_ index, typically your production index.\nAll of the additional variants are indexes with changed settings that you want to test against the control.\n", "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" ] } ] }