> ## Documentation Index
> Fetch the complete documentation index at: https://docs.growthbook.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Update ramp monitoring configuration
> Replaces the monitoring configuration. Health-action thresholds (`srmAction`, `noTrafficAction`, etc.) can be updated at any time.
Once a linked SafeRollout has started, `datasourceId`, `exposureQueryId`, the metric IDs and the snapshot cadence are all locked — stop and recreate the schedule to change the data source.
Changes to guardrail or signal metric IDs take effect on the next analysis run.
## OpenAPI
````yaml openapi.yaml PUT /v1/ramp-schedules/{id}/monitoring
openapi: 3.1.0
info:
version: 5.1.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** - Unprocessable Entity - The request is valid, but a warning,
validation rule, approval requirement, or another publishing gate blocked
it. Do not assume that `ignoreWarnings` clears every 422 response.
- **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
### Publishing gates
Publish responses include a `gates` array that explains every blocker:
- `type`, `severity`, and `messages` identify the problem.
- `override` names the request-body field that can bypass it. This is
`ignoreWarnings` for warnings, `skipSchemaValidation` for schema and
invariant failures, or `skipHooks` for Custom Hook rejections. A value of
`null` means there is no request-body override.
- `requiresPermission` identifies any additional permission needed to use
the override.
- `resolution` provides an API action, method, and path when the blocker
must be resolved another way.
For example, an approval gate is cleared by approving the revision or by
using a caller with **Bypass draft approvals** access. A Config lock is
cleared through the unlock route in `resolution`.
When a successful publish bypasses a gate, the response includes
`bypassedGates`. Each entry reports the gate `type` and how it was bypassed
in `via`, which is one of `ignoreWarnings`, `skipSchemaValidation`,
`skipHooks`, `bypassApprovalPermission`, `restApiBypassesReviews`, or
`revertsBypassApproval` (reverts only). This field is omitted when no gates
were bypassed.
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 programmatically.
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 programmatically.
**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: constants
x-displayName: Constants
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Reusable named values referenced from feature flag values as `@const:key`
and resolved into the SDK payload at build time. String constants are
interpolated via `{{ @const:key }}`; JSON (object) constants are composed
via an `$extends` array. A constant's own keys **replace** what its
`$extends` bases provide, wholesale — constants are atomic building
blocks. (Config and feature values compose as deep, targeted patches
instead.)
- name: constant-revisions
x-displayName: Constant Revisions
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Draft revisions for constants, including pending changes, approvals, and
lifecycle (publish, discard, revert). Pass `version: "new"` on edit
endpoints to auto-create a draft.
- name: configs
x-displayName: Configs
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Reusable, typed, inheritable JSON objects referenced from feature flag
values as `@config:key`. A config carries a field `schema` (with
TypeScript/JSON Schema import-export) and a lineage `parent`. Inheritance
is expressed via `parent`, never an in-value `@config:` entry. Values
layer as a **deep, targeted patch**: a child (or a config-backed feature
value) restates only the leaves it changes and inherits the rest — unlike
a constant's `$extends`, whose own keys replace wholesale. Schema fields
colliding with a published ancestor's key follow 'base wins': identical
re-declarations are stripped with a warning, differing ones are rejected.
- name: config-revisions
x-displayName: Config Revisions
description: >-
**Beta** — these endpoints are new and may change in
backwards-incompatible ways.
Draft revisions for configs, including value and schema edits, schema
import (JSON Schema / TypeScript / inferred), approvals, and lifecycle
(publish, discard, revert). Publishing a schema change cascades the "base
wins" normalization to descendant configs; a publish that removes or
retypes fields descendants still use soft-blocks with a 422 unless the
request body sets `ignoreWarnings: true`. 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: custom-hooks
x-displayName: Custom Hooks
description: >-
Sandboxed JavaScript validation hooks that run when features, configs, or
their revisions are saved or published. Throwing an Error blocks the save;
`addWarning(msg)` raises a soft warning. Hooks are scoped by projects, or
pinned to a single feature/config via `entityType`/`entityId`; a
config-scoped hook also runs for every config inheriting from it (its
whole descendant lineage). Scope can be retargeted on update (or cleared
with nulls). Requires an enterprise plan; not available on GrowthBook
Cloud.
- 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: ContextualBandits
x-displayName: Contextual Bandits
description: ''
- name: Dashboards
x-displayName: Dashboards
description: ''
- name: ContextualBanditQueries
x-displayName: Contextual Bandit Queries
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: Learnings
x-displayName: Learnings
description: >-
Saved learnings captured across experiments, including AI-discovered
patterns.
- name: Holdouts
x-displayName: Holdouts
description: >-
Hold a share of traffic out of all experiments to measure their combined
effect.
- name: AutoRuns
x-displayName: Auto Runs
description: ''
- 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: AutoRun_model
x-displayName: Auto Run
description:
- name: CodeRef_model
x-displayName: Code Ref
description:
- name: Config_model
x-displayName: Config
description:
- name: ConfigKeyUsage_model
x-displayName: Config Key Usage
description:
- name: ConfigLineage_model
x-displayName: Config Lineage
description:
- name: ConfigReferences_model
x-displayName: Config References
description:
- name: ConfigRevision_model
x-displayName: Config Revision
description:
- name: ConfigRevisionActivityLogEntry_model
x-displayName: Config Revision Activity Log Entry
description: >-
- name: ConfigRevisionRef_model
x-displayName: Config Revision Ref
description:
- name: ConfigRevisionReview_model
x-displayName: Config Revision Review
description:
- name: ConfigSchemaExport_model
x-displayName: Config Schema Export
description:
- name: ConfigSchemaSource_model
x-displayName: Config Schema Source
description:
- name: ConfigSchemaVerify_model
x-displayName: Config Schema Verify
description:
- name: ConfigSchemaWarning_model
x-displayName: Config Schema Warning
description:
- name: Constant_model
x-displayName: Constant
description:
- name: ConstantReferences_model
x-displayName: Constant References
description:
- name: ConstantRevision_model
x-displayName: Constant Revision
description:
- name: ConstantRevisionActivityLogEntry_model
x-displayName: Constant Revision Activity Log Entry
description: >-
- name: ConstantRevisionRef_model
x-displayName: Constant Revision Ref
description:
- name: ConstantRevisionReview_model
x-displayName: Constant Revision Review
description: >-
- name: ContextualBandit_model
x-displayName: Contextual Bandit
description:
- name: ContextualBanditQuery_model
x-displayName: Contextual Bandit Query
description: >-
- name: CustomField_model
x-displayName: Custom Field
description:
- name: CustomHook_model
x-displayName: Custom Hook
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: FeatureContextualBanditRefRule_model
x-displayName: Feature Contextual Bandit Ref 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: FeatureRevisionRef_model
x-displayName: Feature Revision Ref
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: Holdout_model
x-displayName: Holdout
description:
- name: InformationSchema_model
x-displayName: Information Schema
description:
- name: InformationSchemaTable_model
x-displayName: Information Schema Table
description: >-
- name: Learning_model
x-displayName: Learning
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: RequireReviewRule_model
x-displayName: Require Review Rule
description:
- name: RequireReviewRuleInput_model
x-displayName: Require Review Rule Input
description: >-
- name: RevisionIdRef_model
x-displayName: Revision Id Ref
description:
- name: Safe Rollout Rule_model
x-displayName: Safe Rollout Rule
description:
- name: SavedGroup_model
x-displayName: Saved Group
description:
- name: SavedGroupApprovalRule_model
x-displayName: Saved Group Approval Rule
description: >-
- name: SavedGroupReferenceResource_model
x-displayName: Saved Group Reference Resource
description: >-
- name: SavedGroupReferences_model
x-displayName: Saved Group References
description:
- name: SavedGroupRevision_model
x-displayName: Saved Group Revision
description:
- name: SavedGroupRevisionActivityLogEntry_model
x-displayName: Saved Group Revision Activity Log Entry
description: >-
- name: SavedGroupRevisionRef_model
x-displayName: Saved Group Revision Ref
description: >-
- name: SavedGroupRevisionReview_model
x-displayName: Saved Group Revision Review
description: >-
- name: ScheduleRule_model
x-displayName: Schedule Rule
description:
- name: ScheduledStopPlan_model
x-displayName: Scheduled Stop Plan
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: TargetingReviewRule_model
x-displayName: Targeting Review 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/ramp-schedules/{id}/monitoring:
put:
tags:
- ramp-schedules
summary: Update ramp monitoring configuration
description: >
Replaces the monitoring configuration. Health-action thresholds
(`srmAction`, `noTrafficAction`, etc.) can be updated at any time.
Once a linked SafeRollout has started, `datasourceId`,
`exposureQueryId`, the metric IDs and the snapshot cadence are all
locked — stop and recreate the schedule to change the data source.
Changes to guardrail or signal metric IDs take effect on the next
analysis run.
operationId: updateRampScheduleMonitoring
parameters:
- name: id
in: path
required: true
description: ''
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
description: >-
Full replacement of the monitoring configuration. `datasourceId`
and `exposureQuery` cannot be changed while a monitoring
experiment is active — stop the schedule first.
type: object
properties:
datasourceId:
type: string
guardrailMetricIds:
minItems: 1
type: array
items:
type: string
signalMetricIds:
type: array
items:
type: string
updateScheduleMinutes:
anyOf:
- type: number
minimum: 10
- type: 'null'
monitoringMode:
type: string
enum:
- auto
- manual
autoUpdate:
type: boolean
srmAction:
type: string
enum:
- rollback
- hold
- warn
noTrafficAction:
type: string
enum:
- rollback
- hold
- warn
noTrafficGracePeriodHours:
description: >-
How long to wait for traffic before applying
`noTrafficAction`. Defaults to 24 hours when null or not
set.
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
multipleExposureAction:
type: string
enum:
- rollback
- hold
- warn
exposureQuery:
description: >-
The assignment query, grouping its ID with the identifier
type analyzed on. Mutually exclusive with the deprecated
`exposureQueryId`.
type: object
properties:
id:
description: The ID of one of the data source's assignment queries.
type: string
identifierType:
description: >-
The identifier type to analyze on, which the query must
declare. Required when selecting a different assignment
query that declares several. Otherwise defaults to the
current identifier type, or the query's only one. Null
is treated as omitted, so a response's value can be sent
back.
anyOf:
- type: string
- type: 'null'
required:
- id
additionalProperties: false
exposureQueryId:
deprecated: true
description: >-
Deprecated: use `exposureQuery`. Rejected when selecting a
different assignment query that declares several identifier
types; set `exposureQuery.identifierType` instead.
type: string
required:
- datasourceId
- guardrailMetricIds
additionalProperties: false
responses:
'200':
description: Resource updated
content:
application/json:
schema:
id: RampSchedule
type: object
properties:
id:
description: Unique identifier (rs_ prefix)
type: string
dateCreated:
format: date-time
type: string
dateUpdated:
format: date-time
type: string
name:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
targets:
description: Controlled entity references
type: array
items:
$ref: '#/components/schemas/targets'
startActions:
description: >-
Actions that restore controlled rules to their pre-ramp
state. Applied when rolling back or jumping to start, and
the base every step accumulates on; the only place a plan
can set hashAttribute, seed or hashVersion.
type: array
items:
$ref: '#/components/schemas/startActions'
steps:
description: Ordered ramp steps
type: array
items:
$ref: '#/components/schemas/steps'
endActions:
description: >-
Actions applied on top of all step patches when the ramp
completes. Represents the final desired rule state.
type: array
items:
$ref: '#/components/schemas/endActions'
startDate:
description: >-
When the ramp fires. Absent/null means immediately on
publish; set to a future datetime to delay start and keep
the rule disabled until that time.
anyOf:
- format: date-time
type: string
- type: 'null'
cutoffDate:
description: >-
Rule-level kill date. When reached, the ramp is completed
and the rule is disabled (enabled=false). Use for
time-boxed rules that must stop serving on a fixed date
regardless of ramp progress. Set to null to clear.
anyOf:
- format: date-time
type: string
- type: 'null'
requiresStartApproval:
description: >-
When true, the ramp holds at step -1 with its rule
disabled (zero traffic) until a human approves the start
via /actions/approve-step. Composes with startDate ('hold
until approved, then arm for that date').
type: boolean
startApprovedAt:
description: >-
When the current launch's start was approved. Cleared on
every return to step -1 (publish, rollback), re-arming the
approval gate.
anyOf:
- format: date-time
type: string
- type: 'null'
status:
type: string
enum:
- pending
- ready
- running
- paused
- completed
- rolled-back
currentStepIndex:
description: Index of current step; -1 = not yet started
type: integer
minimum: -1
startedAt:
anyOf:
- format: date-time
type: string
- type: 'null'
phaseStartedAt:
description: >-
Anchor for cumulative interval timing; resets after each
approval gate is satisfied
anyOf:
- format: date-time
type: string
- type: 'null'
pausedAt:
anyOf:
- format: date-time
type: string
- type: 'null'
nextStepAt:
description: >-
When the current step's time gate elapses; null for steps
with no interval (pure approval gates) and terminal states
anyOf:
- format: date-time
type: string
- type: 'null'
nextProcessAt:
anyOf:
- format: date-time
type: string
- type: 'null'
elapsedMs:
description: >-
Milliseconds since startedAt (computed at response time,
not stored)
anyOf:
- type: integer
- type: 'null'
lockdownConfig:
$ref: '#/components/schemas/lockdownConfig'
monitoringConfig:
anyOf:
- type: object
properties:
datasourceId:
type: string
guardrailMetricIds:
minItems: 1
type: array
items:
type: string
signalMetricIds:
type: array
items:
type: string
updateScheduleMinutes:
anyOf:
- type: number
minimum: 10
- type: 'null'
monitoringMode:
type: string
enum:
- auto
- manual
autoUpdate:
type: boolean
srmAction:
type: string
enum:
- rollback
- hold
- warn
noTrafficAction:
type: string
enum:
- rollback
- hold
- warn
noTrafficGracePeriodHours:
description: >-
How long to wait for traffic before applying
`noTrafficAction`. Defaults to 24 hours when null
or not set.
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
multipleExposureAction:
type: string
enum:
- rollback
- hold
- warn
exposureQuery:
description: >-
The assignment query, grouping its ID with the
identifier type analyzed on.
type: object
properties:
id:
description: >-
The ID of one of the data source's assignment
queries.
type: string
identifierType:
description: >-
The identifier type analyzed on. Null when
none can be resolved: no assignment query is
selected, or a record saved before identifier
types were stored points at a query that no
longer exists.
anyOf:
- type: string
- type: 'null'
required:
- id
- identifierType
additionalProperties: false
exposureQueryId:
description: 'Deprecated: use `exposureQuery`.'
deprecated: true
type: string
required:
- datasourceId
- guardrailMetricIds
- exposureQuery
- exposureQueryId
additionalProperties: false
- type: 'null'
experimentHealthAction:
type: string
enum:
- rollback
- hold
- warn
currentStepEnteredAt:
anyOf:
- format: date-time
type: string
- type: 'null'
stepApproval:
description: >-
Approval record for the current step. Valid only while
`stepApproval.stepIndex === currentStepIndex`.
anyOf:
- type: object
properties:
stepIndex:
description: Index of the step that was approved.
type: integer
approvedAt:
description: When the approval was granted.
type: string
format: date-time
approvedBy:
description: User ID of the approver.
type: string
context:
description: Surface through which the approval was granted.
type: string
enum:
- ui
- api
required:
- stepIndex
- approvedAt
- approvedBy
- context
additionalProperties: false
- type: 'null'
awaitingApproval:
description: >-
Computed at read time: whether a human approval is the
gate blocking the schedule right now — either the
start-approval gate (`requiresStartApproval` before step
0) or the current step's `holdConditions.requiresApproval`
once its time hold (if any) has elapsed. Paused schedules
report `false` (the pause is the blocking gate). For
monitored steps the approve-step endpoint may still reject
an approval until analysis-based gates clear.
type: boolean
monitoringStartDate:
description: >-
When the monitored section most recently started (first
monitored step entered). Used for no-traffic grace period
gating.
anyOf:
- format: date-time
type: string
- type: 'null'
lastRollbackAt:
anyOf:
- format: date-time
type: string
- type: 'null'
lastRollbackReason:
anyOf:
- type: string
- type: 'null'
monitoringStatus:
description: >-
Read-only monitoring status. Present when monitoringConfig
is set.
anyOf:
- type: object
properties:
safeRolloutId:
anyOf:
- type: string
- type: 'null'
monitoringMode:
description: >-
User-selected monitoring mode. `auto` schedules
snapshots automatically; `manual` requires
clicking Update.
type: string
enum:
- auto
- manual
autoUpdate:
description: >-
Legacy alias for auto-update behavior. Prefer
`monitoringMode` (`auto` means true, `manual`
means false).
type: boolean
effectiveAutoUpdate:
description: >-
Computed runtime flag. True only when monitoring
mode is auto and schedule state allows automatic
snapshot scheduling.
type: boolean
blockedReason:
description: >-
When `effectiveAutoUpdate` is false, this
describes the computed reason auto-updates are
currently blocked.
anyOf:
- type: string
- type: 'null'
nextSnapshotAt:
description: When the next automatic snapshot query will run
anyOf:
- format: date-time
type: string
- type: 'null'
currentStepMonitored:
description: >-
Whether the step at currentStepIndex has
monitoring enabled
type: boolean
required:
- monitoringMode
- autoUpdate
- effectiveAutoUpdate
- currentStepMonitored
additionalProperties: false
- type: 'null'
required:
- id
- dateCreated
- dateUpdated
- name
- entityType
- entityId
- targets
- steps
- status
- currentStepIndex
- nextStepAt
- awaitingApproval
additionalProperties: false
x-codeSamples:
- lang: cURL
source: >-
curl -X PUT
'https://api.growthbook.io/api/v1/ramp-schedules/{id}/monitoring' \
-H 'Authorization: Bearer YOUR_API_KEY'
components:
schemas:
targets:
type: object
properties:
id:
type: string
entityType:
type: string
enum:
- feature
entityId:
type: string
ruleId:
anyOf:
- type: string
- type: 'null'
environment:
deprecated: true
description: >-
Legacy disambiguator used alongside `ruleId` for pre-v2 ramps. May
be null on newer targets.
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- pending-join
- active
activatingRevisionVersion:
description: >-
Feature revision version that activates this ramp; cleared once
published
anyOf:
- type: integer
- type: 'null'
required:
- id
- entityType
- entityId
- status
additionalProperties: false
startActions:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored steps the rollout rule is
promoted to an experiment: treatment = [0, coverage), control =
[0.5, 0.5+coverage). Both arms are equal-sized and non-adjacent,
so a step-up only adds new users to each arm — no existing user
changes group. The REST API enforces coverage ≤ 0.5 on monitored
steps so control end never exceeds 1.0. The SDK uses explicit
hash ranges on bucketingV2 clients to keep bucketing stable
across monitored/unmonitored transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: >-
Value to serve, in the string form rule values use ("false",
"10", '{"limit": 5}'). A non-string JSON value is accepted and
stored as its JSON text. Must be valid for the feature's value
type.
enabled:
anyOf:
- type: boolean
- type: 'null'
hashAttribute:
description: >-
Attribute the rule buckets on. Required (here or on the rule)
when a step sets partial coverage on a force rule, which becomes
a rollout.
anyOf:
- type: string
- type: 'null'
seed:
description: Hash seed for a promoted force rule. Defaults to the rule id.
anyOf:
- type: string
- type: 'null'
hashVersion:
description: Hash algorithm version for a promoted force rule. Defaults to 2.
anyOf:
- anyOf:
- type: number
const: 1
- type: number
const: 2
- type: 'null'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
steps:
type: object
properties:
interval:
description: >-
Hold duration in seconds before this step's gates are evaluated.
null = no time gate (advance as soon as holdConditions clear).
anyOf:
- type: number
exclusiveMinimum: 0
- type: 'null'
approvalNotes:
anyOf:
- type: string
- type: 'null'
monitored:
description: >-
When true, this step runs A/B traffic analysis while active.
Treatment = [0, coverage), control = [0.5, 0.5+coverage). Arms are
equal-sized and non-adjacent: step-ups only add users, never
reassign existing ones. The UI caps monitored-step coverage at 0.5
so control end never exceeds 1.0. The SDK uses explicit hash ranges
on the experiment rule to prevent bucketing shifts across
monitored/unmonitored transitions.
type: boolean
holdConditions:
type: object
properties:
minSampleSize:
type: integer
exclusiveMinimum: 0
requiresApproval:
type: boolean
additionalProperties: false
actions:
type: array
items:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored steps the rollout
rule is promoted to an experiment: treatment = [0,
coverage), control = [0.5, 0.5+coverage). Both arms are
equal-sized and non-adjacent, so a step-up only adds new
users to each arm — no existing user changes group. The
REST API enforces coverage ≤ 0.5 on monitored steps so
control end never exceeds 1.0. The SDK uses explicit hash
ranges on bucketingV2 clients to keep bucketing stable
across monitored/unmonitored transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: >-
Value to serve, in the string form rule values use
("false", "10", '{"limit": 5}'). A non-string JSON value
is accepted and stored as its JSON text. Must be valid for
the feature's value type.
enabled:
anyOf:
- type: boolean
- type: 'null'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
required:
- interval
- actions
additionalProperties: false
endActions:
type: object
properties:
targetType:
type: string
const: feature-rule
targetId:
type: string
patch:
type: object
properties:
ruleId:
type: string
coverage:
description: >-
Traffic fraction (0–1). For monitored steps the rollout rule is
promoted to an experiment: treatment = [0, coverage), control =
[0.5, 0.5+coverage). Both arms are equal-sized and non-adjacent,
so a step-up only adds new users to each arm — no existing user
changes group. The REST API enforces coverage ≤ 0.5 on monitored
steps so control end never exceeds 1.0. The SDK uses explicit
hash ranges on bucketingV2 clients to keep bucketing stable
across monitored/unmonitored transitions.
anyOf:
- type: number
minimum: 0
maximum: 1
- type: 'null'
condition:
anyOf:
- type: string
- type: 'null'
savedGroups:
anyOf:
- type: array
items:
type: object
properties:
match:
type: string
enum:
- all
- none
- any
ids:
type: array
items:
type: string
required:
- match
- ids
additionalProperties: false
- type: 'null'
prerequisites:
anyOf:
- type: array
items:
type: object
properties:
id:
type: string
condition:
type: string
required:
- id
- condition
additionalProperties: false
- type: 'null'
allEnvironments:
anyOf:
- type: boolean
- type: 'null'
environments:
anyOf:
- type: array
items:
type: string
- type: 'null'
force:
description: >-
Value to serve, in the string form rule values use ("false",
"10", '{"limit": 5}'). A non-string JSON value is accepted and
stored as its JSON text. Must be valid for the feature's value
type.
enabled:
anyOf:
- type: boolean
- type: 'null'
required:
- ruleId
additionalProperties: false
required:
- targetType
- targetId
- patch
additionalProperties: false
lockdownConfig:
type: object
properties:
mode:
type: string
enum:
- none
- locked
required:
- mode
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
```
````