Create Experiment

posthttps://statsigapi.net/console/v1/experiments

Authorizations

STATSIG-API-KEYstringrequired

apiKey (header)

Body

application/json
namestringrequired

The experiment display name

descriptionstring

A description of the new experiment

idTypestring

The idType the experiment will be performed on

secondaryIDTypestring

The secondary ID type for the experiment used in WHN for ID resolution

identifierMappingModestring

The identifier mapping mode for the experiment used in WHN for ID resolution

identityResolutionSourcestring

The identity resolution entity property source for the experiment used in WHN for ID resolution

hypothesisstring

A statement that will be tested by this experiment

linksobject[]

Links to relevant documentation or resources

Show child attributes
url[]stringrequired

The URL of the link

title[]string

The title of the link

externalEventsobject[]
Show child attributes
name[]stringrequired
timestamp[]numberrequired
groupsobject[]

The test groups for your experiment

Show child attributes
name[]stringrequired
id[]string
size[]numberrequired
parameterValues[]objectrequired
disabled[]boolean
description[]string
foreignGroupID[]string
highlighted[]boolean

Marks this experiment group as highlighted in analysis views. Highlighted groups are prioritized (shown first) and can be used to filter.

controlGroupIDstring

Optional control group ID

allocationnumber

Percent of layer allocated to this experiment

userBucketsnumber[]
primaryMetricTagsstring[]

Primary metric tags for the experiment

secondaryMetricTagsstring[]

Secondary metric tags for the experiment

primaryMetricsobject[]

Main metrics needed to evaluate your hypothesis

Show child attributes
name[]stringrequired

The metric name.

type[]stringrequired

The metric type.

direction[]string

The expected direction for one-sided testing (a feature to only measure metric movements in a single direction)

hypothesizedValue[]number

The comparison value for the one-sample testing (a feature to use a fixed baseline as the control value)

secondaryMetricsobject[]

Additional metrics to monitor that might impact the analysis or final decision of the experiment

Show child attributes
name[]stringrequired

The metric name.

type[]stringrequired

The metric type.

direction[]string

The expected direction for one-sided testing (a feature to only measure metric movements in a single direction)

hypothesizedValue[]number

The comparison value for the one-sample testing (a feature to use a fixed baseline as the control value)

otherMetricsobject[]

Additional metrics you want to investigate or learn from. The usual corrections applied to Primary and Secondary metrics are not applied to these.

Show child attributes
name[]stringrequired

The metric name.

type[]stringrequired

The metric type.

direction[]string

The expected direction for one-sided testing (a feature to only measure metric movements in a single direction)

hypothesizedValue[]number

The comparison value for the one-sample testing (a feature to use a fixed baseline as the control value)

targetAppsoneOf

Target apps assigned to this experiment

tagsstring[]

Tags associated with the experiment

durationinteger

How long the experiment is expected to last in days

targetExposuresinteger

Target exposures for the experiment

targetingGateIDstring

Restrict your experiment to users passing the selected feature gate

sequentialTestingboolean

Apply sequential testing?

bonferroniCorrectionboolean

Is Bonferroni correction applied per variant?

bonferroniCorrectionPerMetricboolean

Is Bonferroni correction applied per metric?

benjaminiHochbergPerVariantboolean

Is Benjamini-Hochberg procedure applied per variant?

benjaminiHochbergPerMetricboolean

Is Benjamini-Hochberg procedure applied per metric?

benjaminiPrimaryMetricsOnlyboolean

Is Benjamini-Hochberg procedure applied for primary metrics only?

defaultConfidenceIntervalstring

Default error margin used for results

defaultRollupWindowinteger

Default rollup window in days for experiment results. Use -1 for cumulative. Only -1, 1, and 7 allowed for cloud experiments.

defaultChanceToBeatThresholdnumber

Default chance-to-beat threshold used for Bayesian results.

bayesianPriorsobject[]

Bayesian prior settings by metric.

Show child attributes
metric[]objectrequired
Show child attributes
namestringrequired
typestringrequired
priorMean[]numberrequired
priorStdDev[]numberrequired
manualQualityScoresobject[]

Up to 10 manually set quality scores for an experiment. The scores and weights will be added to the existing weights and scores, and then weights will be renormalized to 100. This can be set via the Statsig Console API. If targeting a default check, the weight of the check will be updated, but not the status or description. A default score can be removed by setting the weight to 0. The default score identifiers are one of: HYPOTHESIS_LENGTH, BALANCED_EXPOSURE, PRIMARY_METRICS_LENGTH, COMPARISON_CORRECTION, GUARDRAIL_METRIC_TAGS, SUFFICIENT_SAMPLE, POWER_ANALYSIS, SEQUENTIAL_TESTING

Show child attributes
criteriaName[]oneOfrequired
status[]stringrequired
criteriaDescription[]stringrequired
score[]numberrequired
weight[]numberrequired
statusstring

The current status of the experiment

launchedGroupIDstring

ID of the launched group, null otherwise

assignmentSourceNamestring

Source name of the assignment

assignmentSourceExperimentNamestring

Name of the source experiment for assignment

creatorIDstring

The Statsig ID of the creator of this experiment

creatorEmailstring

The email of the creator of this experiment

isAnalysisOnlyboolean

For Warehouse Native

teamstring

The team name associated with the experiment, Enterprise only.

teamIDstring

The team ID associated with the experiment, Enterprise only.

allocationDurationinteger

Warehouse Native Only - Allocation duration in days

cohortedAnalysisDurationinteger

Warehouse Native Only - Cohorted analysis duration in days

cohortedMetricsMatureAfterEndboolean

Warehouse Native Only - Allow cohort metrics to mature after experiment end

cohortWaitUntilEndToIncludeboolean

Warehouse Native Only - Whether to filter to units whose experiment cohort analysis duration is complete, if cohortedAnalysisDuration exists

fixedAnalysisDurationinteger

Fixed analysis duration in days

scheduledReloadHourinteger

Warehouse Native only - UTC hour at which to run scheduled pulse loads

scheduledReloadTypestring

Warehouse Native only - reload type for scheduled reloads

scheduledReloadDaysinteger[]

Warehouse Native only - days on which to run scheduled reloads from 0 to 6, 0 meaning Sunday. Null to run reloads on all days.

turboModeboolean

Warehouse Native only - whether to run scheduled reloads with Turbo mode.

autoLoadToplineImpactboolean

Warehouse Native only - whether to automatically run topline and projected launch impact calculations when reloading experiments.

analysisEndTimestring

Warehouse Native only - end time for analysis only experiments

assignmentSourceFiltersobject[]

Array of criteria for filtering assignment sources.

Show child attributes
column[]string

Column to filter on.

condition[]stringrequired
values[]string[]

Optional array of values for the criterion to match against.

analyticsTypestring

The mode of analysis for the experiment, e.g frequentist, bayesian, sprt

defaultSPRTPowerParamnumber

SPRT power parameter percentage used as the default for experiment analysis.

defaultSPRTMDEnumber

Default MDE value for every metric if one isn't provided. Only used in manual mode.

sprtBaselineModestring

In manual mode, mde/mean/stdDev must be provided for every metric in the experiment. In in_experiment_control, only the mde is needed for every metric, or the defaultSPRTMDE field must be passed.

sprtMDESettingsobject[]

The SPRT values for use in the experiment.

Show child attributes
metricKey[]stringrequired
groupSettings[]object[]required
Show child attributes
groupKey[]stringrequired
mde[]numberrequired
mean[]number
stdDev[]number
isSidecarboolean

Whether this is a Statsig Sidecar experiment.

decisionReasonstring

Experiment notes reported after experiment completes

preComputedUserDimensionsobject[]

User dimensions that will be computed for every metric in WHN

Show child attributes
propertySource[]string
name[]stringrequired
cureCovariatesobject[]

CURE Covariates to use in this experiment

Show child attributes
name[]stringrequired
type[]stringrequired
stratifiedSamplingobject

The stratified sampling settings for the experiment

Show child attributes
statusstringrequired
metricobject
Show child attributes
namestringrequired
typestring
startDatestringrequired
endDatestringrequired
entityPropertySourceobject
Show child attributes
propertySourceNamestringrequired
columnstringrequired
csvobject
Show child attributes
originalstringrequired
identifierstringrequired
useStratifiedSaltboolean

Whether successful stratified sampling is currently used for experiment assignment.

useUnitsboolean

Whether stratified sampling was configured to use allocated units directly.

deltaReductionnumber

Observed reduction in delta after running stratified sampling.

spreadReductionnumber

Observed reduction in spread after running stratified sampling.

enabledNonProdEnvironmentsstring[]
idstring

The experiment name ID

layerIDstring

Which layer to place the experiment into.

Response

application/json
201Create Experiment Success
messagestringrequired

A simple string explaining the result of the operation.

dataobjectrequired
Show child attributes
reviewSettingsobject
Show child attributes
requiredReviewbooleanrequired
allowedReviewersobject[]
Show child attributes
id[]stringrequired
name[]stringrequired
email[]stringrequired
activeReviewobject
Show child attributes
reviewIDstringrequired
reviewStatusstringrequired
descriptionstringrequired
idstringrequired

ID

namestring

The display name of the experiment

idTypestringrequired
descriptionstringrequired

A helpful summary of what this experiment does

lastModifierIDstringrequired

ID of the last modifier.

lastModifiedTimenumberrequired

Time of the last modification.

lastModifierEmailstringrequired

Email of the last modifier.

lastModifierNamestringrequired

Name of the last modifier.

creatorIDstring

The Statsig ID of the creator of this experiment

createdTimenumberrequired

Timestamp when the entity was created.

creatorNamestringrequired

Name of the creator.

creatorEmailstring

The email of the creator of this experiment

tagsstring[]required
targetAppsoneOf

Target apps assigned to this experiment

holdoutIDsstring[]

Holdouts applied to this configuration.

teamstring

The team name associated with the experiment, Enterprise only.

teamIDstring

The team ID associated with the experiment, Enterprise only.

versionnumber

Version number

secondaryIDTypestring

The secondary ID type for the experiment used in WHN for ID resolution

identifierMappingModestring

The identifier mapping mode for the experiment used in WHN for ID resolution

identityResolutionSourcestring

The identity resolution entity property source for the experiment used in WHN for ID resolution

hypothesisstringrequired

A statement that will be tested by this experiment

linksobject[]

Links to relevant documentation or resources

Show child attributes
url[]stringrequired

The URL of the link

title[]string

The title of the link

externalEventsobject[]
Show child attributes
name[]stringrequired
timestamp[]numberrequired
groupsobject[]required

The test groups for your experiment

Show child attributes
name[]stringrequired
id[]string
size[]numberrequired
parameterValues[]objectrequired
disabled[]boolean
description[]string
foreignGroupID[]string
highlighted[]boolean

Marks this experiment group as highlighted in analysis views. Highlighted groups are prioritized (shown first) and can be used to filter.

controlGroupIDstring

Optional control group ID

allocationnumberrequired

Percent of layer allocated to this experiment

userBucketsnumber[]
primaryMetricTagsstring[]

Primary metric tags for the experiment

secondaryMetricTagsstring[]

Secondary metric tags for the experiment

primaryMetricsobject[]required
Show child attributes
name[]stringrequired

The metric name.

type[]stringrequired

The metric type.

direction[]string

The expected direction for one-sided testing (a feature to only measure metric movements in a single direction)

hypothesizedValue[]number

The comparison value for the one-sample testing (a feature to use a fixed baseline as the control value)

secondaryMetricsobject[]required
Show child attributes
name[]stringrequired

The metric name.

type[]stringrequired

The metric type.

direction[]string

The expected direction for one-sided testing (a feature to only measure metric movements in a single direction)

hypothesizedValue[]number

The comparison value for the one-sample testing (a feature to use a fixed baseline as the control value)

otherMetricsobject[]

Additional metrics you want to investigate or learn from. The usual corrections applied to Primary and Secondary metrics are not applied to these.

Show child attributes
name[]stringrequired

The metric name.

type[]stringrequired

The metric type.

direction[]string

The expected direction for one-sided testing (a feature to only measure metric movements in a single direction)

hypothesizedValue[]number

The comparison value for the one-sample testing (a feature to use a fixed baseline as the control value)

durationinteger

How long the experiment is expected to last in days

targetExposuresinteger

Target exposures for the experiment

targetingGateIDstringrequired

Restrict your experiment to users passing the selected feature gate

sequentialTestingboolean

Apply sequential testing?

bonferroniCorrectionbooleanrequired

Is Bonferroni correction applied per variant?

bonferroniCorrectionPerMetricboolean

Is Bonferroni correction applied per metric?

benjaminiHochbergPerVariantboolean

Is Benjamini-Hochberg procedure applied per variant?

benjaminiHochbergPerMetricboolean

Is Benjamini-Hochberg procedure applied per metric?

benjaminiPrimaryMetricsOnlyboolean

Is Benjamini-Hochberg procedure applied for primary metrics only?

defaultConfidenceIntervalstringrequired

Default error margin used for results

defaultRollupWindowinteger

Default rollup window in days for experiment results. Use -1 for cumulative. Only -1, 1, and 7 allowed for cloud experiments.

defaultChanceToBeatThresholdnumber

Default chance-to-beat threshold used for Bayesian results.

bayesianPriorsobject[]

Bayesian prior settings by metric.

Show child attributes
metric[]objectrequired
Show child attributes
namestringrequired
typestringrequired
priorMean[]numberrequired
priorStdDev[]numberrequired
manualQualityScoresobject[]

Up to 10 manually set quality scores for an experiment. The scores and weights will be added to the existing weights and scores, and then weights will be renormalized to 100. This can be set via the Statsig Console API. If targeting a default check, the weight of the check will be updated, but not the status or description. A default score can be removed by setting the weight to 0. The default score identifiers are one of: HYPOTHESIS_LENGTH, BALANCED_EXPOSURE, PRIMARY_METRICS_LENGTH, COMPARISON_CORRECTION, GUARDRAIL_METRIC_TAGS, SUFFICIENT_SAMPLE, POWER_ANALYSIS, SEQUENTIAL_TESTING

Show child attributes
criteriaName[]oneOfrequired
status[]stringrequired
criteriaDescription[]stringrequired
score[]numberrequired
weight[]numberrequired
statusstringrequired

The current status of the experiment

launchedGroupIDstring

ID of the launched group, null otherwise

assignmentSourceNamestring
assignmentSourceExperimentNamestring

Name of the source experiment for assignment

isAnalysisOnlyboolean
allocationDurationinteger

Warehouse Native Only - Allocation duration in days

cohortedAnalysisDurationinteger

Warehouse Native Only - Cohorted analysis duration in days

cohortedMetricsMatureAfterEndboolean

Warehouse Native Only - Allow cohort metrics to mature after experiment end

cohortWaitUntilEndToIncludeboolean

Warehouse Native Only - Whether to filter to units whose experiment cohort analysis duration is complete, if cohortedAnalysisDuration exists

fixedAnalysisDurationinteger

Fixed analysis duration in days

scheduledReloadHourinteger

Warehouse Native only - UTC hour at which to run scheduled pulse loads

scheduledReloadTypestring

Warehouse Native only - reload type for scheduled reloads

scheduledReloadDaysinteger[]

Warehouse Native only - days on which to run scheduled reloads from 0 to 6, 0 meaning Sunday. Null to run reloads on all days.

turboModeboolean

Warehouse Native only - whether to run scheduled reloads with Turbo mode.

autoLoadToplineImpactboolean

Warehouse Native only - whether to automatically run topline and projected launch impact calculations when reloading experiments.

analysisEndTimestring
assignmentSourceFiltersobject[]

Array of criteria for filtering assignment sources.

Show child attributes
column[]string

Column to filter on.

condition[]stringrequired
values[]string[]

Optional array of values for the criterion to match against.

analyticsTypestring
defaultSPRTPowerParamnumber
defaultSPRTMDEnumber
sprtBaselineModestring
sprtMDESettingsobject[]
Show child attributes
metricKey[]stringrequired
groupSettings[]object[]required
Show child attributes
groupKey[]stringrequired
mde[]numberrequired
mean[]number
stdDev[]number
isSidecarboolean

Whether this is a Statsig Sidecar experiment.

decisionReasonstringrequired
preComputedUserDimensionsobject[]

User dimensions that will be computed for every metric in WHN

Show child attributes
propertySource[]string
name[]stringrequired
cureCovariatesobject[]

CURE Covariates to use in this experiment

Show child attributes
name[]stringrequired
type[]stringrequired
stratifiedSamplingobject

The stratified sampling settings for the experiment

Show child attributes
statusstringrequired
metricobject
Show child attributes
namestringrequired
typestring
startDatestringrequired
endDatestringrequired
entityPropertySourceobject
Show child attributes
propertySourceNamestringrequired
columnstringrequired
csvobject
Show child attributes
originalstringrequired
identifierstringrequired
useStratifiedSaltboolean

Whether successful stratified sampling is currently used for experiment assignment.

useUnitsboolean

Whether stratified sampling was configured to use allocated units directly.

deltaReductionnumber

Observed reduction in delta after running stratified sampling.

spreadReductionnumber

Observed reduction in spread after running stratified sampling.

enabledNonProdEnvironmentsstring[]
subtypestring
externalExperimentNamestring
layerIDstringrequired
startTimenumberrequired
endTimenumberrequired
decisionTimenumberrequired
healthChecksobject[]
Show child attributes
name[]stringrequired
description[]stringrequired
status[]stringrequired
metadata[]object
Show child attributes
typestringrequired
lastPulseLoadTimenumber
crossoverPercentnumber
p_valuenumber
assignmentSourceIDstring
assignmentSourceNamestring
foreignExperimentIDstring
deduplication_ratenumber
deduplication_ratesobject[]
Show child attributes
group_id[]stringrequired
rate[]numberrequired
group_name[]stringrequired
primary_id_typestringrequired
secondary_id_typestring
missingMetricsstring[]
metricsobject[]
Show child attributes
metric_name[]stringrequired
earliest_date[]stringrequired
latest_date[]stringrequired
lastUpdatedDsstring
groupsobject[]
Show child attributes
groupID[]stringrequired
groupName[]stringrequired
status[]stringrequired
metrics[]object[]required
Show child attributes
metricKey[]stringrequired
metricTitle[]stringrequired
status[]stringrequired
groupBucketInfoobject[]
Show child attributes
groupID[]stringrequired
averageBucketSize[]numberrequired
type[]string
healthCheckStatusstringrequired

Overall health check status

experimentTypestringrequired

The type of experiment

isStalebooleanrequired

Whether the experiment is considered stale (e.g. in progress or decision-made and not modified in 30+ days).

ownerobject

Schema for owner data including ID, type, name. Note that if Entity is created by CONSOLE API, owner will be undefined.

Show child attributes
ownerIDstring

ID of the owner

ownerTypestring

Type of the owner (e.g., SDK_KEY or USER)

ownerNamestring

The name of the owner. This field is optional.

ownerEmailstring

The email of the owner. This field is optional.

inlineTargetingRulesJSONstring

A raw JSON string of the inline targeting rules

inlineTargetingRulesobject[]

A formatted array of the inline targeting rules

Show child attributes
name[]stringrequired

The name of this rule.

passPercentage[]numberrequired

Of the users that meet the conditions of this rule, what percent should return true.

conditions[]object[]required

An array of Condition objects.

Show child attributes
targetValue[]oneOf
operator[]string
field[]string
customID[]string
type[]stringrequired
environments[]string[]

The environments this rule is enabled for.

id[]string

The Statsig ID of this rule.

baseID[]string

The base ID of this rule, i.e. without any added metadata. Will remain the exact same throughout

returnValue[]object

The return value of the rule.

completedAutomatedRollouts[]object[]

Read-only: Automated rollout phases that have already completed.

Show child attributes
time[]number
passPercent[]numberrequired
pendingAutomatedRollouts[]object[]

Read-only: Automated rollout phases that are scheduled but not yet complete.

Show child attributes
time[]number
passPercent[]numberrequired
qualityScoreobject

The experiment quality score and per-criterion breakdown.

Show child attributes
scorenumberrequired

The normalized experiment quality score.

breakdownobject[]required

The per-criterion quality score breakdown.

Show child attributes
criterion[]stringrequired

The quality score criterion name.

status[]stringrequired

The quality score status for the criterion.

passingDescription[]stringrequired

The passing description for the criterion.

score[]numberrequired

The normalized score contribution for this criterion.

weight[]numberrequired

The normalized weight for this criterion.

summarySectionsobject[]
Show child attributes
name[]stringrequired
content[]stringrequired
permalinkstringrequired

A permalink to this experiment in the Statsig Console.

shipWithHoldoutobject

Present when the experiment has been shipped with a holdback group via make_decision (i.e. the winning variant is live for most users but a control slice is held back for ongoing measurement). Absent for experiments that have not been shipped, or that were shipped fully without a holdback.

Show child attributes
holdoutPercentintegerrequired

Integer percentage of users held back when the experiment was shipped with holdback. Each non-shipped group receives this percentage of traffic and the shipped group receives the remainder.

shippedGroupIDstringrequired

ID of the group that was shipped (i.e. the winning variant).

shippedGroupNamestringrequired

Name of the group that was shipped.

shippedWithHoldoutTimenumber

Unix timestamp (ms) at which the experiment was shipped with holdback.

expectedDurationnumber

Expected duration of the holdback period in days, if specified when shipping.

400Name is already in use
statusintegerrequired
messagestringrequired
401This endpoint only accepts an active CONSOLE key, but an invalid key was sent. Key: console-xxxXXXxxxXXXxxx
statusintegerrequired
messagestringrequired

Was this helpful?