OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST AnalyticsExplorations experiments API
description: "GrowthBook offers a full REST API for interacting with the application.\n\nRequest data can use either JSON or Form data encoding (with proper `Content-Type` headers). All response bodies are JSON-encoded.\n\nThe API base URL for GrowthBook Cloud is `https://api.growthbook.io/api`. For self-hosted deployments, it is the same as your API_HOST environment variable (defaults to `http://localhost:3100/api`). The rest of these docs will assume you are using GrowthBook Cloud.\n\n## Versioning\n\nEndpoints are versioned by path prefix:\n\n- `/v1/...` — stable, widely-supported endpoints\n- `/v2/...` — updated endpoints with improved shapes (e.g. unified per-rule environment scope for feature flags)\n\nNew integrations should prefer v2 where available.\n\n## Authentication\n\nWe support both the HTTP Basic and Bearer authentication schemes for convenience.\n\nYou first need to generate a new API Key in GrowthBook. Different keys have different permissions:\n\n- **Personal Access Tokens**: These are sensitive and provide the same level of access as the user has to an organization. These can be created by going to `Personal Access Tokens` under the your user menu.\n- **Secret Keys**: These are sensitive and provide the level of access for the role, which currently is either `admin` or `readonly`. Only Admins with the `manageApiKeys` permission can manage Secret Keys on behalf of an organization. These can be created by going to `Settings -> API Keys`\n\nIf using HTTP Basic auth, pass the Secret Key as the username and leave the password blank (when using curl, add `:` at the end of the secret to indicate an empty password)\n\n```bash\ncurl https://api.growthbook.io/api/v1/features \\\n -u secret_abc123DEF456:\n```\n\nIf using Bearer auth, pass the Secret Key as the token:\n\n```bash\ncurl https://api.growthbook.io/api/v1/features \\\n-H \"Authorization: Bearer secret_abc123DEF456\"\n```\n\n## Errors\n\nThe API may return the following error status codes:\n\n- **400** - Bad Request - Often due to a missing required parameter\n- **401** - Unauthorized - No valid API key provided\n- **402** - Request Failed - The parameters are valid, but the request failed\n- **403** - Forbidden - Provided API key does not have the required access\n- **404** - Not Found - Unknown API route or requested resource\n- **429** - Too Many Requests - You exceeded the rate limit of 60 requests per minute. Try again later.\n- **5XX** - Server Error - Something went wrong on GrowthBook's end (these are rare)\n\nThe response body will be a JSON object with the following properties:\n\n- **message** - Information about the error\n"
servers:
- url: https://api.growthbook.io/api
description: GrowthBook Cloud
- url: https://{domain}/api
description: Self-hosted GrowthBook
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: experiments
x-displayName: Experiments
description: Experiments (A/B Tests)
paths:
/v1/experiments:
get:
operationId: listExperiments
summary: Get all experiments
tags:
- experiments
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/datasourceId'
- $ref: '#/components/parameters/trackingKey'
- $ref: '#/components/parameters/experimentId'
- name: status
in: query
description: ''
schema:
type: string
enum:
- draft
- running
- stopped
responses:
'200':
content:
application/json:
schema:
allOf:
- type: object
properties:
experiments:
type: array
items:
$ref: '#/components/schemas/Experiment'
required:
- experiments
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/experiments' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: postExperiment
summary: Create a single experiment
tags:
- experiments
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasourceId:
description: ID for the [DataSource](#tag/DataSource_model). Can only be set if a templateId is not provided.
type: string
assignmentQueryId:
description: The ID property of one of the assignment query objects associated with the datasource. Can only be set if a templateId is not provided.
type: string
trackingKey:
type: string
bypassDuplicateKeyCheck:
description: If true, allow creating an experiment even if another experiment with the same tracking key already exists. This is ignored if the organization requires unique tracking keys as a rule.
type: boolean
name:
description: Name of the experiment
type: string
type:
type: string
enum:
- standard
- multi-armed-bandit
project:
description: Project ID which the experiment belongs to
type: string
templateId:
description: ID of the [ExperimentTemplate](#tag/ExperimentTemplate_model) this experiment was created from. Template fields are applied by default and overridden by explicitly provided payload fields.
type: string
hypothesis:
description: Hypothesis of the experiment
type: string
description:
description: Description of the experiment
type: string
tags:
type: array
items:
type: string
metrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
description: Users must convert on this metric before being included
type: string
segmentId:
description: Only users in this segment will be included
type: string
queryFilter:
description: WHERE clause to add to the default experiment query
type: string
owner:
description: The 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.
type: string
archived:
type: boolean
status:
type: string
enum:
- draft
- running
- stopped
autoRefresh:
type: boolean
hashAttribute:
type: string
fallbackAttribute:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
disableStickyBucketing:
type: boolean
bucketVersion:
type: number
minBucketVersion:
type: number
releasedVariationId:
type: string
excludeFromPayload:
type: boolean
inProgressConversions:
type: string
enum:
- loose
- strict
attributionModel:
description: Setting attribution model to `"experimentDuration"` is the same as selecting "Ignore Conversion Windows" for the Conversion Window Override. Setting it to `"lookbackOverride"` requires a `lookbackOverride` object to be provided.
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
lookbackOverride:
description: Controls the lookback override for the experiment. For type "window", value must be a non-negative number and valueUnit is required.
type: object
properties:
type:
type: string
enum:
- date
- window
value:
description: For "window" type - non-negative numeric value (e.g. 7 for 7 days). For "date" type a date string.
anyOf:
- description: For "window" type - non-negative numeric value (e.g. 7 for 7 days). For "date" type a date string.
type: number
- format: date-time
description: For "window" type - non-negative numeric value (e.g. 7 for 7 days). For "date" type a date string.
type: string
valueUnit:
description: Used when type is "window". Defaults to "days".
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
- value
additionalProperties: false
statsEngine:
type: string
enum:
- bayesian
- frequentist
variations:
minItems: 2
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
name:
type: string
description:
type: string
screenshots:
type: array
items:
type: object
properties:
path:
type: string
width:
type: number
height:
type: number
description:
type: string
required:
- path
additionalProperties: false
required:
- key
- name
additionalProperties: false
phases:
type: array
items:
type: object
properties:
name:
type: string
dateStarted:
format: date-time
type: string
dateEnded:
format: date-time
type: string
reasonForStopping:
type: string
seed:
type: string
coverage:
type: number
trafficSplit:
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
required:
- variationId
- weight
additionalProperties: false
namespace:
type: object
properties:
namespaceId:
type: string
enabled:
type: boolean
range:
minItems: 2
maxItems: 2
type: array
items:
type: number
ranges:
type: array
items:
type: array
prefixItems:
- type: number
- type: number
required:
- namespaceId
additionalProperties: false
targetingCondition:
type: string
prerequisites:
type: array
items:
type: object
properties:
id:
description: Feature ID
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
reason:
type: string
condition:
type: string
savedGroupTargeting:
type: array
items:
type: object
properties:
matchType:
type: string
enum:
- all
- any
- none
savedGroups:
type: array
items:
type: string
required:
- matchType
- savedGroups
additionalProperties: false
variationWeights:
type: array
items:
type: number
required:
- name
- dateStarted
additionalProperties: false
regressionAdjustmentEnabled:
description: Controls whether regression adjustment (CUPED) is enabled for experiment analyses
type: boolean
sequentialTestingEnabled:
description: Only applicable to frequentist analyses
type: boolean
sequentialTestingTuningParameter:
type: number
shareLevel:
type: string
enum:
- public
- organization
banditScheduleValue:
type: number
banditScheduleUnit:
type: string
enum:
- days
- hours
banditBurnInValue:
type: number
banditBurnInUnit:
type: string
enum:
- days
- hours
banditConversionWindowValue:
type: number
banditConversionWindowUnit:
type: string
enum:
- days
- hours
postStratificationEnabled:
description: When null, the organization default is used.
anyOf:
- description: When null, the organization default is used.
type: boolean
- description: When null, the organization default is used.
type: 'null'
decisionFrameworkSettings:
description: Controls the decision framework and metric overrides for the experiment. Replaces the entire stored object on update (does not patch individual fields).
type: object
properties:
decisionCriteriaId:
type: string
decisionFrameworkMetricOverrides:
type: array
items:
type: object
properties:
id:
description: ID of the metric to override settings for.
type: string
targetMDE:
description: The target relative MDE to use for the metric, expressed as proportions (e.g. use 0.1 for 10%). Must be greater than 0.
type: number
exclusiveMinimum: 0
required:
- id
additionalProperties: false
additionalProperties: false
metricOverrides:
description: Per-metric analysis overrides for this experiment. Replaces the entire stored array (does not patch individual entries).
type: array
items:
description: Per-metric analysis overrides stored on the experiment (matches internal metricOverrides).
type: object
properties:
id:
description: ID of the metric to override settings for.
type: string
windowType:
type: string
enum:
- conversion
- lookback
- ''
windowHours:
type: number
delayHours:
type: number
properPriorOverride:
description: Must be true for the override to take effect. If true, the other proper prior settings in this object will be used if present.
type: boolean
properPriorEnabled:
type: boolean
properPriorMean:
type: number
properPriorStdDev:
type: number
regressionAdjustmentOverride:
description: Must be true for the override to take effect. If true, the other regression adjustment settings in this object will be used if present.
type: boolean
regressionAdjustmentEnabled:
type: boolean
regressionAdjustmentDays:
type: number
required:
- id
additionalProperties: false
defaultDashboardId:
description: ID of the default dashboard for this experiment.
type: string
customFields:
type: object
propertyNames:
type: string
additionalProperties:
type: string
customMetricSlices:
description: Custom slices that apply to ALL applicable metrics in the experiment
type: array
items:
type: object
properties:
slices:
type: array
items:
type: object
properties:
column:
type: string
levels:
type: array
items:
type: string
required:
- column
- levels
additionalProperties: false
required:
- slices
additionalProperties: false
required:
- trackingKey
- name
- variations
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/Experiment'
required:
- experiment
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/experiments' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/experiments/{id}:
get:
operationId: getExperiment
summary: Get a single experiment
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
experiment:
$ref: '#/components/schemas/ExperimentWithEnhancedStatus'
required:
- experiment
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/experiments/abc123' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: updateExperiment
summary: Update a single experiment
tags:
- experiments
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasourceId:
description: Can only be set if existing experiment does not have a datasource
type: string
assignmentQueryId:
type: string
trackingKey:
type: string
bypassDuplicateKeyCheck:
description: If true, allow updating the tracking key even if another experiment with the same tracking key already exist. This is ignored if the organization requires unique tracking keys as a rule.
type: boolean
name:
description: Name of the experiment
type: string
type:
type: string
enum:
- standard
- multi-armed-bandit
project:
description: Project ID which the experiment belongs to
type: string
hypothesis:
description: Hypothesis of the experiment
type: string
description:
description: Description of the experiment
type: string
tags:
type: array
items:
type: string
metrics:
type: array
items:
type: string
secondaryMetrics:
type: array
items:
type: string
guardrailMetrics:
type: array
items:
type: string
activationMetric:
description: Users must convert on this metric before being included
type: string
segmentId:
description: Only users in this segment will be included
type: string
queryFilter:
description: WHERE clause to add to the default experiment query
type: string
owner:
description: The 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.
type: string
archived:
type: boolean
status:
type: string
enum:
- draft
- running
- stopped
autoRefresh:
type: boolean
hashAttribute:
type: string
fallbackAttribute:
type: string
hashVersion:
anyOf:
- type: number
const: 1
- type: number
const: 2
disableStickyBucketing:
type: boolean
bucketVersion:
type: number
minBucketVersion:
type: number
results:
description: The result status of the experiment. Maps to resultSummary.status in the GET response.
type: string
enum:
- dnf
- won
- lost
- inconclusive
winner:
description: The index of the winning variation (0-indexed). Maps to resultSummary.winner (variation ID) in the GET response.
type: number
analysis:
description: Analysis summary or conclusions for the experiment. Maps to resultSummary.conclusions in the GET response.
type: string
releasedVariationId:
description: The ID of the released variation. Maps to resultSummary.releasedVariationId in the GET response.
type: string
excludeFromPayload:
description: If true, the experiment is excluded from the SDK payload. Maps to resultSummary.excludeFromPayload in the GET response.
type: boolean
inProgressConversions:
type: string
enum:
- loose
- strict
attributionModel:
description: Setting attribution model to `"experimentDuration"` is the same as selecting "Ignore Conversion Windows" for the Conversion Window Override. Setting it to `"lookbackOverride"` requires a `lookbackOverride` object to be provided.
type: string
enum:
- firstExposure
- experimentDuration
- lookbackOverride
lookbackOverride:
description: Controls the lookback override for the experiment. For type "window", value must be a non-negative number and valueUnit is required.
type: object
properties:
type:
type: string
enum:
- date
- window
value:
description: For "window" type - non-negative numeric value (e.g. 7 for 7 days). For "date" type a date string.
anyOf:
- description: For "window" type - non-negative numeric value (e.g. 7 for 7 days). For "date" type a date string.
type: number
- format: date-time
description: For "window" type - non-negative numeric value (e.g. 7 for 7 days). For "date" type a date string.
type: string
valueUnit:
description: Used when type is "window". Defaults to "days".
type: string
enum:
- minutes
- hours
- days
- weeks
required:
- type
- value
additionalProperties: false
statsEngine:
type: string
enum:
- bayesian
- frequentist
variations:
minItems: 2
type: array
items:
type: object
properties:
id:
type: string
key:
type: string
name:
type: string
description:
type: string
screenshots:
type: array
items:
type: object
properties:
path:
type: string
width:
type: number
height:
type: number
description:
type: string
required:
- path
additionalProperties: false
required:
- key
- name
additionalProperties: false
phases:
type: array
items:
type: object
properties:
name:
type: string
dateStarted:
format: date-time
type: string
dateEnded:
format: date-time
type: string
reasonForStopping:
type: string
seed:
type: string
coverage:
type: number
trafficSplit:
deprecated: true
description: Deprecated and unused. Use variationWeights instead.
type: array
items:
type: object
properties:
variationId:
type: string
weight:
type: number
required:
- variationId
- weight
additionalProperties: false
namespace:
type: object
properties:
namespaceId:
type: string
range:
minItems: 2
maxItems: 2
type: array
items:
type: number
enabled:
type: boolean
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-experiments-api-openapi.yml