> ## Documentation Index > Fetch the complete documentation index at: https://algolia.com/llms.txt > Use this file to discover all available pages before exploring further. # List all A/B tests > Lists all A/B tests you configured for this application. **Required ACL:** `analytics` ## OpenAPI ````yaml specs/abtesting-v3.yml get /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: get: tags: - abtest summary: List all A/B tests description: Lists all A/B tests you configured for this application. operationId: listABTests parameters: - name: direction in: query description: > Sort order for A/B tests by start date. Use 'asc' for ascending or 'desc' for descending. Active A/B tests are always listed first. example: desc schema: $ref: '#/components/schemas/direction' - 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: limit in: query description: Number of items to return. required: false schema: type: integer default: 10 - name: offset in: query description: Position of the first item to return. required: false schema: type: integer default: 0 minimum: 0 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' 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.ListABTestsAsync(); // 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.listABTests(); // 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.ListABTests(client.NewApiListABTestsRequest()) 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 ListABTestsResponse response = client.listABTests(); // 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.listABTests(); // 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.listABTests() // 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->listABTests(); // 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.list_ab_tests() # 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.list_ab_tests # 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.listABTests( ), 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.listABTests() // print the response print(response) - lang: cURL label: curl source: |- curl --request GET \ --url 'https://analytics.us.algolia.com/3/abtests?offset=0&limit=10&indexPrefix=dev_&indexSuffix=_development&direction=desc' \ --header 'accept: application/json' \ --header 'x-algolia-api-key: ALGOLIA_API_KEY' \ --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' components: schemas: direction: type: string description: | Sort order for A/B tests by start date. Use 'asc' for ascending or 'desc' for descending. Active A/B tests are always listed first. enum: - asc - desc example: desc ABTests: oneOf: - type: array description: A/B tests. items: $ref: '#/components/schemas/ABTest' - type: 'null' ABTest: type: object additionalProperties: false properties: abTestID: $ref: '#/components/schemas/abTestID' createdAt: $ref: '#/components/schemas/createdAt' endAt: $ref: '#/components/schemas/endAt' name: $ref: '#/components/schemas/name' status: $ref: '#/components/schemas/Status' updatedAt: $ref: '#/components/schemas/updatedAt' variants: $ref: '#/components/schemas/variants' configuration: $ref: '#/components/schemas/ABTestConfiguration' migratedAbTestID: $ref: '#/components/schemas/MigratedABTestId' stoppedAt: $ref: '#/components/schemas/stoppedAt' required: - status - name - createdAt - endAt - updatedAt - abTestID - variants ErrorBase: description: Error. type: object x-keep-model: true additionalProperties: true properties: message: type: string example: Invalid Application-Id or API-Key abTestID: type: integer description: Unique A/B test identifier. example: 224 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' name: type: string description: A/B test name. example: Custom ranking sales rank test Status: type: string description: > A/B test status. - `active`. The A/B test is live and search traffic is split between the two variants. - `stopped`. You stopped the A/B test. The A/B test data is still available for analysis. - `expired`. The A/B test was automatically stopped after reaching its end date. - `failed`. Creating the A/B test failed. example: active enum: - active - stopped - expired - failed 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' variants: type: array description: > A/B test variants. The first variant is your _control_ index, typically your production index. All of the additional variants are indexes with changed settings that you want to test against the control. items: $ref: '#/components/schemas/variant' 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' MigratedABTestId: type: integer description: Unique migrated A/B test identifier. example: 224 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 variant: type: object additionalProperties: false properties: description: $ref: '#/components/schemas/description' index: $ref: '#/components/schemas/index' metrics: $ref: '#/components/schemas/metrics' trafficPercentage: $ref: '#/components/schemas/trafficPercentage' customSearchParameters: type: object description: > Search parameters applied to this variant when the same index is used for multiple variants. Only present if custom search parameters were provided during test creation. example: enablePersonalization: true personalizationImpact: 50 estimatedSampleSize: type: integer description: > Estimated number of searches required to achieve the desired statistical significance. The A/B test configuration must include a `minimumDetectableEffect` setting for this number to be included in the response. example: 0 metadata: $ref: '#/components/schemas/variantMetadata' required: - index - description - trafficPercentage - metrics 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 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 metrics: type: array description: All ABTest metrics that were defined during test creation. items: $ref: '#/components/schemas/metricResult' trafficPercentage: type: integer description: Percentage of search requests each variant receives. minimum: 1 maximum: 99 example: 60 variantMetadata: type: object description: Variant specific metadata. properties: filterEffects: $ref: '#/components/schemas/filterEffects' 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 metricResult: type: object properties: name: type: string pValue: type: number format: double description: >- PValue for the first variant (control) will always be 0. For the other variants, pValue is calculated for the current variant based on the control. updatedAt: type: string description: Date and time when the metric was last updated, in RFC 3339 format. value: type: number format: double criticalValue: type: number format: double description: > The value that was computed during error correction. It is used to determine significance of the metric pValue. The critical value is calculated using Bonferroni or Benjamini-Hochberg corrections, based on the given configuration during the A/B test creation. dimension: type: string description: Dimension defined during test creation. metadata: $ref: '#/components/schemas/metricMetadata' significant: type: boolean description: > Whether the pValue is significant or not based on the critical value and the error correction algorithm used. valueCIHigh: type: number format: double description: > The upper bound of the 95% confidence interval for the metric value. The confidence interval is calculated using either the relative ratio or relative difference between the metric values for the control and the variant. Relative ratio is used for metrics that are ratios (e.g., click-through rate, conversion rate), while relative difference is used for continuous metrics (e.g., revenue). valueCILow: type: number format: double description: > The lower bound of the 95% confidence interval for the metric value. The confidence interval is calculated using either the relative ratio or relative difference between the metric values for the control and the variant. Relative ratio is used for metrics that are ratios (e.g., click-through rate, conversion rate), while relative difference is used for continuous metrics (e.g., revenue). required: - name - updatedAt - value - pValue example: - name: addToCartCount updatedAt: '2025-06-15T15:06:44.400601Z' value: 5 pValue: 0.01 - name: clickThroughRate updatedAt: '2025-05-15T17:52:15.644906Z' value: 0.20869847452125934 pValue: 0.004 - 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 filterEffects: type: object description: A/B test filter effects resulting from configuration settings. properties: 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: trackedSearchesCount: type: integer description: Number of tracked searches removed from the A/B test. example: 237 usersCount: type: integer description: Number of users removed from the A/B test. example: 1 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: trackedSearchesCount: type: integer description: Number of tracked searches removed from the A/B test. example: 237 usersCount: type: integer description: Number of users removed from the A/B test. example: 1 metricMetadata: type: object description: Metric specific metadata. properties: mean: type: number format: double description: Mean value for this metric. example: 53.7 winsorizedValue: type: number format: double description: > Only present in case the metric is 'revenue'. It is the amount exceeding the 95th percentile of global revenue transactions involved in the AB Test. This amount is not considered when calculating statistical significance. It is tied to a per revenue-currency pair contrary to other global filter effects (such as outliers and empty search count). example: winsorizedValue: 888.8 mean: 53.7 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. ````