GrowthBook AnalyticsExplorations API
The AnalyticsExplorations API from GrowthBook — 3 operation(s) for analyticsexplorations.
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST AnalyticsExplorations 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: AnalyticsExplorations
x-displayName: Analytics Explorations
description: ''
paths:
/v1/product-analytics/metric-exploration:
post:
operationId: postMetricExploration
summary: Create a Metric based visualization
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- in
- not_in
- contains
- not_contains
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- last7Days
- last30Days
- last90Days
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- in
- not_in
- contains
- not_contains
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
exploration:
anyOf:
- type: object
properties:
id:
type: string
dateCreated:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
dateUpdated:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
datasource:
type: string
status:
type: string
enum:
- running
- success
- error
dateStart:
type: string
dateEnd:
type: string
error:
anyOf:
- type: string
- type: 'null'
result:
type: object
properties:
rows:
type: array
items:
type: object
properties:
dimensions:
type: array
items:
anyOf:
- type: string
- type: 'null'
values:
type: array
items:
type: object
properties:
metricId:
type: string
numerator:
anyOf:
- type: number
- type: 'null'
denominator:
anyOf:
- type: number
- type: 'null'
required:
- metricId
- numerator
- denominator
additionalProperties: false
required:
- dimensions
- values
additionalProperties: false
required:
- rows
additionalProperties: false
config:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: static
column:
type: string
values:
type: array
items:
type: string
required:
- dimensionType
- column
- values
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: slice
slices:
type: array
items:
type: object
properties:
name:
type: string
filters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- in
- not_in
- contains
- not_contains
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
required:
- name
- filters
additionalProperties: false
required:
- dimensionType
- slices
additionalProperties: false
chartType:
type: string
enum:
- line
- area
- timeseries-table
- table
- bar
- stackedBar
- horizontalBar
- stackedHorizontalBar
- bigNumber
dateRange:
type: object
properties:
predefined:
type: string
enum:
- today
- last7Days
- last30Days
- last90Days
- customLookback
- customDateRange
lookbackValue:
anyOf:
- type: number
- type: 'null'
lookbackUnit:
anyOf:
- type: string
enum:
- hour
- day
- week
- month
- type: 'null'
startDate:
anyOf:
- type: string
- type: 'null'
endDate:
anyOf:
- type: string
- type: 'null'
required:
- predefined
additionalProperties: false
showAs:
type: string
enum:
- total
- per_unit
type:
type: string
const: metric
dataset:
type: object
properties:
type:
type: string
const: metric
values:
type: array
items:
type: object
properties:
name:
type: string
rowFilters:
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- <
- <=
- '>'
- '>='
- in
- not_in
- contains
- not_contains
- starts_with
- ends_with
- is_null
- not_null
- is_true
- is_false
- sql_expr
- saved_filter
column:
type: string
values:
type: array
items:
type: string
required:
- operator
additionalProperties: false
type:
type: string
const: metric
metricId:
type: string
unit:
anyOf:
- type: string
- type: 'null'
denominatorUnit:
anyOf:
- type: string
- type: 'null'
required:
- name
- rowFilters
- type
- metricId
- unit
- denominatorUnit
additionalProperties: false
required:
- type
- values
additionalProperties: false
required:
- datasource
- dimensions
- chartType
- dateRange
- type
- dataset
additionalProperties: false
required:
- id
- dateCreated
- dateUpdated
- datasource
- status
- dateStart
- dateEnd
- result
- config
additionalProperties: false
- type: 'null'
query:
anyOf:
- $ref: '#/components/schemas/Query'
- type: 'null'
explorationUrl:
description: A direct link to view this exploration in the GrowthBook Application.
type: string
message:
description: Present when `exploration` is null, explaining why no result was returned.
type: string
required:
- exploration
- query
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/product-analytics/metric-exploration' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/product-analytics/fact-table-exploration:
post:
operationId: postFactTableExploration
summary: Run a Fact Table based visualization
tags:
- AnalyticsExplorations
parameters:
- $ref: '#/components/parameters/cache'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
datasource:
description: ID of the datasource to query
type: string
dimensions:
type: array
items:
anyOf:
- type: object
properties:
dimensionType:
type: string
const: date
column:
anyOf:
- type: string
- type: 'null'
dateGranularity:
type: string
enum:
- auto
- hour
- day
- week
- month
- year
required:
- dimensionType
- column
- dateGranularity
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
const: dynamic
column:
anyOf:
- type: string
- type: 'null'
maxValues:
type: number
required:
- dimensionType
- column
- maxValues
additionalProperties: false
- type: object
properties:
dimensionType:
type: string
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-analyticsexplorations-api-openapi.yml