GrowthBook fact-tables API
Fact Tables describe the shape of your data warehouse tables
OpenAPI Specification
openapi: 3.1.0
info:
version: 1.0.0
title: GrowthBook REST AnalyticsExplorations fact-tables 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: fact-tables
x-displayName: Fact Tables
description: Fact Tables describe the shape of your data warehouse tables
paths:
/v1/fact-tables:
get:
operationId: listFactTables
summary: Get all fact tables
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/datasourceId'
- $ref: '#/components/parameters/projectId'
responses:
'200':
content:
application/json:
schema:
allOf:
- type: object
properties:
factTables:
type: array
items:
$ref: '#/components/schemas/FactTable'
required:
- factTables
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/fact-tables' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: postFactTable
summary: Create a single fact table
tags:
- fact-tables
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
description: Description of the fact table
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
projects:
description: List of associated project ids
type: array
items:
type: string
tags:
description: List of associated tags
type: array
items:
type: string
datasource:
description: The datasource id
type: string
userIdTypes:
description: List of identifier columns in this table. For example, "id" or "anonymous_id"
type: array
items:
type: string
sql:
description: The SQL query for this fact table
type: string
eventName:
description: The event name used in SQL template variables
type: string
managedBy:
description: Set this to "api" to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
required:
- name
- datasource
- userIdTypes
- sql
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
factTable:
$ref: '#/components/schemas/FactTable'
required:
- factTable
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/fact-tables' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"Orders\",\"datasource\":\"ds_abc123\",\"userIdTypes\":[\"id\"],\"sql\":\"SELECT * FROM orders\"}'"
/v1/fact-tables/{id}:
get:
operationId: getFactTable
summary: Get a single fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
factTable:
$ref: '#/components/schemas/FactTable'
required:
- factTable
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: updateFactTable
summary: Update a single fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
description: Description of the fact table
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
projects:
description: List of associated project ids
type: array
items:
type: string
tags:
description: List of associated tags
type: array
items:
type: string
userIdTypes:
description: List of identifier columns in this table. For example, "id" or "anonymous_id"
type: array
items:
type: string
sql:
description: The SQL query for this fact table
type: string
eventName:
description: The event name used in SQL template variables
type: string
columns:
description: Optional array of columns that you want to update. Only allows updating properties of existing columns. Cannot create new columns or delete existing ones. Columns cannot be added or deleted; column structure is determined by SQL parsing. Slice-related properties require an enterprise license.
type: array
items:
$ref: '#/components/schemas/FactTableColumn'
columnsError:
description: Error message if there was an issue parsing the SQL schema
anyOf:
- type: string
- type: 'null'
managedBy:
description: Set this to "api" to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
archived:
type: boolean
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
factTable:
$ref: '#/components/schemas/FactTable'
required:
- factTable
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/fact-tables/abc123' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"New Fact Table Name\"}'"
delete:
operationId: deleteFactTable
summary: Deletes a single fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/id'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted fact table
example: ftb_123abc
type: string
required:
- deletedId
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X DELETE 'https://api.growthbook.io/api/v1/fact-tables/abc123' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/fact-tables/{factTableId}/filters:
get:
operationId: listFactTableFilters
summary: Get all filters for a fact table
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
content:
application/json:
schema:
allOf:
- type: object
properties:
factTableFilters:
type: array
items:
$ref: '#/components/schemas/FactTableFilter'
required:
- factTableFilters
additionalProperties: false
- $ref: '#/components/schemas/PaginationFields'
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123/filters' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: postFactTableFilter
summary: Create a single fact table filter
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
description: Description of the fact table filter
type: string
value:
description: The SQL expression for this filter.
example: country = 'US'
type: string
managedBy:
description: Set this to "api" to disable editing in the GrowthBook UI. Before you do this, the Fact Table itself must also be marked as "api"
type: string
enum:
- ''
- api
required:
- name
- value
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
factTableFilter:
$ref: '#/components/schemas/FactTableFilter'
required:
- factTableFilter
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/fact-tables/abc123/filters' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\":\"High Value Order\",\"value\":\"amount>100\"}'"
/v1/fact-tables/{factTableId}/filters/{id}:
get:
operationId: getFactTableFilter
summary: Get a single fact filter
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/id'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
factTableFilter:
$ref: '#/components/schemas/FactTableFilter'
required:
- factTableFilter
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X GET 'https://api.growthbook.io/api/v1/fact-tables/abc123/filters/abc123' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
post:
operationId: updateFactTableFilter
summary: Update a single fact table filter
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description:
description: Description of the fact table filter
type: string
value:
description: The SQL expression for this filter.
example: country = 'US'
type: string
managedBy:
description: Set this to "api" to disable editing in the GrowthBook UI. Before you do this, the Fact Table itself must also be marked as "api"
type: string
enum:
- ''
- api
additionalProperties: false
responses:
'200':
content:
application/json:
schema:
type: object
properties:
factTableFilter:
$ref: '#/components/schemas/FactTableFilter'
required:
- factTableFilter
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.growthbook.io/api/v1/fact-tables/abc123/filters/abc123' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"value\":\"amount > 50\"}'"
delete:
operationId: deleteFactTableFilter
summary: Deletes a single fact table filter
tags:
- fact-tables
parameters:
- $ref: '#/components/parameters/factTableId'
- $ref: '#/components/parameters/id'
responses:
'200':
content:
application/json:
schema:
type: object
properties:
deletedId:
description: The ID of the deleted fact filter
example: flt_123abc
type: string
required:
- deletedId
additionalProperties: false
x-codeSamples:
- lang: cURL
source: "curl -X DELETE 'https://api.growthbook.io/api/v1/fact-tables/abc123/filters/abc123' \\\n -H 'Authorization: Bearer YOUR_API_KEY'"
/v1/bulk-import/facts:
post:
operationId: postBulkImportFacts
summary: Bulk import fact tables, filters, and metrics
tags:
- fact-tables
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
factTables:
type: array
items:
type: object
properties:
id:
type: string
data:
type: object
properties:
name:
type: string
description:
description: Description of the fact table
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
projects:
description: List of associated project ids
type: array
items:
type: string
tags:
description: List of associated tags
type: array
items:
type: string
datasource:
description: The datasource id
type: string
userIdTypes:
description: List of identifier columns in this table. For example, "id" or "anonymous_id"
type: array
items:
type: string
sql:
description: The SQL query for this fact table
type: string
eventName:
description: The event name used in SQL template variables
type: string
managedBy:
description: Set this to "api" to disable editing in the GrowthBook UI
type: string
enum:
- ''
- api
- admin
required:
- name
- datasource
- userIdTypes
- sql
additionalProperties: false
required:
- id
- data
additionalProperties: false
factTableFilters:
type: array
items:
type: object
properties:
factTableId:
type: string
id:
type: string
data:
type: object
properties:
name:
type: string
description:
description: Description of the fact table filter
type: string
value:
description: The SQL expression for this filter.
example: country = 'US'
type: string
managedBy:
description: Set this to "api" to disable editing in the GrowthBook UI. Before you do this, the Fact Table itself must also be marked as "api"
type: string
enum:
- ''
- api
required:
- name
- value
additionalProperties: false
required:
- factTableId
- id
- data
additionalProperties: false
factMetrics:
type: array
items:
type: object
properties:
id:
type: string
data:
type: object
properties:
name:
type: string
description:
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
projects:
type: array
items:
type: string
tags:
type: array
items:
type: string
metricType:
type: string
enum:
- proportion
- retention
- mean
- quantile
- ratio
- dailyParticipation
numerator:
type: object
properties:
factTableId:
type: string
column:
description: 'Must be empty for proportion metrics and dailyParticipation metrics. Otherwise, the column name or one of the special values: ''$$distinctUsers'' or ''$$count'' (or ''$$distinctDates'' if metricType is ''mean'' or ''ratio'' or ''quantile'' and quantileSettings.type is ''unit'')'
type: string
aggregation:
description: 'User aggregation of selected column. Either sum or max for numeric columns; count distinct for string columns; hll merge / kll merge for pre-built sketch columns (requires data-source support); ignored for special columns. Default: sum. If you specify a string column you must explicitly specify count distinct. Not used for proportion metrics; for event quantile metrics only kll merge is applicable.'
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: Array of Fact Table Filter Ids. Deprecated, use rowFilters instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: Inline filters to apply to the fact table. Keys are column names, values are arrays of values to filter by. Deprecated, use rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: Filters to apply to the rows of the fact table before aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: Not required for is_null, not_null, is_true, is_false operators.
type: array
items:
type: string
column:
description: Required for all operators except sql_expr and saved_filter.
type: string
required:
- operator
additionalProperties: false
aggregateFilterColumn:
description: Column to use to filter users after aggregation. Either '$$count' of rows or the name of a numeric column that will be summed by user. Must specify `aggregateFilter` if using this. Only can be used with 'retention' and 'proportion' metrics.
type: string
aggregateFilter:
description: Simple comparison operator and value to apply after aggregation (e.g. '= 10' or '>= 1'). Requires `aggregateFilterColumn`.
type: string
required:
- factTableId
additionalProperties: false
denominator:
description: Only when metricType is 'ratio'
type: object
properties:
factTableId:
type: string
column:
description: 'The column name or one of the special values: ''$$distinctUsers'' or ''$$count'' (or ''$$distinctDates'' if metricType is ''mean'' or ''ratio'' or ''quantile'' and quantileSettings.type is ''unit'')'
type: string
aggregation:
description: 'User aggregation of selected column. Either sum or max for numeric columns; count distinct for string columns; hll merge / kll merge for pre-built sketch columns (requires data-source support); ignored for special columns. Default: sum. If you specify a string column you must explicitly specify count distinct. Not used for proportion metrics; for event quantile metrics only kll merge is applicable.'
type: string
enum:
- sum
- max
- count distinct
- hll merge
- kll merge
filters:
deprecated: true
description: Array of Fact Table Filter Ids. Deprecated, use rowFilters instead.
type: array
items:
type: string
inlineFilters:
deprecated: true
description: Inline filters to apply to the fact table. Keys are column names, values are arrays of values to filter by. Deprecated, use rowFilters instead.
type: object
propertyNames:
type: string
additionalProperties:
type: array
items:
type: string
rowFilters:
description: Filters to apply to the rows of the fact table before aggregation.
type: array
items:
type: object
properties:
operator:
type: string
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
- in
- not_in
- is_null
- not_null
- is_true
- is_false
- contains
- not_contains
- starts_with
- ends_with
- sql_expr
- saved_filter
values:
description: Not required for is_null, not_null, is_true, is_false operato
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/growthbook/refs/heads/main/openapi/growthbook-fact-tables-api-openapi.yml