Experiment Evaluation API

The Experiment Evaluation APIs retrieve variant assignment data for users through remote evaluation using the evaluation API, or download local evaluation flags using the 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 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.

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.

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"
  }
  // ...
}

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 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.

Evaluation example

GET · /v1/vardataEvaluation API

cURLGET · /v1/vardata

1
2
3curl --request GET \
  --url 'https://api.lab.amplitude.com/v1/vardata' \
  --header 'Authorization: Api-Key deployment_key'

$ awaiting send…

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 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.

Was this helpful?