> ## 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.yml post /2/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` (alias of `analytics.us.algolia.com`) 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 2, indicated by the `/2/` in each endpoint's URL. version: 2.0.0 servers: - url: https://analytics.{region}.algolia.com variables: region: description: The region where your Algolia application is hosted. 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: /2/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' name: $ref: '#/components/schemas/name' variants: type: array description: A/B test variants. minItems: 2 maxItems: 2 items: $ref: '#/components/schemas/AddABTestsVariant' required: - name - variants - 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 AbtestingClient( new AbtestingConfig("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", 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: go label: Go source: >- // Initialize the client with your application region, eg. abtesting.ALGOLIA_APPLICATION_REGION client, err := abtesting.NewClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", abtesting.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( abtesting.NewEmptyAddABTestsRequest().SetEndAt("2022-12-31T00:00:00.000Z").SetName("myABTest").SetVariants( []abtesting.AddABTestsVariant{*abtesting.AbTestsVariantAsAddABTestsVariant( abtesting.NewEmptyAbTestsVariant().SetIndex("AB_TEST_1").SetTrafficPercentage(30)), *abtesting.AbTestsVariantAsAddABTestsVariant( abtesting.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 AbtestingClient client = new AbtestingClient("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") .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').initAbtesting({ region: 'us' }); // Call the API const response = await client.addABTests({ endAt: '2022-12-31T00:00:00.000Z', name: 'myABTest', 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 = AbtestingClient( 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", 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 = AbtestingClient::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', '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 AbtestingClient instead, which exposes the exact same methods. client = AbtestingClientSync( "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", "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::AbtestingClient.create("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION") # Call the API response = client.add_ab_tests( Algolia::Abtesting::AddABTestsRequest.new( end_at: "2022-12-31T00:00:00.000Z", name: "myABTest", variants: [ Algolia::Abtesting::AbTestsVariant.new(index: "AB_TEST_1", traffic_percentage: 30), Algolia::Abtesting::AbTestsVariant.new(index: "AB_TEST_2", traffic_percentage: 50) ] ) ) # print the response puts(response) - lang: scala label: Scala source: |- // Initialize the client val client = AbtestingClient( 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", 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 AbtestingClient(appID: "ALGOLIA_APPLICATION_ID", apiKey: "ALGOLIA_API_KEY", region: .us) // Call the API let response = try await client.addABTests(addABTestsRequest: AbtestingAddABTestsRequest( name: "myABTest", variants: [ AbtestingAddABTestsVariant.abtestingAbTestsVariant(AbtestingAbTestsVariant( index: "AB_TEST_1", trafficPercentage: 30 )), AbtestingAddABTestsVariant.abtestingAbTestsVariant(AbtestingAbTestsVariant( index: "AB_TEST_2", trafficPercentage: 50 )), ], 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/2/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" } ], "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' 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 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' 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: 0 maximum: 100 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 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. ````