Experiments API

Tier: Free, Premium, Ultimate
Offering: GitLab.com

Use this API to interact with A/B experiments. This API is for internal use only.

Prerequisites:

You must be a GitLab team member.

List all experiments

Lists all experiments on the GitLab instance. Each experiment has an enabled status that indicates whether the experiment is enabled globally, or only in specific contexts.

GET /experiments

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments"

Example response:

[
  {
    "key": "code_quality_walkthrough",
    "definition": {
      "name": "code_quality_walkthrough",
      "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58900",
      "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/327229",
      "milestone": "13.12",
      "type": "experiment",
      "group": "group::activation",
      "default_enabled": false
    },
    "current_status": {
      "state": "conditional",
      "gates": [
        {
          "key": "boolean",
          "value": false
        },
        {
          "key": "percentage_of_actors",
          "value": 25
        }
      ]
    }
  },
  {
    "key": "ci_runner_templates",
    "definition": {
      "name": "ci_runner_templates",
      "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/58357",
      "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/326725",
      "milestone": "14.0",
      "type": "experiment",
      "group": "group::activation",
      "default_enabled": false
    },
    "current_status": {
      "state": "off",
      "gates": [
        {
          "key": "boolean",
          "value": false
        }
      ]
    }
  }
]

Delete cached assignments

Removes all cached variant assignments for an experiment from the cache store. Use this endpoint to clean up completed experiments whose code is removed from the codebase but whose cached assignments remain.

DELETE /experiments/:name/cache

Supported attributes:

Attribute	Type	Required	Description
`name`	string	Yes	Cache key of the experiment to clear.

If successful, returns 204 No Content.

The request returns 204 No Content even when no cached assignments exist for the given name. The request returns 400 Bad Request when the name references a cache key that is not an experiment. The request returns 401 Unauthorized when the request is not authenticated. The request returns 403 Forbidden when the user is not a GitLab team member.

The name value is used directly as the cache key. This endpoint clears any matching cache entry, even one that does not belong to a currently defined experiment. This behavior supports cleaning up orphaned experiments whose code is removed. Verify the name before you call this endpoint.

Example request:

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/experiments/code_quality_walkthrough/cache"