GrowthBook Usage API

openapi: 3.2.0
info:
  version: 5.1.0
  title: GrowthBook REST Usage 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. Feature-flag and metric v1 routes are deprecated: they are tagged **LEGACY** in the sidebar and collapsed by default. Use the matching v2 group when both exist. ## 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, or less if the token''s permissions are limited. These can be created by going to `Personal Access Tokens` under your user menu. Members with the API Keys **Manage members'' tokens** permission can disable a member''s token under `Settings -> Manage PATs`, and admins can require new tokens to expire within a maximum lifetime. - **Secret Keys**: These are sensitive and provide the level of access of the role they are given, which can be any built-in or custom role, with optional per-project role overrides and environment limits. Managing Secret Keys on behalf of an organization takes the API Keys permissions. These can be created by going to `Settings -> API Keys`, where Admins can also require new Secret Keys to expire within a maximum lifetime. 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"

    ```


    If a key has an expiration date, every response includes it in the `X-GrowthBook-Key-Expires-At` header (ISO 8601), so scripts can warn before the key stops working. Requests made with an expired key fail with a `401` that says where to create a replacement. See Expiration for choosing a key''s expiration, the warnings before it lapses, and the organization policies. ## Naming who asked


    Requests made with a Secret Key may add an `X-GrowthBook-Requested-By` header naming the organization member who asked for the change, as a user id or an email address. History, revision logs and webhooks show that member next to the key. Each key''s settings under `Settings -> API Keys`:


    - **Header**: **Optional** (the default) uses the header when it''s sent, **Required** rejects requests without it, and **Rejected** rejects requests that send it, each with a 400. - **Permissions**, when a member is named:

    - **Assume member''s role** (the default): the request acts as that member, with only what both the key and the member can do, so the header can narrow a key but never widen it. Drafts, owners, `mine` filters and reviews are the member''s. The member''s rights over their own drafts, comments and verdicts apply only where the key''s own role allows the same action. - **Use key''s role**: the key acts as itself, with its own permissions, and the name is only recorded in history. Drafts, verdicts and ownership are the key''s, as when no member is named.'
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: Usage
  x-displayName: Usage
  description: Usage information for metrics in experiments.
paths:
  /v1/usage/metrics:
    get:
      operationId: getMetricUsage
      summary: Get metric usage across experiments
      description: 'Returns usage information for one or more legacy or fact metrics, showing which experiments use each metric

        and some usage statistics. If a metric is part of a metric group, then usage of that metric group counts as

        usage of all metrics in the group. Warning: only includes experiments that you have access to! If you do not have admin

        access or read access to experiments across all projects, this endpoint may not return the latest usage data across

        all experiments.'
      tags:
      - Usage
      parameters:
      - name: ids
        in: query
        required: true
        description: List of comma-separated metric IDs (both fact and legacy) to get usage for, e.g. ids=met_123,fact_456
        schema:
          description: List of comma-separated metric IDs (both fact and legacy) to get usage for, e.g. ids=met_123,fact_456
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  metricUsage:
                    type: array
                    items:
                      $ref: '#/components/schemas/MetricUsage'
                required:
                - metricUsage
                additionalProperties: false
      x-codeSamples:
      - lang: cURL
        source: "curl -X GET 'https://api.growthbook.io/api/v1/usage/metrics' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'"
components:
  schemas:
    MetricUsage:
      type: object
      properties:
        metricId:
          description: The metric ID
          type: string
        error:
          description: Set when the metric does not exist or the caller has no permission to read it.
          type: string
        experiments:
          description: List of experiments using this metric
          type: array
          items:
            type: object
            properties:
              experimentId:
                description: The experiment ID
                type: string
              experimentStatus:
                description: The current status of the experiment
                type: string
                enum:
                - draft
                - running
                - stopped
              lastSnapshotAttempt:
                description: The last time a snapshot was attempted for this experiment
                anyOf:
                - format: date-time
                  type: string
                - type: 'null'
            required:
            - experimentId
            - experimentStatus
            - lastSnapshotAttempt
            additionalProperties: false
        lastSnapshotAttempt:
          description: The most recent snapshot attempt across all experiments using this metric
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
      required:
      - metricId
      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
  - reports
  - sdk-connections
  - visual-changesets
  - saved-groups
  - saved-group-revisions
  - constants
  - constant-revisions
  - configs
  - config-revisions
  - releases
  - custom-hooks
  - organizations
  - members
  - code-references
  - archetypes
  - queries
  - settings
  - attributes
  - usage
  - meta
  - ContextualBandits
  - Dashboards
  - ContextualBanditQueries
  - CustomFields
  - MetricGroups
  - Teams
  - ExperimentTemplates
  - AnalyticsExplorations
  - RampScheduleTemplates
  - Learnings
  - Holdouts
  - AutoRuns
  - Populations
- name: Models
  tags:
  - AggregatedFactTable_model
  - AnalyticsExploration_model
  - Archetype_model
  - Attribute_model
  - AutoRun_model
  - CodeRef_model
  - Config_model
  - ConfigKeyUsage_model
  - ConfigLineage_model
  - ConfigReferences_model
  - ConfigRevision_model
  - ConfigRevisionActivityLogEntry_model
  - ConfigRevisionRef_model
  - ConfigRevisionReview_model
  - ConfigSchemaExport_model
  - ConfigSchemaSource_model
  - ConfigSchemaVerify_model
  - ConfigSchemaWarning_model
  - Confirmation_model
  - ConfirmationHeld_model
  - Constant_model
  - ConstantReferences_model
  - ConstantRevision_model
  - ConstantRevisionActivityLogEntry_model
  - ConstantRevisionRef_model
  - ConstantRevisionReview_model
  - ContextualBandit_model
  - ContextualBanditQuery_model
  - CustomField_model
  - CustomHook_model
  - Dashboard_model
  - DataSource_model
  - Dimension_model
  - Environment_model
  - EventUser_model
  - Experiment_model
  - Experiment Rule_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
  - FeatureBaseRule_model
  - FeatureContextualBanditRefRule_model
  - FeatureDefinition_model
  - FeatureEnvironmentV1_model
  - FeatureEnvironmentV2_model
  - FeatureExperimentRefRule_model
  - FeatureExperimentRule_model
  - FeatureForceRule_model
  - FeatureRevisionRef_model
  - FeatureRevisionSummary_model
  - FeatureRevisionV1_model
  - FeatureRevisionV2_model
  - FeatureRolloutRule_model
  - FeatureRuleV1_model
  - FeatureRuleV2_model
  - FeatureSafeRolloutRule_model
  - FeatureV1_model
  - FeatureV2_model
  - FeatureWithRevisionsV1_model
  - FeatureWithRevisionsV2_model
  - Holdout_model
  - InformationSchema_model
  - InformationSchemaTable_model
  - Learning_model
  - LookbackOverride_model
  - Member_model
  - Metric_model
  - MetricAnalysis_model
  - MetricGroup_model
  - MetricUsage_model
  - Namespace_model
  - NamespaceExperimentMember_model
  - Organization_model
  - PaginationFields_model
  - Population_model
  - Project_model
  - Query_model
  - RampSchedule_model
  - RampScheduleTemplate_model
  - Report_model
  - RequireReviewRule_model
  - RequireReviewRuleInput_model
  - RevisionIdRef_model
  - Safe Rollout Rule_model
  - SavedGroup_model
  - SavedGroupApprovalRule_model
  - SavedGroupReferenceResource_model
  - SavedGroupReferences_model
  - SavedGroupRevision_model
  - SavedGroupRevisionActivityLogEntry_model
  - SavedGroupRevisionRef_model
  - SavedGroupRevisionReview_model
  - ScheduleRule_model
  - ScheduledStopPlan_model
  - SdkConnection_model
  - Segment_model
  - Settings_model
  - Targeting Rule_model
  - TargetingReviewRule_model
  - Team_model
  - VisualChange_model
  - VisualChangeset_model
  - VisualEditorCbExperimentStub_model
x-provenance:
  method: harvested
  publisher: GrowthBook
  source: https://docs.growthbook.io/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)