The Experiment Evaluation APIs retrieve variant assignment data for users through [remote evaluation](/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](/docs/feature-experiment/data-model#deployments) key set in the Authorization header with the prefix `Api-Key`. For example, `Authorization: Api-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](/docs/feature-experiment/data-model#full-user-definition). | ### Evaluation headers | Name | Description | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization` | Set to `Api-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. | {% callout type="warning" heading="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. {% /callout %} For example: ```json { "my-experiment": { "key": "treatment", "payload": { "price": 99.99, "discount": "25%" }, "expKey": "exp-1", "evaluationId": "224681772811_1760563672659_3681" } // ... } ``` {% callout type="note" heading="Empty results" %} If a user isn't in the target audience, the Evaluation API may return an empty object. ```json {} ``` {% /callout %} #### 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. {% api-tester type="evaluation" / %} --- ## 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](/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 ` 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. |