> ## Documentation Index > Fetch the complete documentation index at: https://algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an A/B test > Creates a new A/B test. **Required ACL:** `editSettings` ## OpenAPI ````yaml specs/abtesting-v3.yml post /3/abtests openapi: 3.1.0 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: /3/abtests: post: tags: - abtest summary: Create an A/B test description: Creates a new A/B test. operationId: addABTests requestBody: required: true content: application/json: schema: title: addABTestsRequest type: object additionalProperties: false properties: endAt: $ref: '#/components/schemas/endAt' 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' name: $ref: '#/components/schemas/name' variants: type: array description: A/B test variants. minItems: 2 items: $ref: '#/components/schemas/AddABTestsVariant' configuration: $ref: '#/components/schemas/ABTestConfiguration' 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' x-codeSamples: - lang: csharp label: C# source: |- // Initialize the client var client = new AbtestingV3Client( new AbtestingV3Config( "ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION" ) ); // Call the API var response = await client.AddABTestsAsync( new AddABTestsRequest { EndAt = "2022-12-31T00:00:00.000Z", Name = "myABTest", Metrics = new List { new CreateMetric { Name = "myMetric" } }, Variants = new List { new AddABTestsVariant(new AbTestsVariant { Index = "AB_TEST_1", TrafficPercentage = 30 }), new AddABTestsVariant(new AbTestsVariant { Index = "AB_TEST_2", TrafficPercentage = 50 }), }, } ); // print the response Console.WriteLine(response); - lang: dart label: Dart source: |- // Initialize the client final client = AbtestingV3Client( appId: 'ALGOLIA_APPLICATION_ID', apiKey: 'ALGOLIA_API_KEY', region: 'ALGOLIA_APPLICATION_REGION'); // Call the API final response = await client.addABTests( addABTestsRequest: AddABTestsRequest( endAt: "2022-12-31T00:00:00.000Z", name: "myABTest", metrics: [ CreateMetric( name: "myMetric", ), ], variants: [ AbTestsVariant( index: "AB_TEST_1", trafficPercentage: 30, ), AbTestsVariant( index: "AB_TEST_2", trafficPercentage: 50, ), ], ), ); // print the response print(response); - lang: go label: Go source: >- // Initialize the client with your application region, eg. abtestingV3.ALGOLIA_APPLICATION_REGION client, err := abtestingV3.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", abtestingV3.US) if err != nil { // The client can fail to initialize if you pass an invalid parameter. panic(err) } // Call the API response, err := client.AddABTests(client.NewApiAddABTestsRequest( abtestingV3.NewEmptyAddABTestsRequest().SetEndAt("2022-12-31T00:00:00.000Z").SetName("myABTest").SetMetrics( []abtestingV3.CreateMetric{*abtestingV3.NewEmptyCreateMetric().SetName("myMetric")}).SetVariants( []abtestingV3.AddABTestsVariant{*abtestingV3.AbTestsVariantAsAddABTestsVariant( abtestingV3.NewEmptyAbTestsVariant().SetIndex("AB_TEST_1").SetTrafficPercentage(30)), *abtestingV3.AbTestsVariantAsAddABTestsVariant( abtestingV3.NewEmptyAbTestsVariant().SetIndex("AB_TEST_2").SetTrafficPercentage(50))}))) if err != nil { // handle the eventual error panic(err) } // print the response print(response) - lang: java label: Java source: >- // Initialize the client AbtestingV3Client client = new AbtestingV3Client("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION"); // Call the API ABTestResponse response = client.addABTests( new AddABTestsRequest() .setEndAt("2022-12-31T00:00:00.000Z") .setName("myABTest") .setMetrics(Arrays.asList(new CreateMetric().setName("myMetric"))) .setVariants( Arrays.asList( new AbTestsVariant().setIndex("AB_TEST_1").setTrafficPercentage(30), new AbTestsVariant().setIndex("AB_TEST_2").setTrafficPercentage(50) ) ) ); // print the response System.out.println(response); - lang: javascript label: JavaScript source: >- // Initialize the client // Replace 'us' with your Algolia Application Region const client = algoliasearch('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY').initAbtestingV3({ region: 'us' }); // Call the API const response = await client.addABTests({ endAt: '2022-12-31T00:00:00.000Z', name: 'myABTest', metrics: [{ name: 'myMetric' }], variants: [ { index: 'AB_TEST_1', trafficPercentage: 30 }, { index: 'AB_TEST_2', trafficPercentage: 50 }, ], }); // print the response console.log(response); - lang: kotlin label: Kotlin source: |- // Initialize the client val client = AbtestingV3Client( appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY", region = "ALGOLIA_APPLICATION_REGION", ) // Call the API var response = client.addABTests( addABTestsRequest = AddABTestsRequest( endAt = "2022-12-31T00:00:00.000Z", name = "myABTest", metrics = listOf(CreateMetric(name = "myMetric")), variants = listOf( AbTestsVariant(index = "AB_TEST_1", trafficPercentage = 30), AbTestsVariant(index = "AB_TEST_2", trafficPercentage = 50), ), ) ) // print the response println(response) - lang: php label: PHP source: >- // Initialize the client $client = AbtestingV3Client::create('ALGOLIA_APPLICATION_ID', 'ALGOLIA_API_KEY', 'ALGOLIA_APPLICATION_REGION'); // Call the API $response = $client->addABTests( ['endAt' => '2022-12-31T00:00:00.000Z', 'name' => 'myABTest', 'metrics' => [ ['name' => 'myMetric', ], ], 'variants' => [ ['index' => 'AB_TEST_1', 'trafficPercentage' => 30, ], ['index' => 'AB_TEST_2', 'trafficPercentage' => 50, ], ], ], ); // print the response var_dump($response); - lang: python label: Python source: >- # Initialize the client # In an asynchronous context, you can use AbtestingV3Client instead, which exposes the exact same methods. client = AbtestingV3ClientSync( "ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION" ) # Call the API response = client.add_ab_tests( add_ab_tests_request={ "endAt": "2022-12-31T00:00:00.000Z", "name": "myABTest", "metrics": [ { "name": "myMetric", }, ], "variants": [ { "index": "AB_TEST_1", "trafficPercentage": 30, }, { "index": "AB_TEST_2", "trafficPercentage": 50, }, ], }, ) # print the response print(response) - lang: ruby label: Ruby source: >- # Initialize the client client = Algolia::AbtestingV3Client.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION") # Call the API response = client.add_ab_tests( Algolia::AbtestingV3::AddABTestsRequest.new( end_at: "2022-12-31T00:00:00.000Z", name: "myABTest", metrics: [Algolia::AbtestingV3::CreateMetric.new(name: "myMetric")], variants: [ Algolia::AbtestingV3::AbTestsVariant.new(index: "AB_TEST_1", traffic_percentage: 30), Algolia::AbtestingV3::AbTestsVariant.new(index: "AB_TEST_2", traffic_percentage: 50) ] ) ) # print the response puts(response) - lang: scala label: Scala source: |- // Initialize the client val client = AbtestingV3Client( appId = "ALGOLIA_APPLICATION_ID", apiKey = "ALGOLIA_API_KEY", region = Option("ALGOLIA_APPLICATION_REGION") ) // Call the API val response = Await.result( client.addABTests( addABTestsRequest = AddABTestsRequest( endAt = "2022-12-31T00:00:00.000Z", name = "myABTest", metrics = Seq( CreateMetric( name = "myMetric" ) ), variants = Seq( AbTestsVariant( index = "AB_TEST_1", trafficPercentage = 30 ), AbTestsVariant( index = "AB_TEST_2", trafficPercentage = 50 ) ) ) ), Duration(100, "sec") ) // print the response println(response) - lang: swift label: Swift source: >- // Initialize the client let client = try AbtestingV3Client(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY", region: .us) // Call the API let response = try await client.addABTests(addABTestsRequest: AbtestingV3AddABTestsRequest( name: "myABTest", variants: [ AbtestingV3AddABTestsVariant.abtestingV3AbTestsVariant(AbtestingV3AbTestsVariant( index: "AB_TEST_1", trafficPercentage: 30 )), AbtestingV3AddABTestsVariant.abtestingV3AbTestsVariant(AbtestingV3AbTestsVariant( index: "AB_TEST_2", trafficPercentage: 50 )), ], metrics: [CreateMetric(name: "myMetric")], endAt: "2022-12-31T00:00:00.000Z" )) // print the response print(response) - lang: cURL label: curl source: |- curl --request POST \ --url https://analytics.us.algolia.com/3/abtests \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'x-algolia-api-key: ALGOLIA_API_KEY' \ --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \ --data ' { "name": "Custom ranking sales rank test", "variants": [ { "index": "delcourt_production", "trafficPercentage": 60, "description": "Current production index" }, { "index": "delcourt_production", "trafficPercentage": 60, "description": "Current production index" } ], "metrics": [ [ { "name": "revenue", "dimension": "USD" }, { "name": "conversionRate" }, { "name": "clickThroughRate" }, { "name": "trackedSearchCount" } ] ], "configuration": { "minimumDetectableEffect": { "size": 0, "metric": "addToCartRate" }, "filters": [ { "domain": "abtesting", "name": "isOutlier", "trackEffects": true, "includes": true } ], "errorCorrection": "bonferroni" }, "endAt": "2023-06-17T00:00:00Z" } ' components: schemas: endAt: type: string description: End date and time of the A/B test, in RFC 3339 format. example: '2023-06-17T00:00:00Z' 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 name: type: string description: A/B test name. example: Custom ranking sales rank test AddABTestsVariant: oneOf: - $ref: '#/components/schemas/abTestsVariant' title: Variant - $ref: '#/components/schemas/abTestsVariantSearchParams' title: Variant with search parameters ABTestConfiguration: title: configuration type: object description: A/B test configuration. properties: errorCorrection: $ref: '#/components/schemas/ErrorCorrectionType' filters: $ref: '#/components/schemas/MetricsFilters' minimumDetectableEffect: $ref: '#/components/schemas/MinimumDetectableEffect' ABTestResponse: type: object additionalProperties: false properties: abTestID: $ref: '#/components/schemas/abTestID' index: $ref: '#/components/schemas/index' taskID: $ref: '#/components/schemas/taskID' required: - abTestID - index - taskID abTestsVariant: type: object additionalProperties: false properties: index: $ref: '#/components/schemas/index' trafficPercentage: $ref: '#/components/schemas/trafficPercentage' description: $ref: '#/components/schemas/description' required: - index - trafficPercentage abTestsVariantSearchParams: allOf: - $ref: '#/components/schemas/abTestsVariant' - $ref: '#/components/schemas/customSearchParams' ErrorCorrectionType: type: string description: >- Multiple-testing correction method applied when evaluating metric significance. enum: - bonferroni - benjamini-hochberg MetricsFilters: type: array description: List of metric filters applied to the test population. items: $ref: '#/components/schemas/MetricsFilter' MinimumDetectableEffect: type: object description: >- Configuration for the smallest difference between test variants you want to detect. properties: metric: $ref: '#/components/schemas/EffectMetric' 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. required: - size - metric abTestID: type: integer description: Unique A/B test identifier. example: 224 index: type: string description: Index name of the A/B test variant (case-sensitive). example: delcourt_production 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. ErrorBase: description: Error. type: object x-keep-model: true additionalProperties: true properties: message: type: string example: Invalid Application-Id or API-Key trafficPercentage: type: integer description: Percentage of search requests each variant receives. minimum: 1 maximum: 99 example: 60 description: type: string description: Description for this variant. example: Current production index 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 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`, `personalization`). example: abtesting name: type: string description: Public metric name. example: isOutlier includes: type: boolean description: If true, keep items that match the filter; if false, exclude them. trackEffects: type: boolean description: Whether the experiment should record the effects of this filter. required: - domain - name EffectMetric: type: string description: Metric for which you want to detect the smallest relative difference. enum: - addToCartRate - clickThroughRate - conversionRate - purchaseRate - noResultsRate 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 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' 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. ````