Start experiment

POST https://api.ap1.datadoghq.com/api/v2/experiments/{experiment_id}/starthttps://api.ap2.datadoghq.com/api/v2/experiments/{experiment_id}/starthttps://api.datadoghq.eu/api/v2/experiments/{experiment_id}/starthttps://api.ddog-gov.com/api/v2/experiments/{experiment_id}/starthttps://api.us2.ddog-gov.com/api/v2/experiments/{experiment_id}/starthttps://api.uk1.datadoghq.com/api/v2/experiments/{experiment_id}/starthttps://api.datadoghq.com/api/v2/experiments/{experiment_id}/starthttps://api.us3.datadoghq.com/api/v2/experiments/{experiment_id}/starthttps://api.us5.datadoghq.com/api/v2/experiments/{experiment_id}/start

Overview

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. This endpoint requires the product_analytics_experiments_write permission.

OAuth apps require the product_analytics_experiments_write authorization scope to access this endpoint.

Arguments

Path Parameters

Request

Body Data

{
  "data": {
    "id": "string",
    "type": "start-experiment-request"
  }
}

Response

• 204
• 400
• 401
• 403
• 404
• 409
• 429

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  ## default
# 

# Path parameters
export experiment_id="550e8400-e29b-41d4-a716-446655440000"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/experiments/${experiment_id}/start" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "type": "start-experiment-request"
  }
}
EOF