Update a single holdout
Updates a Holdout. Use the start, start-analysis, and stop endpoints to move it through its lifecycle.
curl -X PUT 'https://api.growthbook.io/api/v1/holdouts/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'import requests
url = "https://api.growthbook.io/api/v1/holdouts/{id}"
payload = {
"name": "<string>",
"description": "<string>",
"projects": ["<string>"],
"owner": "<string>",
"tags": ["<string>"],
"archived": True,
"skipAsDefaultHoldout": True,
"holdoutSize": -0.5,
"hashAttribute": "<string>",
"targetingCondition": "<string>",
"savedGroupTargeting": [{ "ids": ["<string>"] }],
"datasourceId": "<string>",
"assignmentQueryId": "<string>",
"goalMetrics": ["<string>"],
"secondaryMetrics": ["<string>"],
"environments": {},
"statusUpdateSchedule": {
"startAt": "2023-11-07T05:31:56Z",
"startAnalysisPeriodAt": "2023-11-07T05:31:56Z",
"stopAt": "2023-11-07T05:31:56Z"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
projects: ['<string>'],
owner: '<string>',
tags: ['<string>'],
archived: true,
skipAsDefaultHoldout: true,
holdoutSize: -0.5,
hashAttribute: '<string>',
targetingCondition: '<string>',
savedGroupTargeting: [{ids: ['<string>']}],
datasourceId: '<string>',
assignmentQueryId: '<string>',
goalMetrics: ['<string>'],
secondaryMetrics: ['<string>'],
environments: {},
statusUpdateSchedule: {
startAt: '2023-11-07T05:31:56Z',
startAnalysisPeriodAt: '2023-11-07T05:31:56Z',
stopAt: '2023-11-07T05:31:56Z'
}
})
};
fetch('https://api.growthbook.io/api/v1/holdouts/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.growthbook.io/api/v1/holdouts/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'projects' => [
'<string>'
],
'owner' => '<string>',
'tags' => [
'<string>'
],
'archived' => true,
'skipAsDefaultHoldout' => true,
'holdoutSize' => -0.5,
'hashAttribute' => '<string>',
'targetingCondition' => '<string>',
'savedGroupTargeting' => [
[
'ids' => [
'<string>'
]
]
],
'datasourceId' => '<string>',
'assignmentQueryId' => '<string>',
'goalMetrics' => [
'<string>'
],
'secondaryMetrics' => [
'<string>'
],
'environments' => [
],
'statusUpdateSchedule' => [
'startAt' => '2023-11-07T05:31:56Z',
'startAnalysisPeriodAt' => '2023-11-07T05:31:56Z',
'stopAt' => '2023-11-07T05:31:56Z'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.growthbook.io/api/v1/holdouts/{id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"projects\": [\n \"<string>\"\n ],\n \"owner\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"archived\": true,\n \"skipAsDefaultHoldout\": true,\n \"holdoutSize\": -0.5,\n \"hashAttribute\": \"<string>\",\n \"targetingCondition\": \"<string>\",\n \"savedGroupTargeting\": [\n {\n \"ids\": [\n \"<string>\"\n ]\n }\n ],\n \"datasourceId\": \"<string>\",\n \"assignmentQueryId\": \"<string>\",\n \"goalMetrics\": [\n \"<string>\"\n ],\n \"secondaryMetrics\": [\n \"<string>\"\n ],\n \"environments\": {},\n \"statusUpdateSchedule\": {\n \"startAt\": \"2023-11-07T05:31:56Z\",\n \"startAnalysisPeriodAt\": \"2023-11-07T05:31:56Z\",\n \"stopAt\": \"2023-11-07T05:31:56Z\"\n }\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.growthbook.io/api/v1/holdouts/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"projects\": [\n \"<string>\"\n ],\n \"owner\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"archived\": true,\n \"skipAsDefaultHoldout\": true,\n \"holdoutSize\": -0.5,\n \"hashAttribute\": \"<string>\",\n \"targetingCondition\": \"<string>\",\n \"savedGroupTargeting\": [\n {\n \"ids\": [\n \"<string>\"\n ]\n }\n ],\n \"datasourceId\": \"<string>\",\n \"assignmentQueryId\": \"<string>\",\n \"goalMetrics\": [\n \"<string>\"\n ],\n \"secondaryMetrics\": [\n \"<string>\"\n ],\n \"environments\": {},\n \"statusUpdateSchedule\": {\n \"startAt\": \"2023-11-07T05:31:56Z\",\n \"startAnalysisPeriodAt\": \"2023-11-07T05:31:56Z\",\n \"stopAt\": \"2023-11-07T05:31:56Z\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.growthbook.io/api/v1/holdouts/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"projects\": [\n \"<string>\"\n ],\n \"owner\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"archived\": true,\n \"skipAsDefaultHoldout\": true,\n \"holdoutSize\": -0.5,\n \"hashAttribute\": \"<string>\",\n \"targetingCondition\": \"<string>\",\n \"savedGroupTargeting\": [\n {\n \"ids\": [\n \"<string>\"\n ]\n }\n ],\n \"datasourceId\": \"<string>\",\n \"assignmentQueryId\": \"<string>\",\n \"goalMetrics\": [\n \"<string>\"\n ],\n \"secondaryMetrics\": [\n \"<string>\"\n ],\n \"environments\": {},\n \"statusUpdateSchedule\": {\n \"startAt\": \"2023-11-07T05:31:56Z\",\n \"startAnalysisPeriodAt\": \"2023-11-07T05:31:56Z\",\n \"stopAt\": \"2023-11-07T05:31:56Z\"\n }\n}"
response = http.request(request)
puts response.read_body{
"holdout": {
"id": "<string>",
"dateCreated": "2023-11-07T05:31:56Z",
"dateUpdated": "2023-11-07T05:31:56Z",
"name": "<string>",
"description": "<string>",
"projects": [
"<string>"
],
"owner": "<string>",
"tags": [
"<string>"
],
"archived": true,
"stage": "draft",
"trackingKey": "<string>",
"experimentId": "<string>",
"skipAsDefaultHoldout": true,
"holdoutSize": -0.5,
"hashAttribute": "<string>",
"targetingCondition": "<string>",
"datasourceId": "<string>",
"assignmentQuery": {
"id": "<string>",
"identifierType": "<string>"
},
"assignmentQueryId": "<string>",
"goalMetrics": [
"<string>"
],
"secondaryMetrics": [
"<string>"
],
"variations": [
{
"variationId": "<string>",
"key": "<string>",
"name": "<string>",
"description": "<string>"
}
],
"environments": {},
"linkedFeatures": [
{
"id": "<string>",
"dateAdded": "2023-11-07T05:31:56Z"
}
],
"linkedExperiments": [
{
"id": "<string>",
"dateAdded": "2023-11-07T05:31:56Z"
}
],
"ownerEmail": "<string>",
"savedGroupTargeting": [
{
"match": "all",
"ids": [
"<string>"
]
}
],
"statsEngine": "bayesian",
"dateStarted": "2023-11-07T05:31:56Z",
"analysisStartDate": "2023-11-07T05:31:56Z",
"dateStopped": "2023-11-07T05:31:56Z",
"statusUpdateSchedule": {
"startAt": "2023-11-07T05:31:56Z",
"startAnalysisPeriodAt": "2023-11-07T05:31:56Z",
"stopAt": "2023-11-07T05:31:56Z"
},
"nextScheduledStatusUpdate": {
"type": "start",
"date": "2023-11-07T05:31:56Z"
}
}
}Authorizations
If using Bearer auth, pass the Secret Key as the token:
curl https://api.growthbook.io/api/v1/features -H "Authorization: Bearer secret_abc123DEF456"
Path Parameters
Body
110000The userId or email address of the owner. If an email address is provided, it will be used to look up the userId of the matching organization member. If an ID is provided, it will be validated as existing in the organization.
When true, this Holdout is not selected automatically when creating Feature Flags or Experiments in Projects assigned to the Holdout.
Proportion of traffic placed in the holdout group (e.g. 0.05 for 5%). An equally sized comparison group is sampled from the remaining traffic for measurement, so 2× this value enters the holdout experiment in total. Must be greater than 0 and at most 0.5.
x <= 0.5Show child attributes
Show child attributes
The assignment query, grouping its ID with the identifier type analyzed on. Mutually exclusive with the deprecated assignmentQueryId.
Show child attributes
Show child attributes
Deprecated: use assignmentQuery. Rejected when selecting a different assignment query that declares several identifier types; set assignmentQuery.identifierType instead.
Statistics engine used to analyze this Holdout.
bayesian, frequentist Replaces the entire per-environment state. Environments not listed are disabled.
Show child attributes
Show child attributes
Automatic stage transitions for the Holdout. Dates must be consecutive: startAt before startAnalysisPeriodAt before stopAt. Send null to delete the schedule.
Show child attributes
Show child attributes
Response
Resource updated
Show child attributes
Show child attributes
Was this page helpful?
curl -X PUT 'https://api.growthbook.io/api/v1/holdouts/{id}' \
-H 'Authorization: Bearer YOUR_API_KEY'import requests
url = "https://api.growthbook.io/api/v1/holdouts/{id}"
payload = {
"name": "<string>",
"description": "<string>",
"projects": ["<string>"],
"owner": "<string>",
"tags": ["<string>"],
"archived": True,
"skipAsDefaultHoldout": True,
"holdoutSize": -0.5,
"hashAttribute": "<string>",
"targetingCondition": "<string>",
"savedGroupTargeting": [{ "ids": ["<string>"] }],
"datasourceId": "<string>",
"assignmentQueryId": "<string>",
"goalMetrics": ["<string>"],
"secondaryMetrics": ["<string>"],
"environments": {},
"statusUpdateSchedule": {
"startAt": "2023-11-07T05:31:56Z",
"startAnalysisPeriodAt": "2023-11-07T05:31:56Z",
"stopAt": "2023-11-07T05:31:56Z"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
description: '<string>',
projects: ['<string>'],
owner: '<string>',
tags: ['<string>'],
archived: true,
skipAsDefaultHoldout: true,
holdoutSize: -0.5,
hashAttribute: '<string>',
targetingCondition: '<string>',
savedGroupTargeting: [{ids: ['<string>']}],
datasourceId: '<string>',
assignmentQueryId: '<string>',
goalMetrics: ['<string>'],
secondaryMetrics: ['<string>'],
environments: {},
statusUpdateSchedule: {
startAt: '2023-11-07T05:31:56Z',
startAnalysisPeriodAt: '2023-11-07T05:31:56Z',
stopAt: '2023-11-07T05:31:56Z'
}
})
};
fetch('https://api.growthbook.io/api/v1/holdouts/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.growthbook.io/api/v1/holdouts/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'projects' => [
'<string>'
],
'owner' => '<string>',
'tags' => [
'<string>'
],
'archived' => true,
'skipAsDefaultHoldout' => true,
'holdoutSize' => -0.5,
'hashAttribute' => '<string>',
'targetingCondition' => '<string>',
'savedGroupTargeting' => [
[
'ids' => [
'<string>'
]
]
],
'datasourceId' => '<string>',
'assignmentQueryId' => '<string>',
'goalMetrics' => [
'<string>'
],
'secondaryMetrics' => [
'<string>'
],
'environments' => [
],
'statusUpdateSchedule' => [
'startAt' => '2023-11-07T05:31:56Z',
'startAnalysisPeriodAt' => '2023-11-07T05:31:56Z',
'stopAt' => '2023-11-07T05:31:56Z'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.growthbook.io/api/v1/holdouts/{id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"projects\": [\n \"<string>\"\n ],\n \"owner\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"archived\": true,\n \"skipAsDefaultHoldout\": true,\n \"holdoutSize\": -0.5,\n \"hashAttribute\": \"<string>\",\n \"targetingCondition\": \"<string>\",\n \"savedGroupTargeting\": [\n {\n \"ids\": [\n \"<string>\"\n ]\n }\n ],\n \"datasourceId\": \"<string>\",\n \"assignmentQueryId\": \"<string>\",\n \"goalMetrics\": [\n \"<string>\"\n ],\n \"secondaryMetrics\": [\n \"<string>\"\n ],\n \"environments\": {},\n \"statusUpdateSchedule\": {\n \"startAt\": \"2023-11-07T05:31:56Z\",\n \"startAnalysisPeriodAt\": \"2023-11-07T05:31:56Z\",\n \"stopAt\": \"2023-11-07T05:31:56Z\"\n }\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.growthbook.io/api/v1/holdouts/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"projects\": [\n \"<string>\"\n ],\n \"owner\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"archived\": true,\n \"skipAsDefaultHoldout\": true,\n \"holdoutSize\": -0.5,\n \"hashAttribute\": \"<string>\",\n \"targetingCondition\": \"<string>\",\n \"savedGroupTargeting\": [\n {\n \"ids\": [\n \"<string>\"\n ]\n }\n ],\n \"datasourceId\": \"<string>\",\n \"assignmentQueryId\": \"<string>\",\n \"goalMetrics\": [\n \"<string>\"\n ],\n \"secondaryMetrics\": [\n \"<string>\"\n ],\n \"environments\": {},\n \"statusUpdateSchedule\": {\n \"startAt\": \"2023-11-07T05:31:56Z\",\n \"startAnalysisPeriodAt\": \"2023-11-07T05:31:56Z\",\n \"stopAt\": \"2023-11-07T05:31:56Z\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.growthbook.io/api/v1/holdouts/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"projects\": [\n \"<string>\"\n ],\n \"owner\": \"<string>\",\n \"tags\": [\n \"<string>\"\n ],\n \"archived\": true,\n \"skipAsDefaultHoldout\": true,\n \"holdoutSize\": -0.5,\n \"hashAttribute\": \"<string>\",\n \"targetingCondition\": \"<string>\",\n \"savedGroupTargeting\": [\n {\n \"ids\": [\n \"<string>\"\n ]\n }\n ],\n \"datasourceId\": \"<string>\",\n \"assignmentQueryId\": \"<string>\",\n \"goalMetrics\": [\n \"<string>\"\n ],\n \"secondaryMetrics\": [\n \"<string>\"\n ],\n \"environments\": {},\n \"statusUpdateSchedule\": {\n \"startAt\": \"2023-11-07T05:31:56Z\",\n \"startAnalysisPeriodAt\": \"2023-11-07T05:31:56Z\",\n \"stopAt\": \"2023-11-07T05:31:56Z\"\n }\n}"
response = http.request(request)
puts response.read_body{
"holdout": {
"id": "<string>",
"dateCreated": "2023-11-07T05:31:56Z",
"dateUpdated": "2023-11-07T05:31:56Z",
"name": "<string>",
"description": "<string>",
"projects": [
"<string>"
],
"owner": "<string>",
"tags": [
"<string>"
],
"archived": true,
"stage": "draft",
"trackingKey": "<string>",
"experimentId": "<string>",
"skipAsDefaultHoldout": true,
"holdoutSize": -0.5,
"hashAttribute": "<string>",
"targetingCondition": "<string>",
"datasourceId": "<string>",
"assignmentQuery": {
"id": "<string>",
"identifierType": "<string>"
},
"assignmentQueryId": "<string>",
"goalMetrics": [
"<string>"
],
"secondaryMetrics": [
"<string>"
],
"variations": [
{
"variationId": "<string>",
"key": "<string>",
"name": "<string>",
"description": "<string>"
}
],
"environments": {},
"linkedFeatures": [
{
"id": "<string>",
"dateAdded": "2023-11-07T05:31:56Z"
}
],
"linkedExperiments": [
{
"id": "<string>",
"dateAdded": "2023-11-07T05:31:56Z"
}
],
"ownerEmail": "<string>",
"savedGroupTargeting": [
{
"match": "all",
"ids": [
"<string>"
]
}
],
"statsEngine": "bayesian",
"dateStarted": "2023-11-07T05:31:56Z",
"analysisStartDate": "2023-11-07T05:31:56Z",
"dateStopped": "2023-11-07T05:31:56Z",
"statusUpdateSchedule": {
"startAt": "2023-11-07T05:31:56Z",
"startAnalysisPeriodAt": "2023-11-07T05:31:56Z",
"stopAt": "2023-11-07T05:31:56Z"
},
"nextScheduledStatusUpdate": {
"type": "start",
"date": "2023-11-07T05:31:56Z"
}
}
}
