---
title: "List experiment holdouts"
method: GET
path: "/api/v2/experiments/{experiment_id}/holdouts"
tags: ["Experiments"]
---

# List experiment holdouts

`GET /api/v2/experiments/{experiment_id}/holdouts`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/experiments/{experiment_id}/holdouts`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `product_analytics_experiments_read`

List the holdouts an experiment is attached to, in evaluation order: MANAGED holdouts first, starting with the GLOBAL holdout, followed by EXTERNAL holdouts. For a draft experiment, the response includes the GLOBAL holdout that the experiment would join if it started. The response excludes archived and deleted holdouts, and MANAGED holdouts past their analysis window. EXTERNAL holdouts are listed until they are archived. MANAGED holdouts are listed only for experiments that use a Datadog feature flag, because Datadog serves holdouts only through its flags. The order matches the experiment's `holdout_ids` attribute.

## Path parameters

- `experiment_id` string, uuid, required: The UUID of the experiment.

## Response `200`

OK

- ExperimentsExperimentHoldoutV2DTOArray: Response containing the holdouts an experiment is attached to.
  - `data` ExperimentsExperimentHoldoutV2DTOData[], required: Holdouts the experiment is attached to, in evaluation order.
    - `attributes` ExperimentsExperimentHoldoutV2DTODataAttributes: Attributes of a holdout that the experiment is attached to.
      - `evaluation_order` integer, nullable: Zero-based position of this MANAGED holdout in the experiment's evaluation order. The GLOBAL holdout is evaluated first. Null for EXTERNAL holdouts.
      - `holdout_type` 'GLOBAL' | 'SELECTIVE' | 'UNKNOWN', nullable: How Datadog serves a MANAGED holdout. GLOBAL holdouts apply to every eligible experiment of a subject type. SELECTIVE holdouts apply only to the experiments attached to them. Null for EXTERNAL holdouts.
      - `key` string: Key of the holdout.
      - `kind` 'MANAGED' | 'EXTERNAL' | 'UNKNOWN': Whether Datadog serves the holdout. Datadog serves MANAGED holdouts. EXTERNAL holdouts record what your own feature flagging system holds back, and Datadog does not serve them.
      - `name` string: Display name of the holdout.
      - `state` 'PENDING' | 'INCLUDING' | 'WAITING_FOR_ANALYSIS' | 'ANALYSING' | 'COMPLETE' | 'UNKNOWN': Lifecycle phase of the holdout. PENDING holdouts have not started including experiments. INCLUDING holdouts are adding experiments. WAITING_FOR_ANALYSIS holdouts have stopped including experiments but have not started analysis. ANALYSING holdouts are in their analysis window. COMPLETE applies only to EXTERNAL holdouts that have ended their analysis window but are not archived.
      - `traffic_allocation` number, double: Share of subjects the holdout holds back, from 0 to 1.
    - `id` string, uuid, required: Identifier of the holdout.
    - `type` 'experiment-holdouts', required: Experiment holdout resource type.

## Other responses

- `400`: Malformed experiment ID (not a valid UUID).
- `401`: Missing or invalid authentication.
- `403`: The caller lacks the `product_analytics_experiments_read` permission or lacks permission to view this experiment.
- `404`: No experiment with this ID exists for the organization.
- `429`: Too many requests

## Changes

- **2026-11-12** `6cc2bb1f7a80`: 4 info
  - added the optional property `errors/items/code` to the response with the `400` status
  - added the optional property `errors/items/code` to the response with the `401` status
  - added the optional property `errors/items/code` to the response with the `403` status
  - added the optional property `errors/items/code` to the response with the `404` status
- **2026-11-11** `d8509050c0a6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/changes/api/v2/experiments/:experiment_id/holdouts/get.md)

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/14d85160bfa9?raw)
