> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieving experiment results using the Automation API
> Request experiment results, identify winning variations by improvement rate, and apply breakdowns and filters 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](./create-a-new-experiment), [modifying variations](./add-and-edit-javascript-in-the-variant-of-your-new-experiment), [associating goals and segments](./create-a-segment-to-target-visitors-by-page-url), and [launching experiments](./add-a-goal-and-segment-to-your-experiment-before-launching).
## Requirements
* `access_token`
The Automation API requires an [access token](/developer-docs/apis/automation-api-rest/get-started/get-started). Retrieve the token programmatically by following the instructions in the [Obtaining an access token section](/developer-docs/apis/automation-api-rest/get-started/get-started#1-obtain-an-access-token).
* `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/*`:
* [Share feature flag results endpoint](/api-reference/featureflag/share-feature-flag-results)
* [Request feature flag's results endpoint](/api-reference/featureflag/request-feature-flags-results/)
* [Result endpoint](/api-reference/data/poll-results)
The `experimentId` is in the **Rollout Planner**:
## How result retrieval works
Retrieving results is a two-step process:
1. **Request results** — POST to `/experiments/{experimentId}/results`. The response returns a `dataCode` hash, not the results themselves.
2. **Poll for results** — GET `/results?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](/api-reference/experiment/request-experiments-results/).
| 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](/api-reference/experiment/request-experiments-results/) using your access token.
**Example:**
```shell theme={null}
curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer ' \
--data-raw '{
"visitorData": false,
"sequentialTesting": true,
"referenceVariationId": "0",
"goalsIds": [279599]
}'
```
**Response:**
```json theme={null}
{"dataCode":"14443931880924098266207585267983330260134079899081739889989435434342588016765"}
```
Pass this `dataCode` to [step 2](#2-retrieve-the-experiment-results) to retrieve the actual results.
### Case 2: Share results without authorization
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](/api-reference/experiment/share-experiment-results). This endpoint accepts the same request body as the results endpoint.
```shell theme={null}
curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results/share' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer ' \
--data-raw '{
"visitorData": false,
"sequentialTesting": true,
"referenceVariationId": "0",
"goalsIds": [279599]
}'
```
**Response:**
```json theme={null}
{
"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](/api-reference/experiment/request-experiments-results/) using the `SharedToken` from the previous response in place of an access token.
```shell theme={null}
curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'SharedToken: ' \
--data-raw '{
"visitorData": false,
"sequentialTesting": true,
"referenceVariationId": "0",
"goalsIds": [279599]
}'
```
**Response:**
```json theme={null}
{"dataCode":"14443931880924098266207585267983330260134079899081739889989435434342588016765"}
```
## 2. Retrieve the experiment results
After receiving the `dataCode` from either case above, call the [result endpoint](/api-reference/data/poll-results).
```shell theme={null}
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:**
```json theme={null}
{
"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**
```json theme={null}
"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**
```json theme={null}
"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:
```json theme={null}
"breakdown": {
"type": "BROWSER"
}
```
Three breakdown types require additional fields:
**`INTERVAL`** — segments results by a time interval. Pair `"type": "INTERVAL"` with an `interval` field:
```json theme={null}
"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:
```json theme={null}
"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`:
```json theme={null}
"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](/api-reference/experiment/request-experiments-results/):
```shell theme={null}
curl -L -X POST 'https://api.kameleoon.com/experiments/188308/results' \
-H 'Content-Type: application/json' \
-H 'Accept: */*' \
-H 'Authorization: Bearer ' \
--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:
```shell theme={null}
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:
```json theme={null}
{
"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": {}
}
}
```