Experiment Evaluation API

The Amplitude 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

Region	URL
Standard Server	`https://api.lab.amplitude.com/v1/`
EU Residency Server	`https://api.lab.eu.amplitude.com/v1/`

Authorization

The evaluation APIs authenticates 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

GET /v1/vardata

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. If you have more than one flag key, separate them with commas, for example, `flag_keys=flag-A,flag-B`. If empty/missing, Experiment evaluates all flags & experiments associated with the deployment key.
`context`	JSON string consisting of a full user context. Set user properties in the `user_properties` field (for example: `{"user_properties":{"premium":true}}`). For more information about user context, see 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.

Evaluation response

The response body is a JSON object keyed by the flag key. The value for a given flag key is the variant assigned to the user. The variant contains its identification key (a.k.a value) and an optional payload containing a JSON element.

{
    "<flag_keys>": {
        "key": "<variant_value>",
        "payload": <variant_payload>
    },
    // ...
}

{
    "<flag_keys>": {
        "key": "<variant_value>",
        "payload": <variant_payload>
    },
    // ...
}

Empty results

If a user isn't in the target audience, the Evaluation API may return an empty object.

{}

{}

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 below to try the API from your browser or copy a curl.
400	If the request has invalid JSON in the context parameter, it returns a `400` status.
401	If the request doesn't include a valid API key, it returns a `401` response.

Evaluation example

Set the fields in the table, and press send to send the request in browser, or copy the curl to send the request yourself.

Flags API

GET /v1/flags

GET /v1/flags

The Flags API allows you to download flag configurations for local evaluations. This is useful for bootstrapping client-side local evaluation SDKs with initialFlags or running evaluation using external flag configuration storage like edge environments.

The data model returned by this API is different from what you may see in the management API for flags and experiments. This format is specifically used for evaluation purposes, which is more verbose and less human readable than the management API.

Flags query parameters

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

Flags headers

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

Flags response

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

[
  {
    "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"
      }
    }
  }
]

[
  {
    "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. Use the example below to try the API from your browser or copy a curl.
401	If the request doesn't include a valid API key, it returns a `401` response.