---
title: "Start experiment"
method: POST
path: "/api/v2/experiments/{experiment_id}/start"
tags: ["Experiments"]
---

# Start experiment

`POST /api/v2/experiments/{experiment_id}/start`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/experiments/{experiment_id}/start`
- 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_write`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/experiments/:experiment_id/start/post.ts> (a function with typed inputs; its response is checked against the schema)

Start an experiment. The experiment is started exactly as it is configured; this endpoint accepts no attributes, and a request body carrying any is rejected rather than ignored. Set the run window, duration, or variants with PATCH /api/v2/experiments/{experiment_id} before starting. An unconfigured draft returns HTTP 409. Configure either warehouse_exposure_configuration or datadog_flag_configuration, plus the required experiment fields, before starting. Start validation errors can include meta.configuration_pointer to identify a field on the experiment to correct. For a flag-backed experiment this enables the linked feature flag's environment, clears any stored variant override on it, and starts the allocation's rollout. The request is idempotent: an experiment that is already running or ready for a decision still returns 204, so a retry after a timeout is safe. One exception: an experiment scheduled to start is accepted only when it is backed by your own feature flag; a Datadog-flag experiment in that state returns 409 because its stored state and flag allocation disagree. Cancel and conclude are not idempotent and return 409 when repeated.

## Path parameters

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

## Request body

- ExperimentsStartExperimentV2Request: Request to start the experiment.
  - `data` ExperimentsStartExperimentV2RequestData, required: JSON:API resource containing the experiment identity.
    - `id` string: ID of the experiment.
    - `type` 'start-experiment-request', required: Start experiment request resource type.

## Response `204`

The experiment was started.

## Other responses

- `400`: Malformed experiment ID, a request body carrying attributes this endpoint does not accept, or an experiment managed by a specialized workflow that cannot use this start endpoint.
- `401`: Missing or invalid authentication (dd-api-key + dd-application-key headers, or a valid user session).
- `403`: Authenticated caller lacks the product_analytics_experiments_write permission, lacks permission to edit this experiment, or lacks contribute permission on the feature flag owning its allocation.
- `404`: No experiment with this ID exists for the organization.
- `409`: The experiment cannot be started from its current state, its stored setup is incomplete (missing subject type, primary metric, variants, assignment source, or run window), its linked feature flag environment requires an approval, or that flag has a pending suggestion for a property this would change (environment status, override variant, rollout, or allocations).
- `429`: Too many requests

---

[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/3f70db624329?raw)