Start/Stage an experiment
Starts an experiment or stages it for a future start if a statusUpdateSchedule is set on the experiment. Both check the launch checklist that GET /experiments/{id}/start-checklist returns, as gates. An incomplete item refuses the start with checklist_incomplete unless skipChecklist is set; a linked Feature Flag blocker refuses it either way. The refusal lists each blocking gate in gates, with the flag or permission that gets past it and a route that resolves it. A linked Feature Flag draft that still needs approval, or a flag locked by a ramp, is bypassed automatically when the caller has Bypass draft approvals access for that flag or the organization enables the REST API approval bypass. A start reports what it got past in bypassedGates and the drafts it published in publishedFeatureDrafts; if a draft can’t publish, for example because it needs a rebase, the start fails with pending_draft_publish_failed before any is published. A staged start carries the caller’s Bypass draft approvals access to when it runs, for the drafts as they were when it was staged: if one has changed since, or the caller has lost that access, it needs approval like any other. The organization’s REST API approval bypass doesn’t carry to a staged start.
POST
/
v1
/
experiments
/
{id}
/
start
cURL
curl -X POST 'https://api.growthbook.io/api/v1/experiments/exp_abc123/start' \
-H 'Authorization: Bearer YOUR_API_KEY'import requests
url = "https://api.growthbook.io/api/v1/experiments/{id}/start"
payload = {
"skipChecklist": True,
"bypassApproval": True,
"ignoreWarnings": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({skipChecklist: true, bypassApproval: true, ignoreWarnings: true})
};
fetch('https://api.growthbook.io/api/v1/experiments/{id}/start', 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/experiments/{id}/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'skipChecklist' => true,
'bypassApproval' => true,
'ignoreWarnings' => true
]),
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/experiments/{id}/start"
payload := strings.NewReader("{\n \"skipChecklist\": true,\n \"bypassApproval\": true,\n \"ignoreWarnings\": true\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.growthbook.io/api/v1/experiments/{id}/start")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"skipChecklist\": true,\n \"bypassApproval\": true,\n \"ignoreWarnings\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.growthbook.io/api/v1/experiments/{id}/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"skipChecklist\": true,\n \"bypassApproval\": true,\n \"ignoreWarnings\": true\n}"
response = http.request(request)
puts response.read_body{
"experiment": {
"id": "<string>",
"trackingKey": "<string>",
"dateCreated": "2023-11-07T05:31:56Z",
"dateUpdated": "2023-11-07T05:31:56Z",
"name": "<string>",
"type": "standard",
"project": "<string>",
"hypothesis": "<string>",
"description": "<string>",
"tags": [
"<string>"
],
"owner": "<string>",
"archived": true,
"status": "<string>",
"autoRefresh": true,
"hashAttribute": "<string>",
"hashVersion": 1,
"variations": [
{
"variationId": "<string>",
"key": "<string>",
"name": "<string>",
"description": "<string>",
"screenshots": [
"<string>"
]
}
],
"phases": [
{
"name": "<string>",
"dateStarted": "<string>",
"dateEnded": "<string>",
"reasonForStopping": "<string>",
"seed": "<string>",
"coverage": 123,
"trafficSplit": [
{
"variationId": "<string>",
"weight": 123
}
],
"targetingCondition": "<string>",
"namespace": {
"namespaceId": "<string>",
"enabled": true,
"range": [
123
],
"ranges": [
[
123,
123
]
]
},
"prerequisites": [
{
"id": "<string>",
"condition": "<string>"
}
],
"savedGroupTargeting": [
{
"matchType": "all",
"savedGroups": [
"<string>"
]
}
]
}
],
"settings": {
"datasourceId": "<string>",
"assignmentQuery": {
"id": "<string>",
"identifierType": "<string>"
},
"assignmentQueryId": "<string>",
"experimentId": "<string>",
"segmentId": "<string>",
"queryFilter": "<string>",
"inProgressConversions": "include",
"attributionModel": "firstExposure",
"statsEngine": "bayesian",
"goals": [
{
"metricId": "<string>",
"overrides": {
"delayHours": 123,
"windowHours": 123,
"window": "conversion",
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123,
"winRiskThreshold": 123,
"loseRiskThreshold": 123
}
}
],
"secondaryMetrics": [
{
"metricId": "<string>",
"overrides": {
"delayHours": 123,
"windowHours": 123,
"window": "conversion",
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123,
"winRiskThreshold": 123,
"loseRiskThreshold": 123
}
}
],
"guardrails": [
{
"metricId": "<string>",
"overrides": {
"delayHours": 123,
"windowHours": 123,
"window": "conversion",
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123,
"winRiskThreshold": 123,
"loseRiskThreshold": 123
}
}
],
"isClusterExperiment": true,
"clusterSubUnitIdentifier": "<string>",
"lookbackOverride": {
"type": "date",
"value": 123,
"valueUnit": "minutes"
},
"regressionAdjustmentEnabled": true,
"sequentialTestingEnabled": true,
"sequentialTestingTuningParameter": 123,
"postStratificationEnabled": true,
"decisionFrameworkSettings": {
"decisionCriteriaId": "<string>",
"decisionFrameworkMetricOverrides": [
{
"id": "<string>",
"targetMDE": 123
}
]
},
"metricOverrides": [
{
"id": "<string>",
"windowType": "conversion",
"windowHours": 123,
"delayHours": 123,
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123
}
],
"activationMetric": {
"metricId": "<string>",
"overrides": {
"delayHours": 123,
"windowHours": 123,
"window": "conversion",
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123,
"winRiskThreshold": 123,
"loseRiskThreshold": 123
}
}
},
"ownerEmail": "<string>",
"fallbackAttribute": "<string>",
"disableStickyBucketing": true,
"bucketVersion": 123,
"minBucketVersion": 123,
"resultSummary": {
"status": "<string>",
"winner": "<string>",
"conclusions": "<string>",
"releasedVariationId": "<string>",
"excludeFromPayload": true
},
"shareLevel": "public",
"publicUrl": "<string>",
"banditScheduleValue": 123,
"banditScheduleUnit": "days",
"banditBurnInValue": 123,
"banditBurnInUnit": "days",
"banditConversionWindowValue": 123,
"banditConversionWindowUnit": "days",
"linkedFeatures": [
"<string>"
],
"attributeScopeAllProjects": true,
"hasVisualChangesets": true,
"hasURLRedirects": true,
"customFields": {},
"customMetricSlices": [
{
"slices": [
{
"column": "<string>",
"levels": [
"<string>"
]
}
]
}
],
"precomputedUnitDimensionIds": [
"<string>"
],
"defaultDashboardId": "<string>",
"templateId": "<string>",
"statusUpdateSchedule": {
"startAt": "2023-11-07T05:31:56Z",
"stopAt": "2023-11-07T05:31:56Z",
"stopAfter": {
"value": 123,
"unit": "hours"
},
"scheduledStopPlan": {
"mode": "notify",
"tiebreakerMetricId": "<string>",
"fallback": "notify",
"fallbackVariationId": "<string>"
}
},
"nextScheduledStatusUpdate": {
"type": "start",
"date": "2023-11-07T05:31:56Z"
},
"enhancedStatus": {
"status": "Running",
"detailedStatus": "<string>"
}
},
"message": "<string>",
"bypassedGates": [
{
"key": "<string>",
"type": "<string>",
"outcome": "bypassed",
"via": "ignoreWarnings"
}
],
"publishedFeatureDrafts": [
{
"featureId": "<string>",
"revisionVersion": 123
}
]
}{
"confirmation": {
"id": "<string>",
"status": "pending",
"actions": [
{
"action": "feature.create",
"environments": [
"<string>"
]
}
],
"summary": "<string>",
"url": "<string>",
"expiresAt": "<string>",
"response": {
"status": 123,
"body": "<unknown>"
},
"note": "<string>"
},
"message": "<string>"
}{
"message": "<string>",
"code": "checklist_incomplete",
"details": {
"remainingChecklistItems": [
{
"key": "<string>",
"required": true,
"status": "complete",
"manual": true,
"reason": "<string>",
"hardBlock": true
}
]
}
}Authorizations
bearerAuthbasicAuth
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
The id of the requested resource
Body
application/json
If true, skips validating the experiment satisfies all pre-launch checklist items. Only set this when a person has explicitly asked you to. If a check blocks you, stop and ask a person instead of working around it.
Deprecated and ignored. Approval is bypassed automatically when the caller has Bypass draft approvals access for this resource or when the organization enables the REST API approval bypass. Otherwise, the revision must be approved before it can be published.
Set to true to acknowledge the warnings listed in a blocked response and continue. This covers experiment guards, locked dependents, and references affected by an archive. When the organization treats schema failures as warnings, it also covers schema and invariant warnings. It never bypasses a rejected Custom Hook. On revision publish endpoints, it can also force-publish an out-of-date draft when the caller has Bypass draft approvals access. Only set this when a person has explicitly asked you to. If a check blocks you, stop and ask a person instead of working around it.
Response
Resource created
Show child attributes
Show child attributes
Present only when the request staged a future scheduled start instead of starting the experiment immediately.
Gates this start skipped or bypassed. Present only when there were some.
Show child attributes
Show child attributes
The linked Feature Flag drafts the start published. Present only when it published some.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
cURL
curl -X POST 'https://api.growthbook.io/api/v1/experiments/exp_abc123/start' \
-H 'Authorization: Bearer YOUR_API_KEY'import requests
url = "https://api.growthbook.io/api/v1/experiments/{id}/start"
payload = {
"skipChecklist": True,
"bypassApproval": True,
"ignoreWarnings": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({skipChecklist: true, bypassApproval: true, ignoreWarnings: true})
};
fetch('https://api.growthbook.io/api/v1/experiments/{id}/start', 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/experiments/{id}/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'skipChecklist' => true,
'bypassApproval' => true,
'ignoreWarnings' => true
]),
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/experiments/{id}/start"
payload := strings.NewReader("{\n \"skipChecklist\": true,\n \"bypassApproval\": true,\n \"ignoreWarnings\": true\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.growthbook.io/api/v1/experiments/{id}/start")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"skipChecklist\": true,\n \"bypassApproval\": true,\n \"ignoreWarnings\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.growthbook.io/api/v1/experiments/{id}/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"skipChecklist\": true,\n \"bypassApproval\": true,\n \"ignoreWarnings\": true\n}"
response = http.request(request)
puts response.read_body{
"experiment": {
"id": "<string>",
"trackingKey": "<string>",
"dateCreated": "2023-11-07T05:31:56Z",
"dateUpdated": "2023-11-07T05:31:56Z",
"name": "<string>",
"type": "standard",
"project": "<string>",
"hypothesis": "<string>",
"description": "<string>",
"tags": [
"<string>"
],
"owner": "<string>",
"archived": true,
"status": "<string>",
"autoRefresh": true,
"hashAttribute": "<string>",
"hashVersion": 1,
"variations": [
{
"variationId": "<string>",
"key": "<string>",
"name": "<string>",
"description": "<string>",
"screenshots": [
"<string>"
]
}
],
"phases": [
{
"name": "<string>",
"dateStarted": "<string>",
"dateEnded": "<string>",
"reasonForStopping": "<string>",
"seed": "<string>",
"coverage": 123,
"trafficSplit": [
{
"variationId": "<string>",
"weight": 123
}
],
"targetingCondition": "<string>",
"namespace": {
"namespaceId": "<string>",
"enabled": true,
"range": [
123
],
"ranges": [
[
123,
123
]
]
},
"prerequisites": [
{
"id": "<string>",
"condition": "<string>"
}
],
"savedGroupTargeting": [
{
"matchType": "all",
"savedGroups": [
"<string>"
]
}
]
}
],
"settings": {
"datasourceId": "<string>",
"assignmentQuery": {
"id": "<string>",
"identifierType": "<string>"
},
"assignmentQueryId": "<string>",
"experimentId": "<string>",
"segmentId": "<string>",
"queryFilter": "<string>",
"inProgressConversions": "include",
"attributionModel": "firstExposure",
"statsEngine": "bayesian",
"goals": [
{
"metricId": "<string>",
"overrides": {
"delayHours": 123,
"windowHours": 123,
"window": "conversion",
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123,
"winRiskThreshold": 123,
"loseRiskThreshold": 123
}
}
],
"secondaryMetrics": [
{
"metricId": "<string>",
"overrides": {
"delayHours": 123,
"windowHours": 123,
"window": "conversion",
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123,
"winRiskThreshold": 123,
"loseRiskThreshold": 123
}
}
],
"guardrails": [
{
"metricId": "<string>",
"overrides": {
"delayHours": 123,
"windowHours": 123,
"window": "conversion",
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123,
"winRiskThreshold": 123,
"loseRiskThreshold": 123
}
}
],
"isClusterExperiment": true,
"clusterSubUnitIdentifier": "<string>",
"lookbackOverride": {
"type": "date",
"value": 123,
"valueUnit": "minutes"
},
"regressionAdjustmentEnabled": true,
"sequentialTestingEnabled": true,
"sequentialTestingTuningParameter": 123,
"postStratificationEnabled": true,
"decisionFrameworkSettings": {
"decisionCriteriaId": "<string>",
"decisionFrameworkMetricOverrides": [
{
"id": "<string>",
"targetMDE": 123
}
]
},
"metricOverrides": [
{
"id": "<string>",
"windowType": "conversion",
"windowHours": 123,
"delayHours": 123,
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123
}
],
"activationMetric": {
"metricId": "<string>",
"overrides": {
"delayHours": 123,
"windowHours": 123,
"window": "conversion",
"properPriorOverride": true,
"properPriorEnabled": true,
"properPriorMean": 123,
"properPriorStdDev": 123,
"regressionAdjustmentOverride": true,
"regressionAdjustmentEnabled": true,
"regressionAdjustmentDays": 123,
"winRiskThreshold": 123,
"loseRiskThreshold": 123
}
}
},
"ownerEmail": "<string>",
"fallbackAttribute": "<string>",
"disableStickyBucketing": true,
"bucketVersion": 123,
"minBucketVersion": 123,
"resultSummary": {
"status": "<string>",
"winner": "<string>",
"conclusions": "<string>",
"releasedVariationId": "<string>",
"excludeFromPayload": true
},
"shareLevel": "public",
"publicUrl": "<string>",
"banditScheduleValue": 123,
"banditScheduleUnit": "days",
"banditBurnInValue": 123,
"banditBurnInUnit": "days",
"banditConversionWindowValue": 123,
"banditConversionWindowUnit": "days",
"linkedFeatures": [
"<string>"
],
"attributeScopeAllProjects": true,
"hasVisualChangesets": true,
"hasURLRedirects": true,
"customFields": {},
"customMetricSlices": [
{
"slices": [
{
"column": "<string>",
"levels": [
"<string>"
]
}
]
}
],
"precomputedUnitDimensionIds": [
"<string>"
],
"defaultDashboardId": "<string>",
"templateId": "<string>",
"statusUpdateSchedule": {
"startAt": "2023-11-07T05:31:56Z",
"stopAt": "2023-11-07T05:31:56Z",
"stopAfter": {
"value": 123,
"unit": "hours"
},
"scheduledStopPlan": {
"mode": "notify",
"tiebreakerMetricId": "<string>",
"fallback": "notify",
"fallbackVariationId": "<string>"
}
},
"nextScheduledStatusUpdate": {
"type": "start",
"date": "2023-11-07T05:31:56Z"
},
"enhancedStatus": {
"status": "Running",
"detailedStatus": "<string>"
}
},
"message": "<string>",
"bypassedGates": [
{
"key": "<string>",
"type": "<string>",
"outcome": "bypassed",
"via": "ignoreWarnings"
}
],
"publishedFeatureDrafts": [
{
"featureId": "<string>",
"revisionVersion": 123
}
]
}{
"confirmation": {
"id": "<string>",
"status": "pending",
"actions": [
{
"action": "feature.create",
"environments": [
"<string>"
]
}
],
"summary": "<string>",
"url": "<string>",
"expiresAt": "<string>",
"response": {
"status": 123,
"body": "<unknown>"
},
"note": "<string>"
},
"message": "<string>"
}{
"message": "<string>",
"code": "checklist_incomplete",
"details": {
"remainingChecklistItems": [
{
"key": "<string>",
"required": true,
"status": "complete",
"manual": true,
"reason": "<string>",
"hardBlock": true
}
]
}
}