> ## Documentation Index > Fetch the complete documentation index at: https://docs2.growthbook.io/llms.txt > Use this file to discover all available pages before exploring further. # Get all fact metrics ## OpenAPI ````yaml openapi.yaml GET /v1/fact-metrics openapi: 3.1.0 info: version: 4.4.0 title: GrowthBook REST API description: > GrowthBook offers a full REST API for interacting with the application. 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/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. ## Versioning Endpoints are versioned by path prefix: - `/v1/...` — stable, widely-supported endpoints - `/v2/...` — updated endpoints with improved shapes (e.g. unified per-rule environment scope for feature flags) New integrations should prefer v2 where available. ## Authentication We support both the HTTP Basic and Bearer authentication schemes for convenience. You first need to generate a new API Key in GrowthBook. Different keys have different permissions: - **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. - **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` If 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) ```bash curl https://api.growthbook.io/api/v1/features \ -u secret_abc123DEF456: ``` 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" ``` ## 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 - **422** - Soft Warning - The request failed, but can be re-submitted with `?ignoreWarnings=true` to proceed anyway. - **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 servers: - url: https://api.growthbook.io/api description: GrowthBook Cloud - url: https://{domain}/api description: Self-hosted GrowthBook variables: domain: default: localhost:3100 description: Your self-hosted GrowthBook host (and port) security: - bearerAuth: [] - basicAuth: [] tags: - name: projects x-displayName: Projects description: Projects are used to organize your feature flags and experiments - name: environments x-displayName: Environments description: >- GrowthBook comes with one environment by default (production), but you can add as many as you need. When used with feature flags, you can enable/disable feature flags on a per-environment basis. - name: features-v2 x-displayName: Feature Flags description: >- Control your feature flags programatically. Rules are returned as a unified top-level array; each rule carries `allEnvironments` / `environments` scope fields instead of being bucketed by environment. - name: feature-revisions-v2 x-displayName: Feature Revisions description: >- Draft revisions for feature flags, including rules, scheduling, and approval workflows. Revision `rules` is a flat array with per-rule scope fields. - name: features x-displayName: Feature Flags (legacy) description: >- Control your feature flags programatically. **These are v1 endpoints.** New integrations should use the v2 Feature Flags endpoints, which expose a unified per-rule environment scope instead of per-environment rule arrays. - name: feature-revisions x-displayName: Feature Revisions (legacy) description: >- Draft revisions for feature flags, including rules, scheduling, and approval workflows. **These are v1 endpoints.** New integrations should use the v2 Feature Revisions endpoints. - name: ramp-schedules x-displayName: Ramp Schedules description: >- Multi-step rollout schedules that gradually increase feature rule traffic over time, with optional real-time monitoring. Each step supports interval timers, approval gates, and hold conditions. Monitored steps are backed by a live analysis experiment that can automatically hold, roll back, or advance the ramp based on guardrail and signal metric health. - 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. - name: fact-tables x-displayName: Fact Tables description: Fact Tables describe the shape of your data warehouse tables - name: fact-metrics x-displayName: Fact Metrics description: Fact Metrics are metrics built on top of Fact Table definitions - name: metrics x-displayName: Metrics (legacy) description: Metrics used as goals and guardrails for experiments - name: experiments x-displayName: Experiments description: Experiments (A/B Tests) - name: namespaces x-displayName: Namespaces description: >- Namespaces partition your user population into buckets so that experiments using the same hash attribute do not overlap unintentionally. Each namespace defines a 0–1 range and individual experiments claim sub-ranges within it. - name: snapshots x-displayName: Experiment Snapshots description: Experiment Snapshots (the individual updates of an experiment) - name: dimensions x-displayName: Dimensions description: Dimensions used during experiment analysis - name: segments x-displayName: Segments description: Segments used during experiment analysis - name: reports x-displayName: Experiment Reports description: >- Custom analysis reports built on top of experiment snapshots. Reports let you re-run analysis with different metrics, date ranges, stats engines, and other settings without modifying the underlying experiment. - name: sdk-connections x-displayName: SDK Connections description: Client keys and settings for connecting SDKs to a GrowthBook instance - name: visual-changesets x-displayName: Visual Changesets description: Groups of visual changes made by the visual editor to a single page - name: saved-groups x-displayName: Saved Groups description: >- Defined sets of attribute values which can be used with feature rules for targeting features at particular users. - name: saved-group-revisions x-displayName: Saved Group Revisions description: >- Draft revisions for saved groups, including pending changes, approvals, and lifecycle (publish, discard, revert). Most callers can interact with these endpoints via shorthand actions (`/items/add`, `/items/remove`, single-field PUTs) instead of authoring JSON Patch ops directly. Pass `version: "new"` on edit endpoints to auto-create a draft. - name: releases x-displayName: Releases description: >- **Beta** — these endpoints are new and may change in backwards-incompatible ways. Coordinated multi-entity publishing: publish a set of revisions across Feature Flags, Saved Groups, configs, and constants as one all-or-nothing operation, validated against the combined end-state instead of each in-between state. Requires the `releases` commercial feature. - name: organizations x-displayName: Organizations description: >- Organizations are used for multi-org deployments where different teams can run their own isolated feature flags and experiments. These endpoints are only via a super-admin's Personal Access Token. - name: members x-displayName: Members description: Members are users who have been invited to an organization. - name: code-references x-displayName: Code References description: >- Intended for use with our code reference CI utility, [`gb-find-code-refs`](https://github.com/growthbook/gb-find-code-refs). - name: archetypes x-displayName: Archetypes description: >- Archetypes allow you to simulate the result of targeting rules on pre-set user attributes - name: queries x-displayName: Queries description: Retrieve queries used in experiments to calculate results. - name: settings x-displayName: Settings description: Get the organization settings. - name: attributes x-displayName: Attributes description: Used when targeting feature flags and experiments. - name: usage x-displayName: Usage description: Usage information for metrics in experiments. - name: meta x-displayName: Meta description: >- Server metadata, including the running build's version and commit for version-skew checks. - name: Dashboards x-displayName: Dashboards description: '' - name: CustomFields x-displayName: Custom Fields description: '' - name: MetricGroups x-displayName: Metric Groups description: '' - name: Teams x-displayName: Teams description: '' - name: ExperimentTemplates x-displayName: Experiment Templates description: '' - name: AnalyticsExplorations x-displayName: Analytics Explorations description: '' - name: RampScheduleTemplates x-displayName: Ramp Schedule Templates description: Reusable step configurations for ramp schedules. - name: AggregatedFactTable_model x-displayName: Aggregated Fact Table description: - name: AnalyticsExploration_model x-displayName: Analytics Exploration description: - name: Archetype_model x-displayName: Archetype description: - name: Attribute_model x-displayName: Attribute description: - name: CodeRef_model x-displayName: Code Ref description: - name: CustomField_model x-displayName: Custom Field description: - name: Dashboard_model x-displayName: Dashboard description: - name: DataSource_model x-displayName: Data Source description: - name: Dimension_model x-displayName: Dimension description: - name: Environment_model x-displayName: Environment description: - name: EventUser_model x-displayName: Event User description: - name: Experiment_model x-displayName: Experiment description: - name: Experiment Rule_model x-displayName: Experiment Rule description: - name: ExperimentAnalysisSettings_model x-displayName: Experiment Analysis Settings description: >- - name: ExperimentDecisionFrameworkSettings_model x-displayName: Experiment Decision Framework Settings description: >- - name: ExperimentMetric_model x-displayName: Experiment Metric description: - name: ExperimentMetricOverrideEntry_model x-displayName: Experiment Metric Override Entry description: >- - name: ExperimentResults_model x-displayName: Experiment Results description: - name: ExperimentSnapshot_model x-displayName: Experiment Snapshot description: - name: ExperimentTemplate_model x-displayName: Experiment Template description: - name: ExperimentWithEnhancedStatus_model x-displayName: Experiment With Enhanced Status description: >- - name: FactMetric_model x-displayName: Fact Metric description: - name: FactTable_model x-displayName: Fact Table description: - name: FactTableColumn_model x-displayName: Fact Table Column description: - name: FactTableFilter_model x-displayName: Fact Table Filter description: - name: FeatureBaseRule_model x-displayName: Feature Base Rule description: - name: FeatureDefinition_model x-displayName: Feature Definition description: - name: FeatureEnvironmentV1_model x-displayName: Feature Environment V1 description: - name: FeatureEnvironmentV2_model x-displayName: Feature Environment V2 description: - name: FeatureExperimentRefRule_model x-displayName: Feature Experiment Ref Rule description: >- - name: FeatureExperimentRule_model x-displayName: Feature Experiment Rule description: >- - name: FeatureForceRule_model x-displayName: Feature Force Rule description: - name: FeatureRevisionSummary_model x-displayName: Feature Revision Summary description: >- - name: FeatureRevisionV1_model x-displayName: Feature Revision V1 description: - name: FeatureRevisionV2_model x-displayName: Feature Revision V2 description: - name: FeatureRolloutRule_model x-displayName: Feature Rollout Rule description: - name: FeatureRuleV1_model x-displayName: Feature Rule V1 description: - name: FeatureRuleV2_model x-displayName: Feature Rule V2 description: - name: FeatureSafeRolloutRule_model x-displayName: Feature Safe Rollout Rule description: >- - name: FeatureV1_model x-displayName: Feature V1 description: - name: FeatureV2_model x-displayName: Feature V2 description: - name: FeatureWithRevisionsV1_model x-displayName: Feature With Revisions V1 description: >- - name: FeatureWithRevisionsV2_model x-displayName: Feature With Revisions V2 description: >- - name: InformationSchema_model x-displayName: Information Schema description: - name: InformationSchemaTable_model x-displayName: Information Schema Table description: >- - name: LookbackOverride_model x-displayName: Lookback Override description: - name: Member_model x-displayName: Member description: - name: Metric_model x-displayName: Metric description: - name: MetricAnalysis_model x-displayName: Metric Analysis description: - name: MetricGroup_model x-displayName: Metric Group description: - name: MetricUsage_model x-displayName: Metric Usage description: - name: Namespace_model x-displayName: Namespace description: - name: NamespaceExperimentMember_model x-displayName: Namespace Experiment Member description: >- - name: Organization_model x-displayName: Organization description: - name: PaginationFields_model x-displayName: Pagination Fields description: - name: Project_model x-displayName: Project description: - name: Query_model x-displayName: Query description: - name: RampSchedule_model x-displayName: Ramp Schedule description: - name: RampScheduleTemplate_model x-displayName: Ramp Schedule Template description: - name: Report_model x-displayName: Report description: - name: Safe Rollout Rule_model x-displayName: Safe Rollout Rule description: - name: SavedGroup_model x-displayName: Saved Group description: - name: SavedGroupRevision_model x-displayName: Saved Group Revision description: - name: SavedGroupRevisionActivityLogEntry_model x-displayName: Saved Group Revision Activity Log Entry description: >- - name: SavedGroupRevisionReview_model x-displayName: Saved Group Revision Review description: >- - name: ScheduleRule_model x-displayName: Schedule Rule description: - name: SdkConnection_model x-displayName: Sdk Connection description: - name: Segment_model x-displayName: Segment description: - name: Settings_model x-displayName: Settings description: - name: Targeting Rule_model x-displayName: Targeting Rule description: - name: Team_model x-displayName: Team description: - name: VisualChange_model x-displayName: Visual Change description: - name: VisualChangeset_model x-displayName: Visual Changeset description: paths: /v1/fact-metrics: get: tags: - fact-metrics summary: Get all fact metrics operationId: listFactMetrics parameters: - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/datasourceId' - $ref: '#/components/parameters/projectId' - name: factTableId in: query description: >- Filter by Fact Table Id (for ratio metrics, we only look at the numerator) schema: description: >- Filter by Fact Table Id (for ratio metrics, we only look at the numerator) type: string responses: '200': description: Successful response content: application/json: schema: allOf: - type: object properties: factMetrics: type: array items: $ref: '#/components/schemas/FactMetric' required: - factMetrics additionalProperties: false - $ref: '#/components/schemas/PaginationFields' x-codeSamples: - lang: cURL source: |- curl -X GET 'https://api.growthbook.io/api/v1/fact-metrics' \ -H 'Authorization: Bearer YOUR_API_KEY' components: parameters: 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 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: query description: Filter by Data Source schema: description: Filter by Data Source type: string projectId: name: projectId in: query description: Filter by project id schema: description: Filter by project id type: string schemas: FactMetric: type: object properties: id: type: string name: type: string description: type: string maxLength: 10000 owner: description: The userId of the owner (or raw owner name/email for legacy records) type: string ownerEmail: description: >- The email address of the owner, when the owner can be resolved to a known user. type: string projects: type: array items: type: string tags: type: array items: type: string datasource: type: string metricType: type: string enum: - proportion - retention - mean - quantile - ratio - dailyParticipation numerator: type: object properties: factTableId: type: string column: type: string aggregation: 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 - column additionalProperties: false denominator: type: object properties: factTableId: type: string column: type: string 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 required: - factTableId - column additionalProperties: false inverse: description: >- Set to true for things like Bounce Rate, where you want the metric to decrease type: boolean quantileSettings: description: >- Controls the settings for quantile metrics (mandatory if metricType is "quantile") type: object properties: type: description: >- Whether the quantile is over unit aggregations or raw event values type: string enum: - event - unit ignoreZeros: description: >- If true, zero values will be ignored when calculating the quantile type: boolean quantile: description: The quantile value (from 0.001 to 0.999) type: number minimum: 0.001 maximum: 0.999 multipleOf: 0.001 quantileEventCountColumn: description: >- Optional override for the source-column name used to recover per-row event counts when numerator.aggregation is 'kll merge'. Defaults to '_n_events'. Only valid for event-quantile metrics with a 'kll merge' numerator. type: string required: - type - ignoreZeros - quantile additionalProperties: false cappingSettings: description: Controls how outliers are handled type: object properties: type: type: string enum: - none - absolute - percentile value: description: >- When type is absolute, this is the absolute value. When type is percentile, this is the percentile value (from 0.0 to 1.0). type: number ignoreZeros: description: >- If true and capping is `percentile`, zeros will be ignored when calculating the percentile. type: boolean required: - type additionalProperties: false windowSettings: description: Controls the conversion window for the metric type: object properties: type: type: string enum: - none - conversion - lookback delayValue: description: >- Wait this long after experiment exposure before counting conversions. type: number delayUnit: type: string enum: - minutes - hours - days - weeks windowValue: type: number windowUnit: type: string enum: - minutes - hours - days - weeks required: - type additionalProperties: false priorSettings: description: Controls the bayesian prior for the metric type: object properties: override: description: >- If false, the organization default settings will be used instead of the other settings in this object type: boolean proper: description: >- If true, the `mean` and `stddev` will be used, otherwise we will use an improper flat prior. type: boolean mean: description: >- The mean of the prior distribution of relative effects in proportion terms (e.g. 0.01 is 1%) type: number stddev: description: >- Must be > 0. The standard deviation of the prior distribution of relative effects in proportion terms. type: number required: - override - proper - mean - stddev additionalProperties: false regressionAdjustmentSettings: description: Controls the regression adjustment (CUPED) settings for the metric type: object properties: override: description: If false, the organization default settings will be used type: boolean enabled: description: >- Controls whether or not regresion adjustment is applied to the metric type: boolean days: description: Number of pre-exposure days to use for the regression adjustment type: number required: - override additionalProperties: false riskThresholdSuccess: type: number riskThresholdDanger: type: number displayAsPercentage: description: >- If true and the metric is a ratio metric, variation means will be displayed as a percentage type: boolean minPercentChange: type: number maxPercentChange: type: number minSampleSize: type: number targetMDE: type: number managedBy: description: >- Where this fact metric must be managed from. If not set (empty string), it can be managed from anywhere. type: string enum: - '' - api - admin dateCreated: format: date-time type: string dateUpdated: format: date-time type: string archived: type: boolean metricAutoSlices: description: >- Array of slice column names that will be automatically included in metric analysis. This is an enterprise feature. type: array items: type: string required: - id - name - description - owner - projects - tags - datasource - metricType - numerator - inverse - cappingSettings - windowSettings - priorSettings - regressionAdjustmentSettings - riskThresholdSuccess - riskThresholdDanger - minPercentChange - maxPercentChange - minSampleSize - targetMDE - managedBy - dateCreated - dateUpdated 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 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 ``` ````