Retrieving experiment results using the Automation API

This tutorial describes how to request experiment results and determine winning variations using the Automation API. It follows previous tutorials on creating experiments, modifying variations, associating goals and segments, and launching experiments.

Requirements

access_token

The Automation API requires an access token. Retrieve the token programmatically by following the instructions in the Obtaining an access token section.

experimentId

The experimentId is the numeric identifier of the experiment you want results for. You can find it in the URL of the Kameleoon app while viewing the experiment (for example, https://app.kameleoon.com/.../experiments/188308/...). For feature flag experiments, the ID is shown in the Rollout Planner.

Goal

The tutorial uses the following example experiment:

This experiment, called Product Page Redesign, includes two variations in addition to the original version: Redesign 1 (ID 828220) and Redesign 2 (ID 828221). While the experiment has several objectives, this tutorial will focus solely on the main goal, which is to track insurance subscriptions through Click Tracking.

The tutorial also applies to Feature Flag experiments; however, use the https://api.kameleoon.com/feature-flags/* endpoints instead of https://api.kameleoon.com/experiments/*:

The experimentId is in the Rollout Planner:

How result retrieval works

Retrieving results is a two-step process:

Request results — POST to /experiments/{experimentId}/results. The response returns a dataCode hash, not the results themselves.
Poll for results — GET /results?dataCode=<dataCode> to retrieve the actual data.

The two cases in step 1 differ only in how you authenticate: directly with your access token (Case 1), or via a shared token that lets unauthenticated users view results (Case 2).

1. Retrieve the data code

The following key body parameters control what the report includes. For the full parameter reference, see the Request experiment’s results endpoint.

Field	Type	Description
`goalsIds`	integer[]	Goals to include. Pass `[goalId]` for a specific goal, `[]` to exclude all, or `null` to include all.
`referenceVariationId`	string	The variation to compare others against. Use `"0"` for the original variation.
`visitorData`	boolean	`true` counts unique visitors; `false` (default) counts all visits.
`sequentialTesting`	boolean	`true` enables sequential testing for confidence intervals.
`conversionType`	string	Counts to use for reliability calculations. `ALL_CONVERSION` counts every conversion event per visitor; `CONVERTED_VISITS` counts each visit at most once, regardless of how many conversion events occurred during it.

Case 1: Retrieve results directly

Send a POST request to the Request experiment’s results endpoint using your access token. Example:

curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
  "visitorData": false,
  "sequentialTesting": true,
  "referenceVariationId": "0",
  "goalsIds": [279599]
}'

Response:

{"dataCode":"14443931880924098266207585267983330260134079899081739889989435434342588016765"}

Pass this dataCode to step 2 to retrieve the actual results. Use this approach to let users view results without an access token — for example, to share a live results view with a stakeholder.

1. Retrieve a SharedToken

Fetch a SharedToken from the Share experiment results endpoint. This endpoint accepts the same request body as the results endpoint.

curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results/share' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
  "visitorData": false,
  "sequentialTesting": true,
  "referenceVariationId": "0",
  "goalsIds": [279599]
}'

Response:

{
    "method": "POST",
    "url": "https://api.kameleoon.com/experiments/188308/results",
    "path": "/experiments/188308/results",
    "headers": {
        "SharedToken": "eyJhbGciOiJIUzUxMiJ9.eyJleHAiOjE4NDQ5NDI5MTMsInNoYXJlZENvZGUiOiJhZmM1NzRjN2I4MjY4NTY3NzI2YjZhMDRhMTUxMjgyNjA3Zjk1ZGI4YjA1Y2RkZGY1ZDEwM2ExZDg5ZWM0MmZmIn0.oCECNm5mEhgIthc6eejo9BrfB7p8kEIrpoqtNb4JUiHK6nsxWHMvLc4hHYXCg3DgaBlVoKv6eEZHGty9c-VAoA",
        "Content-Type": "application/json"
    },
    "payload": {
        "visitorData": false,
        "sequentialTesting": true,
        "referenceVariationId": "0",
        "goalsIds": [279599]
    }
}

2. Retrieve the dataCode with the SharedToken

Send a POST request to the Request experiment’s results endpoint using the SharedToken from the previous response in place of an access token.

curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'SharedToken: <SHARED_TOKEN>' \
--data-raw '{
  "visitorData": false,
  "sequentialTesting": true,
  "referenceVariationId": "0",
  "goalsIds": [279599]
}'

Response:

{"dataCode":"14443931880924098266207585267983330260134079899081739889989435434342588016765"}

2. Retrieve the experiment results

After receiving the dataCode from either case above, call the result endpoint.

curl -L -X GET 'https://api.kameleoon.com/results?dataCode=14443931880924098266207585267983330260134079899081739889989435434342588016765'

If the response returns "status": "WAITING", the report is still generating. Retry the request after a short delay until the status is "READY".

Response:

{
 "status": "READY",
 "data": {
  "dataCode": "14443931880924098266207585267983330260134079899081739889989435434342588016765",
  "variationData": {
   "_reference": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 126862,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 1898,
         "convertedVisitCount": 1898,
         "revenueCount": 235352.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 1.86,
         "revenuePerVisitor": 0.0,
         "conversionRate": 0.014961138875313333,
         "averageCart": 124.0,
         "ratioValue": 0.0,
         "outlierBounds": {
          "lower": 0.1,
          "upper": 99.0
         }
        }
       }
      }
     }
    }
   },
   "828220": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 167938,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 7826,
         "convertedVisitCount": 7826,
         "revenueCount": 986076.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 5.87,
         "revenuePerVisitor": 0.0,
         "reliability": 100.0,
         "improvementRange": {
          "min": 193.92,
          "max": 229.03,
          "half": 17.56
         },
         "improvementRate": 211.48,
         "conversionRate": 0.04660053114840001,
         "averageCart": 126.0,
         "ratioValue": 0.0,
         "continuousMetrics": {
          "conversions": {
           "reliability": 1.0,
           "improvementRate": 2.114771645178252,
           "halfInterval": 0.10445147824911348,
           "lowerBound": 2.0103201669291386,
           "upperBound": 2.219223123427365
          },
          "revenuePerVisit": {
           "reliability": 1.0,
           "improvementRate": 2.1650098975198366,
           "halfInterval": 0.10613617951119597,
           "lowerBound": 2.0588737180086407,
           "upperBound": 2.2711460770310326
          },
          "averageCart": null
         },
         "outlierBounds": {
          "lower": 0.1,
          "upper": 99.0
         }
        }
       }
      }
     }
    }
   },
   "828221": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 174194,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 1477,
         "convertedVisitCount": 1477,
         "revenueCount": 189056.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 1.09,
         "revenuePerVisitor": 0.0,
         "reliability": 100.0,
         "improvementRange": {
          "min": -47.93,
          "max": -38.72,
          "half": 4.6
         },
         "improvementRate": -43.33,
         "conversionRate": 0.00847905209134643,
         "averageCart": 128.0,
         "ratioValue": 0.0,
         "continuousMetrics": {
          "conversions": {
           "reliability": 1.0,
           "improvementRate": -0.4332615877700786,
           "halfInterval": 0.027369693136479373,
           "lowerBound": -0.46063128090655797,
           "upperBound": -0.40589189463359926
          },
          "revenuePerVisit": {
           "reliability": 1.0,
           "improvementRate": -0.41497970350459723,
           "halfInterval": 0.028252586463462577,
           "lowerBound": -0.4432322899680598,
           "upperBound": -0.38672711704113466
          },
          "averageCart": null
         },
         "outlierBounds": {
          "lower": 0.1,
          "upper": 99.0
         }
        }
       }
      }
     }
    }
   }
  },
  "ventilationNames": null,
  "cupedDataByGoalId": {}
 }
}

3. Interpreting the results to determine the winning variation

Winning variations must demonstrate high reliability (exceeding 95%) and a positive improvement rate compared to the reference variation. The JSON response shows that both Redesign 1 and Redesign 2 have a 100% reliability rate. However, Redesign 1 has a +211.48% improvement rate compared to the -43.33% rate of Redesign 2. Therefore, Redesign 1 is the winner. Redesign 1

"828220": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 167938,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 7826,
         "convertedVisitCount": 7826,
         "revenueCount": 986076.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 5.87,
         "revenuePerVisitor": 0.0,
         "reliability": 100.0,
         "improvementRange": {
          "min": 193.92,
          "max": 229.03,
          "half": 17.56
         },
         "improvementRate": 211.48,

Redesign 2

"828221": {
    "breakdownData": {
     "_reference": {
      "intervalData": {},
      "generalData": {
       "visitCount": 174194,
       "visitorCount": 0,
       "goalsData": {
        "279599": {
         "conversionCount": 1477,
         "convertedVisitCount": 1477,
         "revenueCount": 189056.0,
         "convertedVisitorCount": 0,
         "revenuePerVisit": 1.09,
         "revenuePerVisitor": 0.0,
         "reliability": 100.0,
         "improvementRange": {
          "min": -47.93,
          "max": -38.72,
          "half": 4.6
         },
         "improvementRate": -43.33,

4. Filter experiment results

Obtain specific results by using the breakdown and filters parameters. The breakdown parameter organizes data by a single dimension (such as browser, operating system, or day of the week). The filters parameter restricts data to a subset of visitors before the breakdown is applied.

The breakdown parameter accepts a single object per request, not an array. To compare several dimensions, send one request per breakdown.

Breakdown formats

Most breakdown types take only a type field, for example:

"breakdown": {
  "type": "BROWSER"
}

Three breakdown types require additional fields: INTERVAL — segments results by a time interval. Pair "type": "INTERVAL" with an interval field:

"breakdown": {
  "type": "INTERVAL",
  "interval": "DAY"
}

The interval field accepts HOUR, DAY, WEEK, MONTH, or YEAR. CUSTOM_DATUM — segments results by custom data index. Pair "type": "CUSTOM_DATUM" with an index field:

"breakdown": {
  "type": "CUSTOM_DATUM",
  "index": 3
}

CROSS_CAMPAIGN — segments results by exposure to another experiment or personalization. Provide at least one of experiments or personalizations:

"breakdown": {
  "type": "CROSS_CAMPAIGN",
  "experiments": [188309],
  "personalizations": []
}

Filter types

Each filter object requires a type string and an include boolean. Set include to true to restrict results to matching visitors, or false to exclude them. The additional fields depend on type:

`type`	Additional fields	Accepted values
`BROWSER`	`values` (string[])	`CHROME`, `EDGE`, `FIREFOX`, `SAFARI`, `OPERA`, `OTHERS`
`DEVICE_TYPE`	`values` (string[])	`DESKTOP`, `TABLET`, `PHONE`, `OTHERS`
`OS`	`values` (string[])	`WINDOWS`, `MAC_OS`, `I_OS`, `LINUX`, `ANDROID`, `WINDOWS_PHONE`, `OTHERS`
`NEW_VISITOR`	`visitorsType` (string)	`NEW_VISITORS`, `RETURNING_VISITORS`
`ORIGIN_TYPE`	`values` (string[])	`SEO`, `SEM`, `AFFILIATION`, `EMAIL`, `DIRECT`
`SDK`	`values` (string[])	`JAVA`, `ANDROID`, `GO`, `DOTNET`, `PYTHON`, `RUBY`, `IOS`, `PHP`, `JAVASCRIPT`, `NODEJS`, `REACT`, `RUST`, `ELIXIR`
`DAY_OF_WEEK`	`values` (string[])	`SUNDAY`, `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`
`WEATHER_CODE`	`values` (string[])	`CLEAR_SKY`, `CLOUDS`, `RAIN`, `THUNDERSTORM`, `SNOW`, `HAIL`, `WIND`, `ATMOSPHERIC_DISTURBANCES`
`LANGUAGE`	`values` (string[])	ISO 639-1 language codes (e.g., `EN`, `FR`, `DE`)
`CUSTOM_DATUM`	`customDataId` (integer), `value` (string)	Any custom data value
`TARGETING_SEGMENT`	`values` (integer[])	Segment IDs
`GOAL_REACHED`	`goalId` (integer), `index` (integer), `value` (string)

Example: browser breakdown filtered to new visitors

The following request applies a browser breakdown restricted to new visitors by sending a POST to the Request experiment’s results endpoint:

curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
--data-raw '{
  "visitorData": true,
  "sequentialTesting": true,
  "breakdown": {
    "type": "BROWSER"
  },
  "referenceVariationId": "0",
  "filters": [
    {
      "type": "NEW_VISITOR",
      "visitorsType": "NEW_VISITORS",
      "include": true
    }
  ],
  "goalsIds": [279599]
}'

After receiving the dataCode, retrieve the results:

curl -L -X GET 'https://api.kameleoon.com/results?dataCode=14443931880924098266207585267983330260134079899081739889989435434342588016765'

A successful response returns results broken down by browser. The response follows the same structure as step 2 above, with each browser type (CHROME, FIREFOX, OTHERS, etc.) as a key within breakdownData. The following response is truncated for clarity:

{
  "status": "READY",
  "data": {
    "variationData": {
      "828221": {
        "breakdownData": {
          "OTHERS": {
            "intervalData": {},
            "generalData": {
              "visitCount": 0,
              "visitorCount": 587206,
              "goalsData": {
                "279599": {
                  "conversionCount": 5410,
                  "revenueCount": 692480.0,
                  "convertedVisitorCount": 5359,
                  "revenuePerVisitor": 1.18,
                  "reliability": 100.0,
                  "improvementRange": {
                    "min": -53.0,
                    "max": -48.7,
                    "half": 2.15
                  },
                  "improvementRate": -50.85,
                  "conversionRate": 0.009126269145751235,
                  "averageCart": 129.22,
                  "ratioValue": 0.0
                }
              }
            }
          },
          "CHROME": {
            "intervalData": {},
            "generalData": {
              "visitCount": 0,
              "visitorCount": 16,
              "goalsData": {
                "279599": {
                  "conversionCount": 0,
                  "revenueCount": 0.0,
                  "reliability": 50.0,
                  "improvementRate": 0.0,
                  "averageCart": 0.0,
                  "ratioValue": 0.0
                }
              }
            }
          }
        }
      }
    },
    "ventilationNames": null,
    "cupedDataByGoalId": {}
  }
}

​Requirements

​Goal

​How result retrieval works

​1. Retrieve the data code

​Case 1: Retrieve results directly

​Case 2: Share results without authorization

​1. Retrieve a SharedToken

​2. Retrieve the dataCode with the SharedToken

​2. Retrieve the experiment results

​3. Interpreting the results to determine the winning variation

​4. Filter experiment results

​Breakdown formats

​Filter types

​Example: browser breakdown filtered to new visitors

Requirements

Goal

How result retrieval works

1. Retrieve the data code

Case 1: Retrieve results directly

Case 2: Share results without authorization

1. Retrieve a SharedToken

2. Retrieve the dataCode with the SharedToken

2. Retrieve the experiment results

3. Interpreting the results to determine the winning variation

4. Filter experiment results

Breakdown formats

Filter types

Example: browser breakdown filtered to new visitors