openapi: 3.1.0 info: version: 1.0.0 title: GrowthBook REST AnalyticsExplorations data-sources 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: data-sources x-displayName: Data Sources description: How GrowthBook connects and queries your data, including cached database schema metadata (information schemas) for tables and columns. paths: /v1/data-sources: get: operationId: listDataSources summary: Get all data sources tags: - data-sources parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/projectId' responses: '200': content: application/json: schema: allOf: - type: object properties: dataSources: type: array items: $ref: '#/components/schemas/DataSource' required: - dataSources additionalProperties: false - $ref: '#/components/schemas/PaginationFields' x-codeSamples: - lang: cURL source: "curl -X GET 'https://api.growthbook.io/api/v1/data-sources' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v1/data-sources/{id}: get: operationId: getDataSource summary: Get a single data source tags: - data-sources parameters: - $ref: '#/components/parameters/id' responses: '200': content: application/json: schema: type: object properties: dataSource: $ref: '#/components/schemas/DataSource' required: - dataSource additionalProperties: false x-codeSamples: - lang: cURL source: "curl -X GET 'https://api.growthbook.io/api/v1/data-sources/{id}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v1/data-sources/{dataSourceId}/information-schema: get: operationId: getInformationSchema summary: Get a Data Source's Information Schema description: Returns cached database schema metadata for a data source, including databases, schemas, and tables. The information schema is automatically created when a SQL-based data source is added. Not all data source types support information schemas. tags: - data-sources parameters: - $ref: '#/components/parameters/dataSourceId' responses: '200': content: application/json: schema: type: object properties: informationSchema: $ref: '#/components/schemas/InformationSchema' required: - informationSchema additionalProperties: false x-codeSamples: - lang: cURL source: "curl -X GET 'https://api.growthbook.io/api/v1/data-sources/{dataSourceId}/information-schema' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" /v1/information-schema-tables/{tableId}: get: operationId: getInformationSchemaTable summary: Get a single Information Schema Table by id description: Returns cached metadata for a specific table in the Data Source, including columns and their data types. Not all data source types support information schemas. tags: - data-sources parameters: - $ref: '#/components/parameters/tableId' responses: '200': content: application/json: schema: type: object properties: informationSchemaTable: $ref: '#/components/schemas/InformationSchemaTable' required: - informationSchemaTable additionalProperties: false x-codeSamples: - lang: cURL source: "curl -X GET 'https://api.growthbook.io/api/v1/information-schema-tables/{tableId}' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" components: parameters: offset: name: offset in: query description: How many items to skip (use in conjunction with limit for pagination) schema: default: 0 description: How many items to skip (use in conjunction with limit for pagination) type: integer minimum: 0 dataSourceId: name: dataSourceId in: path required: true description: The id of the data source schema: description: The id of the data source type: string tableId: name: tableId in: path required: true description: The id of the information schema table schema: description: The id of the information schema table type: string id: name: id in: path required: true description: The id of the requested resource schema: description: The id of the requested resource type: string projectId: name: projectId in: query description: Filter by project id schema: description: Filter by project id type: string limit: name: limit in: query description: The number of items to return schema: default: 10 description: The number of items to return type: integer minimum: 1 maximum: 100 schemas: InformationSchema: type: object properties: id: type: string datasourceId: type: string status: type: string enum: - PENDING - COMPLETE error: type: object properties: errorType: type: string enum: - generic - not_supported - missing_params message: type: string required: - errorType - message additionalProperties: false databases: type: array items: type: object properties: databaseName: type: string path: type: string dateCreated: format: date-time type: string dateUpdated: format: date-time type: string schemas: type: array items: type: object properties: schemaName: type: string path: type: string dateCreated: format: date-time type: string dateUpdated: format: date-time type: string tables: type: array items: type: object properties: tableName: type: string path: type: string id: type: string numOfColumns: type: number dateCreated: format: date-time type: string dateUpdated: format: date-time type: string required: - tableName - id - numOfColumns - dateCreated - dateUpdated additionalProperties: false required: - schemaName - dateCreated - dateUpdated - tables additionalProperties: false required: - databaseName - dateCreated - dateUpdated - schemas additionalProperties: false dateCreated: format: date-time type: string dateUpdated: format: date-time type: string required: - id - datasourceId - status - databases - dateCreated - dateUpdated additionalProperties: false DataSource: type: object properties: id: type: string dateCreated: format: date-time type: string dateUpdated: format: date-time type: string type: type: string name: type: string description: type: string projectIds: type: array items: type: string eventTracker: type: string identifierTypes: type: array items: type: object properties: id: type: string description: type: string required: - id - description additionalProperties: false assignmentQueries: type: array items: type: object properties: id: type: string name: type: string description: type: string identifierType: type: string sql: type: string includesNameColumns: type: boolean dimensionColumns: type: array items: type: string required: - id - name - description - identifierType - sql - includesNameColumns - dimensionColumns additionalProperties: false identifierJoinQueries: type: array items: type: object properties: identifierTypes: type: array items: type: string sql: type: string required: - identifierTypes - sql additionalProperties: false mixpanelSettings: type: object properties: viewedExperimentEventName: type: string experimentIdProperty: type: string variationIdProperty: type: string extraUserIdProperty: type: string required: - viewedExperimentEventName - experimentIdProperty - variationIdProperty - extraUserIdProperty additionalProperties: false required: - id - dateCreated - dateUpdated - type - name - description - projectIds - eventTracker - identifierTypes - assignmentQueries - identifierJoinQueries additionalProperties: false PaginationFields: type: object properties: limit: type: integer offset: type: integer count: type: integer total: type: integer hasMore: type: boolean nextOffset: anyOf: - type: integer - type: 'null' required: - limit - offset - count - total - hasMore - nextOffset additionalProperties: false InformationSchemaTable: type: object properties: id: type: string datasourceId: type: string informationSchemaId: type: string tableName: type: string tableSchema: type: string databaseName: type: string columns: type: array items: type: object properties: columnName: type: string dataType: type: string required: - columnName - dataType additionalProperties: false refreshMS: type: number dateCreated: format: date-time type: string dateUpdated: format: date-time type: string required: - id - datasourceId - informationSchemaId - tableName - tableSchema - databaseName - columns - refreshMS - dateCreated - dateUpdated additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: 'If using Bearer auth, pass the Secret Key as the token: ```bash curl https://api.growthbook.io/api/v1/features -H "Authorization: Bearer secret_abc123DEF456" ``` ' basicAuth: type: http scheme: basic description: 'If using HTTP Basic auth, pass the Secret Key as the username and leave the password blank: ```bash curl https://api.growthbook.io/api/v1/features -u secret_abc123DEF456: # The ":" at the end stops curl from asking for a password ``` ' x-tagGroups: - name: Endpoints tags: - projects - environments - features-v2 - feature-revisions-v2 - features - feature-revisions - ramp-schedules - data-sources - fact-tables - fact-metrics - metrics - experiments - namespaces - snapshots - dimensions - segments - sdk-connections - visual-changesets - saved-groups - organizations - members - code-references - archetypes - queries - settings - attributes - usage - Dashboards - CustomFields - MetricGroups - Teams - ExperimentTemplates - AnalyticsExplorations - RampScheduleTemplates - name: Models tags: - AnalyticsExploration_model - Archetype_model - Attribute_model - CodeRef_model - CustomField_model - Dashboard_model - DataSource_model - Dimension_model - Environment_model - Experiment_model - ExperimentAnalysisSettings_model - ExperimentDecisionFrameworkSettings_model - ExperimentMetric_model - ExperimentMetricOverrideEntry_model - ExperimentResults_model - ExperimentSnapshot_model - ExperimentTemplate_model - ExperimentWithEnhancedStatus_model - FactMetric_model - FactTable_model - FactTableColumn_model - FactTableFilter_model - Feature_model - FeatureBaseRule_model - FeatureDefinition_model - FeatureEnvironment_model - FeatureEnvironmentV2_model - FeatureExperimentRefRule_model - FeatureExperimentRule_model - FeatureForceRule_model - FeatureRevision_model - FeatureRevisionV2_model - FeatureRolloutRule_model - FeatureRule_model - FeatureRuleV2_model - FeatureSafeRolloutRule_model - FeatureV2_model - FeatureWithRevisions_model - FeatureWithRevisionsV2_model - InformationSchema_model - InformationSchemaTable_model - LookbackOverride_model - Member_model - Metric_model - MetricAnalysis_model - MetricGroup_model - MetricUsage_model - Namespace_model - NamespaceExperimentMember_model - Organization_model - PaginationFields_model - Project_model - Query_model - RampSchedule_model - RampScheduleTemplate_model - SavedGroup_model - ScheduleRule_model - SdkConnection_model - Segment_model - Settings_model - Team_model - VisualChange_model - VisualChangeset_model