# Experiment Evaluation API

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

The Experiment Evaluation APIs retrieve variant assignment data for users through [remote evaluation](https://amplitude.com/docs/feature-experiment/remote-evaluation) using the [evaluation API](#evaluation-api), or download local evaluation flags using the [flags API](#flags-api).

## Regions

| Data residency | Base URL |
| --- | --- |
| Default | `https://api.lab.amplitude.com/v1/` |
| EU | `https://api.lab.eu.amplitude.com/v1/` |

## Authorization

The evaluation APIs authenticate the request using your [deployment](https://amplitude.com/docs/feature-experiment/data-model#deployments) key set in the Authorization header with the prefix `Api-Key`. For example, `Authorization: Api-Key <deployment_key>`.

---

## Evaluation API

```text
GET /v1/vardata
```

The Evaluation API lets you retrieve variant assignment data for users. When you call this API, Amplitude tracks an `[Experiment] Assignment` event.

### Evaluation query parameters

| Name | Description |
| --- | --- |
| `user_id` | The user's ID. |
| `device_id` | The user's device ID. |
| `flag_keys` | Specific flag keys to get the variants of. To request more than one flag key, separate them with commas, for example, `flag_keys=flag-A,flag-B`. If empty or missing, Experiment evaluates all flags and experiments associated with the deployment key. |
| `context` | JSON string containing a full user context. Set user properties in the `user_properties` field, for example, `{"user_properties":{"premium":true}}`. For more about user context, refer to the definition in the [Data Model](https://amplitude.com/docs/feature-experiment/data-model#full-user-definition). |

### Evaluation headers

| Name | Description |
| --- | --- |
| `Authorization` | Set to `Api-Key <deployment_key>` for authentication. |
| `X-Amp-Exp-Track` | Set to `no-track` to not track an assignment event for the evaluation. |
| `X-Amp-Exp-Exposure-Track` | Controls whether the server tracks an `[Experiment] Exposure` event for each flag. Defaults to `no-track`. Set to `track` to track an exposure event for each evaluated flag. |

### Evaluation response

The response body is a JSON object keyed by the flag key. The value for each flag key is the variant assigned to the user. Each variant object contains the following fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | Required | The assigned variant key for the flag/experiment. |
| `payload` | `any` | Optional | The variant's payload (if set). Can be any valid JSON value. |
| `expKey` | `string` | Optional | The experiment key, used to differentiate between different runs of the same experiment. |
| `evaluationId` | `string` | Optional | The evaluation ID, used for debugging purposes. |

> **Warning:** Unexpected response fields.
>
> The variant object for each flag may include additional response fields in the future. Your code must handle these additional fields gracefully.

For example:

```json
{
  "my-experiment": {
    "key": "treatment",
    "payload": { "price": 99.99, "discount": "25%" },
    "expKey": "exp-1",
    "evaluationId": "224681772811_1760563672659_3681"
  }
  // ...
}
```

> **Note:** Empty results
>
> If a user isn't in the target audience, the Evaluation API may return an empty object.
>
> ```json
> {}
> ```

#### Evaluation response status codes

| Status Code | Description |
| --- | --- |
| 200 | A successful request returns a `200` response and a map of flag key to variants. If `flag_keys` isn't provided, Experiment evaluates all flags associated with the deployment key in the authorization header. Use the [example](#evaluation-example) to try the API from your browser or copy a curl. |
| 400 | The request has invalid JSON in the context parameter. |
| 401 | The request doesn't include a valid API key. |

### Evaluation example

Set the fields in the table, then select **Send** to make the request in your browser, or copy the curl command to run the request yourself.

---

## Flags API

```text
GET /v1/flags
```

The Flags API lets you download flag configurations for local evaluations. Use the Flags API to bootstrap client-side local evaluation SDKs with `initialFlags`, or to run evaluation using external flag configuration storage such as edge environments.

The data model returned by this API differs from the [management API](https://amplitude.com/docs/apis/experiment/experiment-management-api) format for flags and experiments. The Flags API format supports evaluation, so it's more verbose and less human-readable than the management API format.

### Flags query parameters

| Name | Description |
| --- | --- |
| `flag_keys` | Specific flag keys to get the flag configurations for. To request more than one flag key, separate them with commas, for example, `flag_keys=flag-A,flag-B`. If empty or missing, the API returns all flags and experiments associated with the deployment key. |

### Flags headers

| Name | Description |
| --- | --- |
| `Authorization` | Set to `Api-Key <deployment_key>` for authentication. |

### Flags response

The Flags API returns a JSON array of objects, where each object represents a flag or experiment. For example, here's a basic response with a single flag.

```json
[
  {
    "key": "example-flag",
    "metadata": {
      "deployed": true,
      "evaluationMode": "local",
      "flagType": "release",
      "flagVersion": 42
    },
    "segments": [
      {
        "metadata": {
          "segmentName": "All Other Users"
        },
        "variant": "off"
      }
    ],
    "variants": {
      "off": {
        "key": "off",
        "metadata": {
          "default": true
        }
      },
      "on": {
        "key": "on",
        "value": "on"
      }
    }
  }
]
```

#### Flags response status codes

| Status Code | Description |
| --- | --- |
| 200 | A successful request returns a `200` response with an array of flag configurations. |
| 401 | The request doesn't include a valid API key. |