Skip to main content
API docs by Redocly

GrowthBook REST API (1.0.0)

Download OpenAPI specification:Download

GrowthBook offers a full REST API for interacting with the GrowthBook application. This is currently in beta as we add more authenticated API routes and features.

Request data can use either JSON or Form data encoding (with proper Content-Type headers). All response bodies are JSON-encoded.

The API base URL for GrowthBook Cloud is https://api.growthbook.io. For self-hosted deployments, it is the same as your API_HOST environment variable (defaults to http://localhost:3100). The rest of these docs will assume you are using GrowthBook Cloud.

Authentication

We support both the HTTP Basic and Bearer authentication schemes for convenience.

You first need to generate a new Secret Key in GrowthBook by going to Settings -> API Keys.

If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank:

curl https://api.growthbook.io/api/v1 \
  -u secret_abc123DEF456:
# The ":" at the end stops curl from asking for a password

If using Bearer auth, pass the Secret Key as the token:

curl https://api.growthbook.io/api/v1 \
-H "Authorization: Bearer secret_abc123DEF456"

Errors

The API may return the following error status codes:

  • 400 - Bad Request - Often due to a missing required parameter
  • 401 - Unauthorized - No valid API key provided
  • 402 - Request Failed - The parameters are valid, but the request failed
  • 403 - Forbidden - Provided API key does not have the required access
  • 404 - Not Found - Unknown API route or requested resource
  • 429 - Too Many Requests - You exceeded the rate limit of 60 requests per minute. Try again later.
  • 5XX - Server Error - Something went wrong on GrowthBook's end (these are rare)

The response body will be a JSON object with the following properties:

  • message - Information about the error

Projects

Projects are used to organize your feature flags and experiments

Get all projects

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer
Default: 10

The number of items to return

offset
integer

How many items to skip (use in conjunction with limit for pagination)

Responses

Request samples 

curl https://api.growthbook.io/api/v1/projects \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "projects": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single project

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/projects/prj_123abc \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "project": {
    }
}

Feature Flags

Control your feature flags programatically

Get all features

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer
Default: 10

The number of items to return

offset
integer

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

Responses

Request samples 

curl https://api.growthbook.io/api/v1/features \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "features": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single feature

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/features/my_feature \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Toggle a feature in one or more environments

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
reason
string
required
object

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "environments": {
    }
}

Response samples

Content type
application/json
{
  • "feature": {
    }
}

Data Sources

How GrowthBook connects and queries your data

Get all data sources

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer
Default: 10

The number of items to return

offset
integer

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

Responses

Request samples 

curl https://api.growthbook.io/api/v1/data-sources \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "dataSources": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single data source

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/data-sources/ds_123abc \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "dataSource": {
    }
}

Metrics

Metrics used as goals and guardrails for experiments

Get all metrics

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer
Default: 10

The number of items to return

offset
integer

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

datasourceId
string

Filter by Data Source

Responses

Request samples 

curl https://api.growthbook.io/api/v1/metrics \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "metrics": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single metric

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/metrics/met_123abc \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "metric": {
    }
}

Experiments

Experiments (A/B Tests)

Get all experiments

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer
Default: 10

The number of items to return

offset
integer

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

datasourceId
string

Filter by Data Source

experimentId
string

Filter the returned list by the experiment tracking key (id)

Responses

Request samples 

curl https://api.growthbook.io/api/v1/experiments \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "experiments": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/experiments/exp_123abc \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "experiment": {
    }
}

Get results for an experiment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

query Parameters
phase
string
dimension
string

Responses

Request samples 

curl https://api.growthbook.io/api/v1/experiments/exp_123abc/results \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "result": {
    }
}

Dimensions

Dimensions used during experiment analysis

Get all dimensions

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer
Default: 10

The number of items to return

offset
integer

How many items to skip (use in conjunction with limit for pagination)

datasourceId
string

Filter by Data Source

Responses

Request samples 

curl https://api.growthbook.io/api/v1/dimensions \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "dimensions": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single dimension

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/dimensions/dim_123abc \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "dimension": {
    }
}

Segments

Segments used during experiment analysis

Get all segments

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer
Default: 10

The number of items to return

offset
integer

How many items to skip (use in conjunction with limit for pagination)

datasourceId
string

Filter by Data Source

Responses

Request samples 

curl https://api.growthbook.io/api/v1/segments \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "segments": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single segment

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/segments/seg_123abc \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "segment": {
    }
}

SDK Connections

Client keys and settings for connecting SDKs to a GrowthBook instance

Get all sdk connections

Authorizations:
bearerAuthbasicAuth
query Parameters
limit
integer
Default: 10

The number of items to return

offset
integer

How many items to skip (use in conjunction with limit for pagination)

projectId
string

Filter by project id

withProxy
string

Responses

Request samples 

curl https://api.growthbook.io/api/v1/sdk-connections \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "connections": [
    ],
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Get a single sdk connection

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/sdk-connections/sdk_123abc \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "sdkConnection": {
    }
}

Visual Changesets

Groups of visual changes made by the visual editor to a single page

Get all visual changesets

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The experiment id the visual changesets belong to

Responses

Request samples 

curl https://api.growthbook.io/api/v1/experiments/exp_123abc/visual-changesets \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "visualChangesets": [
    ]
}

Get a single visual changeset

Authorizations:
bearerAuthbasicAuth
path Parameters
id
required
string

The id of the requested resource

Responses

Request samples 

curl https://api.growthbook.io/api/v1/visual-changesets/ds_123abc \
  -u secret_abc123DEF456:

Response samples

Content type
application/json
{
  • "visualChangeset": {
    }
}

DataSource

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
type
required
string
name
required
string
description
required
string
projectIds
required
Array of strings
eventTracker
required
string
required
Array of objects
required
Array of objects
required
Array of objects
object
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "type": "string",
  • "name": "string",
  • "description": "string",
  • "projectIds": [
    ],
  • "eventTracker": "string",
  • "identifierTypes": [
    ],
  • "assignmentQueries": [
    ],
  • "identifierJoinQueries": [
    ],
  • "mixpanelSettings": {
    }
}

Dimension

id
required
string
dateCreated
required
string
dateUpdated
required
string
owner
required
string
datasourceId
required
string
identifierType
required
string
name
required
string
query
required
string
{
  • "id": "string",
  • "dateCreated": "string",
  • "dateUpdated": "string",
  • "owner": "string",
  • "datasourceId": "string",
  • "identifierType": "string",
  • "name": "string",
  • "query": "string"
}

Experiment

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
project
required
string
hypothesis
required
string
description
required
string
tags
required
Array of strings
owner
required
string
archived
required
boolean
status
required
string
autoRefresh
required
boolean
hashAttribute
required
string
required
Array of objects
required
Array of objects
required
object (ExperimentAnalysisSettings)
object
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "project": "string",
  • "hypothesis": "string",
  • "description": "string",
  • "tags": [
    ],
  • "owner": "string",
  • "archived": true,
  • "status": "string",
  • "autoRefresh": true,
  • "hashAttribute": "string",
  • "variations": [
    ],
  • "phases": [
    ],
  • "settings": {
    },
  • "resultSummary": {
    }
}

ExperimentAnalysisSettings

datasourceId
required
string
assignmentQueryId
required
string
experimentId
required
string
segmentId
required
string
queryFilter
required
string
inProgressConversions
required
any
Enum: "include" "exclude"
attributionModel
required
any
Enum: "firstExposure" "experimentDuration"
statsEngine
required
any
Enum: "bayesian" "frequentist"
required
Array of objects (ExperimentMetric)
required
Array of objects (ExperimentMetric)
object (ExperimentMetric)
{
  • "datasourceId": "string",
  • "assignmentQueryId": "string",
  • "experimentId": "string",
  • "segmentId": "string",
  • "queryFilter": "string",
  • "inProgressConversions": "include",
  • "attributionModel": "firstExposure",
  • "statsEngine": "bayesian",
  • "goals": [
    ],
  • "guardrails": [
    ],
  • "activationMetric": {
    }
}

ExperimentMetric

metricId
required
string
required
object
{
  • "metricId": "string",
  • "overrides": {
    }
}

ExperimentResults

id
required
string
dateUpdated
required
string
experimentId
required
string
phase
required
string
dateStart
required
string
dateEnd
required
string
required
object
required
object (ExperimentAnalysisSettings)
queryIds
required
Array of strings
required
Array of objects
{
  • "id": "string",
  • "dateUpdated": "string",
  • "experimentId": "string",
  • "phase": "string",
  • "dateStart": "string",
  • "dateEnd": "string",
  • "dimension": {
    },
  • "settings": {
    },
  • "queryIds": [
    ],
  • "results": [
    ]
}

Feature

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
archived
required
boolean
description
required
string
owner
required
string
project
required
string
valueType
required
string
Enum: "boolean" "string" "number" "json"
defaultValue
required
string
tags
required
Array of strings
required
object
required
object
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "archived": true,
  • "description": "string",
  • "owner": "string",
  • "project": "string",
  • "valueType": "boolean",
  • "defaultValue": "string",
  • "tags": [
    ],
  • "environments": {
    },
  • "revision": {
    }
}

FeatureDefinition

defaultValue
required
string or number or array or object or null
Array of objects
{
  • "defaultValue": "string",
  • "rules": [
    ]
}

FeatureEnvironment

enabled
required
boolean
defaultValue
required
string
required
Array of FeatureForceRule (object) or FeatureRolloutRule (object) or FeatureExperimentRule (object) (FeatureRule)
definition
string

A JSON stringified FeatureDefinition

object
{
  • "enabled": true,
  • "defaultValue": "string",
  • "rules": [
    ],
  • "definition": "string",
  • "draft": {
    }
}

FeatureExperimentRule

description
required
string
condition
required
string
id
required
string
enabled
required
boolean
type
required
string
trackingKey
string
hashAttribute
string
namespace
obect
coverage
number
Array of objects
{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "type": "string",
  • "trackingKey": "string",
  • "hashAttribute": "string",
  • "namespace": null,
  • "coverage": 0,
  • "value": [
    ]
}

FeatureForceRule

description
required
string
condition
required
string
id
required
string
enabled
required
boolean
type
required
string
value
required
string
{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "type": "string",
  • "value": "string"
}

FeatureRolloutRule

description
required
string
condition
required
string
id
required
string
enabled
required
boolean
type
required
string
value
required
string
coverage
required
number
hashAttribute
required
string
{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "type": "string",
  • "value": "string",
  • "coverage": 0,
  • "hashAttribute": "string"
}

FeatureRule

Any of
description
required
string
condition
required
string
id
required
string
enabled
required
boolean
type
required
string
value
required
string
Example
{
  • "description": "string",
  • "condition": "string",
  • "id": "string",
  • "enabled": true,
  • "type": "string",
  • "value": "string"
}

Metric

id
required
string
dateCreated
required
string
dateUpdated
required
string
owner
required
string
datasourceId
required
string
name
required
string
description
required
string
type
required
string
tags
required
Array of strings
projects
required
Array of strings
archived
required
boolean
required
object
object
object
{
  • "id": "string",
  • "dateCreated": "string",
  • "dateUpdated": "string",
  • "owner": "string",
  • "datasourceId": "string",
  • "name": "string",
  • "description": "string",
  • "type": "string",
  • "tags": [
    ],
  • "projects": [
    ],
  • "archived": true,
  • "behavior": {
    },
  • "sql": {
    },
  • "mixpanel": {
    }
}

PaginationFields

limit
required
integer
offset
required
integer
count
required
integer
total
required
integer
hasMore
required
boolean
nextOffset
required
integer or null
{
  • "limit": 0,
  • "offset": 0,
  • "count": 0,
  • "total": 0,
  • "hasMore": true,
  • "nextOffset": 0
}

Project

id
required
string
name
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
{
  • "id": "string",
  • "name": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z"
}

SdkConnection

id
required
string
dateCreated
required
string <date-time>
dateUpdated
required
string <date-time>
name
required
string
languages
required
Array of strings
environment
required
string
project
required
string
encryptPayload
required
boolean
encryptionKey
required
string
key
required
string
proxyEnabled
required
boolean
proxyHost
required
string
proxySigningKey
required
string
{
  • "id": "string",
  • "dateCreated": "2019-08-24T14:15:22Z",
  • "dateUpdated": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "languages": [
    ],
  • "environment": "string",
  • "project": "string",
  • "encryptPayload": true,
  • "encryptionKey": "string",
  • "key": "string",
  • "proxyEnabled": true,
  • "proxyHost": "string",
  • "proxySigningKey": "string"
}

Segment

id
required
string
owner
required
string
datasourceId
required
string
identifierType
required
string
name
required
string
query
required
string
dateCreated
required
string
dateUpdated
required
string
{
  • "id": "string",
  • "owner": "string",
  • "datasourceId": "string",
  • "identifierType": "string",
  • "name": "string",
  • "query": "string",
  • "dateCreated": "string",
  • "dateUpdated": "string"
}

VisualChangeset

id
string
urlPattern
required
string
editorUrl
required
string
experiment
required
string
required
Array of objects
{
  • "id": "string",
  • "urlPattern": "string",
  • "editorUrl": "string",
  • "experiment": "string",
  • "visualChanges": [
    ]
}