> ## Documentation Index > Fetch the complete documentation index at: https://algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # Estimate the sample size and duration of an A/B test > 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. **Required ACL:** `analytics` ## OpenAPI ````yaml specs/abtesting.yml post /2/abtests/estimate 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/estimate: post: tags: - abtest 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. operationId: estimateABTest 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: minimumDetectableEffect: $ref: '#/components/schemas/MinimumDetectableEffect' emptySearch: $ref: '#/components/schemas/EmptySearch' featureFilters: $ref: '#/components/schemas/FeatureFilters' outliers: $ref: '#/components/schemas/Outliers' required: - minimumDetectableEffect variants: type: array description: A/B test variants. minItems: 2 maxItems: 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' 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.EstimateABTestAsync( new EstimateABTestRequest { Configuration = new EstimateConfiguration { EmptySearch = new EmptySearch { Exclude = true }, MinimumDetectableEffect = new MinimumDetectableEffect { Size = 0.03, Metric = Enum.Parse("ConversionRate"), }, }, Variants = new List { new AddABTestsVariant(new AbTestsVariant { Index = "AB_TEST_1", TrafficPercentage = 50 }), 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.EstimateABTest(client.NewApiEstimateABTestRequest( abtesting.NewEmptyEstimateABTestRequest().SetConfiguration( abtesting.NewEmptyEstimateConfiguration().SetEmptySearch( abtesting.NewEmptyEmptySearch().SetExclude(true)).SetMinimumDetectableEffect( abtesting.NewEmptyMinimumDetectableEffect().SetSize(0.03).SetMetric(abtesting.EffectMetric("conversionRate")))).SetVariants( []abtesting.AddABTestsVariant{*abtesting.AbTestsVariantAsAddABTestsVariant( abtesting.NewEmptyAbTestsVariant().SetIndex("AB_TEST_1").SetTrafficPercentage(50)), *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 EstimateABTestResponse response = client.estimateABTest( new EstimateABTestRequest() .setConfiguration( new EstimateConfiguration() .setEmptySearch(new EmptySearch().setExclude(true)) .setMinimumDetectableEffect(new MinimumDetectableEffect().setSize(0.03).setMetric(EffectMetric.CONVERSION_RATE)) ) .setVariants( Arrays.asList( new AbTestsVariant().setIndex("AB_TEST_1").setTrafficPercentage(50), 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.estimateABTest({ configuration: { emptySearch: { exclude: true }, minimumDetectableEffect: { size: 0.03, metric: 'conversionRate' }, }, variants: [ { index: 'AB_TEST_1', trafficPercentage: 50 }, { 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.estimateABTest( estimateABTestRequest = EstimateABTestRequest( configuration = EstimateConfiguration( emptySearch = EmptySearch(exclude = true), minimumDetectableEffect = MinimumDetectableEffect( size = 0.03, metric = EffectMetric.entries.first { it.value == "conversionRate" }, ), ), variants = listOf( AbTestsVariant(index = "AB_TEST_1", trafficPercentage = 50), 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->estimateABTest( ['configuration' => ['emptySearch' => ['exclude' => true, ], 'minimumDetectableEffect' => ['size' => 0.03, 'metric' => 'conversionRate', ], ], 'variants' => [ ['index' => 'AB_TEST_1', 'trafficPercentage' => 50, ], ['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.estimate_ab_test( estimate_ab_test_request={ "configuration": { "emptySearch": { "exclude": True, }, "minimumDetectableEffect": { "size": 0.03, "metric": "conversionRate", }, }, "variants": [ { "index": "AB_TEST_1", "trafficPercentage": 50, }, { "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.estimate_ab_test( Algolia::Abtesting::EstimateABTestRequest.new( configuration: Algolia::Abtesting::EstimateConfiguration.new( empty_search: Algolia::Abtesting::EmptySearch.new(exclude: true), minimum_detectable_effect: Algolia::Abtesting::MinimumDetectableEffect.new(size: 0.03, metric: "conversionRate") ), variants: [ Algolia::Abtesting::AbTestsVariant.new(index: "AB_TEST_1", traffic_percentage: 50), 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.estimateABTest( estimateABTestRequest = EstimateABTestRequest( configuration = EstimateConfiguration( emptySearch = Some( EmptySearch( exclude = Some(true) ) ), minimumDetectableEffect = MinimumDetectableEffect( size = 0.03, metric = EffectMetric.withName("conversionRate") ) ), variants = Seq( AbTestsVariant( index = "AB_TEST_1", trafficPercentage = 50 ), 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.estimateABTest(estimateABTestRequest: AbtestingEstimateABTestRequest( configuration: AbtestingEstimateConfiguration( emptySearch: EmptySearch(exclude: true), minimumDetectableEffect: AbtestingMinimumDetectableEffect( size: 0.03, metric: AbtestingEffectMetric.conversionRate ) ), variants: [ AbtestingAddABTestsVariant.abtestingAbTestsVariant(AbtestingAbTestsVariant( index: "AB_TEST_1", trafficPercentage: 50 )), AbtestingAddABTestsVariant.abtestingAbTestsVariant(AbtestingAbTestsVariant( index: "AB_TEST_2", trafficPercentage: 50 )), ] )) // print the response print(response) - lang: cURL label: curl source: |- curl --request POST \ --url https://analytics.us.algolia.com/2/abtests/estimate \ --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 ' { "configuration": { "featureFilters": { "dynamicReRanking": true, "aiPerso": true, "multiSignalRanking": true }, "outliers": { "exclude": true }, "emptySearch": { "exclude": true }, "minimumDetectableEffect": { "size": 0, "metric": "addToCartRate" } }, "variants": [ { "index": "delcourt_production", "trafficPercentage": 60, "description": "Current production index" }, { "index": "delcourt_production", "trafficPercentage": 60, "description": "Current production index" } ] } ' components: schemas: 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 EmptySearch: type: object description: Configuration for handling empty searches. properties: exclude: type: boolean description: Whether to exclude empty searches when calculating A/B test results. FeatureFilters: type: object description: >- Configuration of feature-based filters applied to the A/B test population. properties: aiPerso: type: boolean description: Whether to apply AI Personalization feature filters. dynamicReRanking: type: boolean description: Whether to apply Dynamic Re-Ranking feature filters. multiSignalRanking: type: boolean description: Whether to apply Multi-Signal Re-Ranking feature filters. Outliers: type: object description: Configuration for handling outliers. properties: exclude: type: boolean description: Whether to exclude outliers when calculating A/B test results. default: true AddABTestsVariant: oneOf: - $ref: '#/components/schemas/abTestsVariant' title: Variant - $ref: '#/components/schemas/abTestsVariantSearchParams' title: Variant with search parameters 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 required to achieve the desired statistical significance. items: type: integer format: int64 description: >- Number of tracked searches needed to be able to detect the configured effect for the control variant. example: 23415 EffectMetric: type: string description: Metric for which you want to detect the smallest relative difference. enum: - addToCartRate - clickThroughRate - conversionRate - purchaseRate 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' ErrorBase: description: Error. type: object x-keep-model: true additionalProperties: true properties: message: type: string example: Invalid Application-Id or API-Key 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: 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. ````