DAdatadog
Experiments

Create experiment

Create a draft experiment. name is required. structured_metadata identifies each metadata field by field_key; use freetext_value for free-text fields and enum_values for enum fields. When this attribute is present, the request must include a value for every required metadata field. When protocol_id is present, the published protocol supplies the subject type, decision metrics, analysis-plan defaults, and configuration and enforcement baselines. The request may also include hypothesis, tags, teams, related links, and assignment or event date overrides that satisfy the protocol's duration rules; omit subject_type_id, decision_metrics, variants, warehouse_exposure_configuration, datadog_flag_configuration, traffic_exposure, split_by_properties, and structured_metadata. The protocol association cannot be changed after creation. Without protocol_id, a complete Warehouse or Datadog configuration saves the experiment and its configuration in one transaction. For Datadog flag configuration, send name, subject_type_id, decision_metrics, variants, traffic_exposure, assignments_start_date, assignments_end_date, events_start_date, and events_end_date. The four date fields can be null. Inside datadog_flag_configuration, send feature_flag_id, environment_id, targeting_rules, and entry_point. Use targeting_rules: [] and entry_point: null when unused. This creates one saved draft allocation that does not serve traffic. Omit all configuration fields to create an experiment without an allocation. This endpoint is not idempotent.

post/api/v2/experiments

Request

Request body

Example request

{
  "data": {
    "attributes": {
      "assignments_end_date": "2026-08-15T00:00:00Z",
      "assignments_start_date": "2026-08-01T00:00:00Z",
      "datadog_flag_configuration": {
        "entry_point": null,
        "environment_id": "550e8400-e29b-41d4-a716-446655440005",
        "feature_flag_id": "550e8400-e29b-41d4-a716-446655440004",
        "targeting_rules": []
      },
      "decision_metrics": [
        {
          "is_primary": true,
          "metric_id": "b1a2c3d4-0000-0000-0000-000000000000"
        }
      ],
      "events_end_date": "2026-08-22T00:00:00Z",
      "events_start_date": "2026-08-01T00:00:00Z",
      "name": "Checkout button test",
      "structured_metadata": [
        {
          "enum_values": [
            "beta"
          ],
          "field_key": "launch_stage"
        },
        {
          "field_key": "notes",
          "freetext_value": "Checkout redesign"
        }
      ],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000",
      "traffic_exposure": {
        "fraction": 1,
        "mode": "STATIC"
      },
      "variants": [
        {
          "feature_flag_variant_id": "550e8400-e29b-41d4-a716-446655440010",
          "is_active": true,
          "is_control": true,
          "key": "control",
          "weight": 50
        },
        {
          "feature_flag_variant_id": "550e8400-e29b-41d4-a716-446655440011",
          "is_active": true,
          "is_control": false,
          "key": "treatment",
          "weight": 50
        }
      ]
    },
    "type": "experiments"
  }
}

Response

Created

Example response

{
  "data": {
    "attributes": {
      "assignments_end_date": "2026-08-15T00:00:00Z",
      "assignments_start_date": "2026-08-01T00:00:00Z",
      "concluded_at": "2026-08-05T09:30:00Z",
      "conclusion": {
        "decision_reason": "The primary metric improved without material regressions",
        "outcome": "POSITIVE",
        "summary": "The treatment improved conversion"
      },
      "created_at": "2026-08-01T12:00:00Z",
      "datadog_flag_configuration": null,
      "decision_metrics": [
        {
          "is_primary": true,
          "metric_id": "b1a2c3d4-0000-0000-0000-000000000000"
        }
      ],
      "decision_variant_key": "treatment",
      "events_end_date": "2026-08-22T00:00:00Z",
      "events_start_date": "2026-08-01T00:00:00Z",
      "experiment_type": "STANDARD",
      "hypothesis": "A clearer checkout button increases purchase conversion",
      "name": "Checkout button test",
      "pipeline_table_suffix": "a1b2c3d4",
      "protocol_id": "e4d5f6a7-0000-0000-0000-000000000000",
      "related_links": [
        {
          "id": "d1d2d3d4-0000-0000-0000-000000000000",
          "title": "Experiment design",
          "url": "https://docs.example.com/checkout-experiment"
        }
      ],
      "results_last_updated": "2026-08-05T09:25:00Z",
      "split_by_properties": [],
      "status": "DECISION_MADE",
      "structured_metadata": [
        {
          "enum_values": [
            "beta"
          ],
          "field_display_name": "Launch stage",
          "field_key": "launch_stage",
          "field_type": "ENUM"
        },
        {
          "field_display_name": "Notes",
          "field_key": "notes",
          "field_type": "FREETEXT",
          "freetext_value": "Checkout redesign"
        }
      ],
      "subject_type_id": "c2b3d4e5-0000-0000-0000-000000000000",
      "summary": "The treatment improved conversion",
      "tags": [
        "growth"
      ],
      "teams": [
        "growth"
      ],
      "traffic_exposure": {
        "fraction": 1,
        "mode": "STATIC"
      },
      "updated_at": "2026-08-05T09:30:00Z",
      "variants": [
        {
          "is_active": true,
          "is_control": true,
          "key": "control",
          "name": "Control",
          "weight": 50
        },
        {
          "is_active": true,
          "is_control": false,
          "key": "treatment",
          "name": "Treatment",
          "weight": 50
        }
      ],
      "warehouse_exposure_configuration": {
        "entry_point": null,
        "experiment_key": "checkout_button_test",
        "exposure_sql_model_id": "f5e6a7b8-0000-0000-0000-000000000000"
      }
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "experiments"
  }
}

Changes

Changes to this operation have not been checked yet.