# Create holdout

POST https://app.launchdarkly.com/api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts
Content-Type: application/json

Create a new holdout in the specified project.

Reference: https://launchdarkly.com/docs/api/holdouts-beta/post-holdout

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: LaunchDarkly REST API
  version: 1.0.0
paths:
  /api/v2/projects/{projectKey}/environments/{environmentKey}/holdouts:
    post:
      operationId: post-holdout
      summary: Create holdout
      description: Create a new holdout in the specified project.
      tags:
        - subpackage_holdoutsBeta
      parameters:
        - name: projectKey
          in: path
          description: The project key
          required: true
          schema:
            type: string
            format: string
        - name: environmentKey
          in: path
          description: The environment key
          required: true
          schema:
            type: string
            format: string
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Holdout response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HoldoutRep'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestErrorRep'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HoldoutPostRequest'
servers:
  - url: https://app.launchdarkly.com
  - url: https://app.launchdarkly.us
components:
  schemas:
    MetricInput:
      type: object
      properties:
        key:
          type: string
          description: The metric key
        isGroup:
          type: boolean
          description: >-
            Whether this is a metric group (true) or a metric (false). Defaults
            to false
        primary:
          type: boolean
          description: >-
            Deprecated, use <code>primarySingleMetricKey</code> and
            <code>primaryFunnelKey</code>. Whether this is a primary metric
            (true) or a secondary metric (false)
      required:
        - key
      title: MetricInput
    HoldoutPostRequest:
      type: object
      properties:
        name:
          type: string
          description: A human-friendly name for the holdout
        key:
          type: string
          description: A key that identifies the holdout
        description:
          type: string
          description: Description of the holdout
        randomizationunit:
          type: string
          description: The chosen randomization unit for the holdout base experiment
        attributes:
          type: array
          items:
            type: string
          description: The attributes that the holdout iteration's results can be sliced by
        holdoutamount:
          type: string
          description: Audience allocation for the holdout
        primarymetrickey:
          type: string
          description: The key of the primary metric for this holdout
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/MetricInput'
          description: Details on the metrics for this experiment
        prerequisiteflagkey:
          type: string
          description: The key of the flag that the holdout is dependent on
        maintainerId:
          type: string
          description: Maintainer id
      title: HoldoutPostRequest
    HoldoutRepStatus:
      type: string
      enum:
        - created
        - enabled
        - running
        - ended
      title: HoldoutRepStatus
    UnixMillis:
      type: integer
      format: int64
      title: UnixMillis
    ExperimentMethodology:
      type: string
      enum:
        - bayesian
        - frequentist
        - export_only
      description: The results analysis approach.
      title: ExperimentMethodology
    ExperimentDataSource:
      type: string
      enum:
        - launchdarkly
        - snowflake
      description: >-
        The source of metric data in order to analyze results. Defaults to
        "launchdarkly" when not provided.
      title: ExperimentDataSource
    Link:
      type: object
      properties:
        href:
          type: string
          description: The URL of the link
        type:
          type: string
          description: The type of the link
      title: Link
    IterationRepStatus:
      type: string
      enum:
        - not_started
        - running
        - stopped
      description: >-
        The status of the iteration: <code>not_started</code>,
        <code>running</code>, <code>stopped</code>
      title: IterationRepStatus
    FlagRep:
      type: object
      properties:
        targetingRule:
          type: string
          description: The targeting rule
        targetingRuleDescription:
          type: string
          description: The rule description
        targetingRuleClauses:
          type: array
          items:
            description: Any type
          description: >-
            An array of clauses used for individual targeting based on
            attributes
        flagConfigVersion:
          type: integer
          description: The flag version
        notInExperimentVariationId:
          type: string
          description: >-
            The ID of the variation to route traffic not part of the experiment
            analysis to
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
      required:
        - _links
      title: FlagRep
    DependentMetricOrMetricGroupRepKind:
      type: string
      enum:
        - pageview
        - click
        - custom
        - funnel
        - standard
      description: >-
        If this is a metric, then it represents the kind of event the metric
        tracks. If this is a metric group, then it represents the group type
      title: DependentMetricOrMetricGroupRepKind
    MetricInGroupRepKind:
      type: string
      enum:
        - pageview
        - click
        - custom
      description: The kind of event the metric tracks
      title: MetricInGroupRepKind
    MetricInGroupRepUnitAggregationType:
      type: string
      enum:
        - sum
        - average
      description: The type of unit aggregation to use for the metric
      title: MetricInGroupRepUnitAggregationType
    MetricInGroupRep:
      type: object
      properties:
        key:
          type: string
          description: The metric key
        _versionId:
          type: string
          description: The version ID of the metric
        name:
          type: string
          description: The metric name
        kind:
          $ref: '#/components/schemas/MetricInGroupRepKind'
          description: The kind of event the metric tracks
        isNumeric:
          type: boolean
          description: >-
            For custom metrics, whether to track numeric changes in value
            against a baseline (<code>true</code>) or to track a conversion when
            an end user takes an action (<code>false</code>).
        unitAggregationType:
          $ref: '#/components/schemas/MetricInGroupRepUnitAggregationType'
          description: The type of unit aggregation to use for the metric
        eventKey:
          type: string
          description: >-
            The event key sent with the metric. Only relevant for custom
            metrics.
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
        nameInGroup:
          type: string
          description: >-
            Name of the metric when used within the associated metric group. Can
            be different from the original name of the metric. Required if and
            only if the metric group is a <code>funnel</code>.
        randomizationUnits:
          type: array
          items:
            type: string
          description: The randomization units for the metric
      required:
        - key
        - name
        - kind
        - _links
      title: MetricInGroupRep
    DependentMetricOrMetricGroupRep:
      type: object
      properties:
        key:
          type: string
          description: A unique key to reference the metric or metric group
        _versionId:
          type: string
          description: The version ID of the metric or metric group
        name:
          type: string
          description: A human-friendly name for the metric or metric group
        kind:
          $ref: '#/components/schemas/DependentMetricOrMetricGroupRepKind'
          description: >-
            If this is a metric, then it represents the kind of event the metric
            tracks. If this is a metric group, then it represents the group type
        isNumeric:
          type: boolean
          description: >-
            For custom metrics, whether to track numeric changes in value
            against a baseline (<code>true</code>) or to track a conversion when
            an end user takes an action (<code>false</code>).
        eventKey:
          type: string
          description: >-
            The event key sent with the metric. Only relevant for custom
            metrics.
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
        isGroup:
          type: boolean
          description: Whether this is a metric group or a metric
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/MetricInGroupRep'
          description: An ordered list of the metrics in this metric group
      required:
        - key
        - _versionId
        - name
        - kind
        - _links
        - isGroup
      title: DependentMetricOrMetricGroupRep
    MetricV2RepKind:
      type: string
      enum:
        - pageview
        - click
        - custom
      description: The kind of event the metric tracks
      title: MetricV2RepKind
    MetricV2RepUnitAggregationType:
      type: string
      enum:
        - sum
        - average
      description: The type of unit aggregation to use for the metric
      title: MetricV2RepUnitAggregationType
    MetricV2Rep:
      type: object
      properties:
        key:
          type: string
          description: The metric key
        _versionId:
          type: string
          description: The version ID of the metric
        name:
          type: string
          description: The metric name
        kind:
          $ref: '#/components/schemas/MetricV2RepKind'
          description: The kind of event the metric tracks
        isNumeric:
          type: boolean
          description: >-
            For custom metrics, whether to track numeric changes in value
            against a baseline (<code>true</code>) or to track a conversion when
            an end user takes an action (<code>false</code>).
        unitAggregationType:
          $ref: '#/components/schemas/MetricV2RepUnitAggregationType'
          description: The type of unit aggregation to use for the metric
        eventKey:
          type: string
          description: >-
            The event key sent with the metric. Only relevant for custom
            metrics.
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
      required:
        - key
        - name
        - kind
        - _links
      title: MetricV2Rep
    DependentMetricGroupRepWithMetricsKind:
      type: string
      enum:
        - funnel
        - standard
      description: The type of the metric group
      title: DependentMetricGroupRepWithMetricsKind
    DependentMetricGroupRepWithMetrics:
      type: object
      properties:
        key:
          type: string
          description: A unique key to reference the metric group
        name:
          type: string
          description: A human-friendly name for the metric group
        kind:
          $ref: '#/components/schemas/DependentMetricGroupRepWithMetricsKind'
          description: The type of the metric group
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/MetricInGroupRep'
          description: The metrics in the metric group
      required:
        - key
        - name
        - kind
        - _links
      title: DependentMetricGroupRepWithMetrics
    ParameterRep:
      type: object
      properties:
        variationId:
          type: string
        flagKey:
          type: string
      title: ParameterRep
    TreatmentRep:
      type: object
      properties:
        _id:
          type: string
          description: The treatment ID. This is the variation ID from the flag.
        name:
          type: string
          description: The treatment name. This is the variation name from the flag.
        allocationPercent:
          type: string
          description: >-
            The percentage of traffic allocated to this treatment during the
            iteration
        baseline:
          type: boolean
          description: >-
            Whether this treatment is the baseline to compare other treatments
            against
        parameters:
          type: array
          items:
            $ref: '#/components/schemas/ParameterRep'
          description: Details on the flag and variation used for this treatment
      required:
        - name
        - allocationPercent
      title: TreatmentRep
    LayerSnapshotRep:
      type: object
      properties:
        key:
          type: string
          description: Key of the layer the experiment was part of
        name:
          type: string
          description: Layer name at the time this experiment iteration was stopped
        reservationPercent:
          type: integer
          description: >-
            Percent of layer traffic that was reserved in the layer for this
            experiment iteration
        otherReservationPercent:
          type: integer
          description: >-
            Percent of layer traffic that was reserved for other experiments in
            the same environment, when this experiment iteration was stopped
      required:
        - key
        - name
        - reservationPercent
        - otherReservationPercent
      title: LayerSnapshotRep
    CovariateInfoRep:
      type: object
      properties:
        id:
          type: string
          description: The ID of the covariate matrix
        fileName:
          type: string
          description: The file name of the uploaded covariate matrix
        createdAt:
          $ref: '#/components/schemas/UnixMillis'
          description: Timestamp of when the covariate was uploaded
      required:
        - id
        - fileName
        - createdAt
      title: CovariateInfoRep
    IterationRep:
      type: object
      properties:
        _id:
          type: string
          description: The iteration ID
        hypothesis:
          type: string
          description: The expected outcome of this experiment
        status:
          $ref: '#/components/schemas/IterationRepStatus'
          description: >-
            The status of the iteration: <code>not_started</code>,
            <code>running</code>, <code>stopped</code>
        createdAt:
          $ref: '#/components/schemas/UnixMillis'
          description: Timestamp of when the iteration was created
        startedAt:
          $ref: '#/components/schemas/UnixMillis'
          description: Timestamp of when the iteration started
        endedAt:
          $ref: '#/components/schemas/UnixMillis'
          description: Timestamp of when the iteration ended
        winningTreatmentId:
          type: string
          description: The ID of the treatment chosen when the experiment stopped
        winningReason:
          type: string
          description: The reason you stopped the experiment
        canReshuffleTraffic:
          type: boolean
          description: >-
            Whether the experiment may reassign traffic to different variations
            when the experiment audience changes (true) or must keep all traffic
            assigned to its initial variation (false).
        flags:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FlagRep'
          description: Details on the flag used in this experiment
        reallocationFrequencyMillis:
          type: integer
          description: >-
            The cadence (in milliseconds) to update the allocation. Only present
            for multi-armed bandits.
        version:
          type: integer
          description: The current version that the iteration is on
        primaryMetric:
          $ref: '#/components/schemas/DependentMetricOrMetricGroupRep'
          description: >-
            Deprecated, use <code>primarySingleMetric</code> and
            <code>primaryFunnel</code> instead. Details on the primary metric
            for this experiment.
        primarySingleMetric:
          $ref: '#/components/schemas/MetricV2Rep'
          description: Details on the primary metric for this experiment
        primaryFunnel:
          $ref: '#/components/schemas/DependentMetricGroupRepWithMetrics'
          description: Details on the primary funnel group for this experiment
        randomizationUnit:
          type: string
          description: The unit of randomization for this iteration
        attributes:
          type: array
          items:
            type: string
          description: The available attribute filters for this iteration
        treatments:
          type: array
          items:
            $ref: '#/components/schemas/TreatmentRep'
          description: Details on the variations you are testing in the experiment
        secondaryMetrics:
          type: array
          items:
            $ref: '#/components/schemas/MetricV2Rep'
          description: >-
            Deprecated, use <code>metrics</code> instead. Details on the
            secondary metrics for this experiment.
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/DependentMetricOrMetricGroupRep'
          description: Details on the metrics for this experiment
        layerSnapshot:
          $ref: '#/components/schemas/LayerSnapshotRep'
          description: >-
            Snapshot of the layer state on iteration stop, if part of a layer.
            Otherwise omitted.
        covariateInfo:
          $ref: '#/components/schemas/CovariateInfoRep'
          description: Details of the covariate file for stratified sampling
      required:
        - hypothesis
        - status
        - createdAt
      title: IterationRep
    AnalysisConfigRepMultipleComparisonCorrectionMethod:
      type: string
      enum:
        - bonferroni
        - benjamini-hochberg
      description: The method for multiple comparison correction.
      title: AnalysisConfigRepMultipleComparisonCorrectionMethod
    AnalysisConfigRepMultipleComparisonCorrectionScope:
      type: string
      enum:
        - variations
        - variations-and-metrics
        - metrics
      description: The scope for multiple comparison correction.
      title: AnalysisConfigRepMultipleComparisonCorrectionScope
    AnalysisConfigRep:
      type: object
      properties:
        bayesianThreshold:
          type: string
          description: >-
            The threshold for the Probability to Beat Baseline (PBBL) and
            Probability to Be Best (PBB) comparisons for the Bayesian results
            analysis approach.  Value should be between 0-100 inclusive.
        significanceThreshold:
          type: string
          description: >-
            The significance threshold for the frequentist results analysis
            approach. Value should be between 0.0-1.0 inclusive.
        testDirection:
          type: string
          description: >-
            The test sided direction for the frequentist results analysis
            approach.
        multipleComparisonCorrectionMethod:
          $ref: >-
            #/components/schemas/AnalysisConfigRepMultipleComparisonCorrectionMethod
          description: The method for multiple comparison correction.
        multipleComparisonCorrectionScope:
          $ref: >-
            #/components/schemas/AnalysisConfigRepMultipleComparisonCorrectionScope
          description: The scope for multiple comparison correction.
        sequentialTestingEnabled:
          type: boolean
          description: Whether sequential testing is enabled for Frequentist analysis
      title: AnalysisConfigRep
    Experiment:
      type: object
      properties:
        _id:
          type: string
          description: The experiment ID
        key:
          type: string
          description: The experiment key
        name:
          type: string
          description: The experiment name
        description:
          type: string
          description: The experiment description
        _maintainerId:
          type: string
          description: The ID of the member who maintains this experiment.
        _creationDate:
          $ref: '#/components/schemas/UnixMillis'
          description: Timestamp of when the experiment was created
        environmentKey:
          type: string
        methodology:
          $ref: '#/components/schemas/ExperimentMethodology'
          description: The results analysis approach.
        dataSource:
          $ref: '#/components/schemas/ExperimentDataSource'
          description: >-
            The source of metric data in order to analyze results. Defaults to
            "launchdarkly" when not provided.
        archivedDate:
          $ref: '#/components/schemas/UnixMillis'
          description: Timestamp of when the experiment was archived
        tags:
          type: array
          items:
            type: string
          description: Tags for the experiment
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
        holdoutId:
          type: string
          description: The holdout ID
        currentIteration:
          $ref: '#/components/schemas/IterationRep'
          description: Details on the current iteration
        type:
          type: string
          description: The experiment type
        draftIteration:
          $ref: '#/components/schemas/IterationRep'
          description: >-
            Details on the current iteration. This iteration may be already
            started, or may still be a draft.
        previousIterations:
          type: array
          items:
            $ref: '#/components/schemas/IterationRep'
          description: Details on the previous iterations for this experiment.
        analysisConfig:
          $ref: '#/components/schemas/AnalysisConfigRep'
          description: Details of the Analysis Configuration for this experiment.
      required:
        - key
        - name
        - _maintainerId
        - _creationDate
        - environmentKey
        - _links
      title: Experiment
    RelatedExperimentRep:
      type: object
      properties:
        key:
          type: string
        name:
          type: string
        environment:
          type: string
      title: RelatedExperimentRep
    HoldoutRep:
      type: object
      properties:
        _id:
          type: string
        status:
          $ref: '#/components/schemas/HoldoutRepStatus'
        description:
          type: string
        holdoutAmount:
          type: string
          description: The percentage of traffic allocated to this holdout.
        createdAt:
          $ref: '#/components/schemas/UnixMillis'
        updatedAt:
          $ref: '#/components/schemas/UnixMillis'
        baseExperiment:
          $ref: '#/components/schemas/Experiment'
        experiments:
          type: array
          items:
            $ref: '#/components/schemas/RelatedExperimentRep'
      required:
        - _id
        - status
        - holdoutAmount
        - createdAt
        - updatedAt
        - baseExperiment
      title: HoldoutRep
    InvalidRequestErrorRep:
      type: object
      properties:
        code:
          type: string
          description: Specific error code encountered
        message:
          type: string
          description: Description of the error
      required:
        - code
        - message
      title: InvalidRequestErrorRep
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization

```

## SDK Code Examples

```python
import requests

url = "https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts"

payload = {}
headers = {
    "Authorization": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts';
const options = {
  method: 'POST',
  headers: {Authorization: '<apiKey>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts")
  .header("Authorization", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts', [
  'body' => '{}',
  'headers' => [
    'Authorization' => '<apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://app.launchdarkly.com/api/v2/projects/projectKey/environments/environmentKey/holdouts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```