Safely deploy features with staged rollout plans, automatic safety checks, and instant rollback capabilities
Last updated November 21, 2026
Progressive Rollouts
Progressive rollouts let you deploy features gradually across your user base instead of flipping a flag for everyone at once. Define rollout plans with multiple stages, safety checks between each stage, and automatic rollback if things go wrong.
How Rollouts Work
A rollout plan controls the percentage of users who see a feature over time:
Draft → Start → 5% (canary) → 25% → 50% → 100% (complete)
↓ ↓ ↓
health check health check health check
Each stage runs for a configurable duration, and you can require health checks to pass before advancing to the next stage.
Rollout Plan Lifecycle
┌───────┐ start ┌────────┐ advance ┌───────────┐
│ Draft │ ──────────> │ Active │ ──────────> │ Completed │
└───────┘ └────────┘ └───────────┘
│ ▲
pause │ │ resume
▼ │
┌────────┐
│ Paused │
└────────┘
│
rollback │
▼
┌─────────────┐
│ Rolled Back │
└─────────────┘
| Status | Description |
|---|---|
draft | Plan created but not started. Stages can be edited. |
active | Rollout in progress. One stage is active at a time. |
paused | Temporarily halted. Can be resumed. |
completed | All stages finished. Feature is at 100%. |
rolled_back | Rollout was reversed. Feature returns to previous state. |
failed | The rollout engine stopped the plan after an error. |
cancelled | Stopped by a user; unfinished stages are skipped. |
Creating a Rollout Plan
Rollout plans belong to a project and are stored, so every server instance, the console's Releases view and the five-minute rollout tick see the same plan. The server assigns the plan id; the response (201) is the plan with status draft.
curl -X POST https://flaggr.dev/api/projects/proj-123/rollouts \
-H "Authorization: Bearer $FLAGGR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"flagKey": "checkout-v2",
"serviceId": "svc-web",
"environment": "production",
"name": "Checkout v2",
"strategy": { "type": "staged" },
"targetValue": true,
"stages": [
{ "id": "canary", "name": "Canary", "percentage": 5, "durationMinutes": 60, "autoAdvance": true },
{ "id": "half", "name": "Half", "percentage": 50, "durationMinutes": 720, "autoAdvance": false, "manualApproval": true },
{ "id": "all", "name": "Everyone", "percentage": 100, "durationMinutes": 1, "autoAdvance": true }
],
"safetyChecks": [
{ "type": "error_rate", "threshold": 0.02, "action": "rollback", "minSampleSize": 200 },
{ "type": "latency", "threshold": 250, "action": "pause" }
],
"rollbackPolicy": {
"automatic": true,
"rollbackTo": "fully_off",
"conditions": [{ "type": "error_rate", "threshold": 0.05, "action": "rollback" }]
}
}'| Field | Description |
|---|---|
flagKey, serviceId | The flag to roll out; the service must belong to the project |
environment | development, staging or production (default) |
name | Up to 200 characters |
strategy | staged; linear (startPercent, endPercent, durationMinutes); canary (canaryPercent, canaryDurationMinutes), which is what the canary API creates; or ring (rings: name, percentage, cohortId, duration) |
stages | At least one; see below |
targetValue | The value served to the rolled-out percentage |
safetyChecks | Optional guardrails checked while a stage runs |
rollbackPolicy | Optional: automatic, conditions, rollbackTo (previous_stage, fully_off, or specific_percentage with rollbackPercentage) and notifyChannels |
Stage Properties
| Property | Description |
|---|---|
id, name | Identifier (unique in the plan) and display name |
percentage | Share of traffic served targetValue, a whole number from 0 to 100 |
durationMinutes | Soak time before the stage can advance (at least 1) |
autoAdvance | Advance automatically once the soak ends and the guardrails pass (default true) |
manualApproval | Hold the stage until someone approves it with /advance |
cohortId | Ring strategy: the cohort this ring adds. Rings are cumulative, and a ring stage without a cohort opens to everyone. A cohort that can't be resolved reaches nobody; when none of the cohorts released so far resolves, the plan's rule matches nobody rather than everyone |
Safety Checks
| Field | Description |
|---|---|
type | error_rate (a fraction: 0.02 = 2%), latency (p99 in ms), traffic_ratio (0–1), custom_metric, manual, or a browser-analytics check: js_error_rate, lcp_p75, inp_p75, cls_p75, friction_rate or conversion_rate |
threshold | Breach threshold for the type |
action | pause, rollback or alert |
comparison | How threshold is compared: absolute (the canary's own value), delta (canary minus baseline) or relative (that difference as a fraction of the baseline: 0.2 = 20%). Defaults to delta for browser-analytics checks, absolute otherwise |
eventName | Required for conversion_rate: the conversion name that counts (the name of a flaggr:conversion event) |
minSampleSize | Sample a check needs before it counts: evaluations for error_rate and latency; sessions, page loads or interactions in each arm for browser-analytics checks. With fewer, the stage holds |
windowSeconds | Look-back window (60–604,800), never earlier than the stage start |
Starting, Advancing, Pausing and Cancelling
PLAN=https://flaggr.dev/api/projects/proj-123/rollouts/$PLAN_ID
curl -X POST "$PLAN/start" -H "Authorization: Bearer $FLAGGR_TOKEN"
curl -X POST "$PLAN/advance" -H "Authorization: Bearer $FLAGGR_TOKEN" -d '{}'
curl -X POST "$PLAN/pause" -H "Authorization: Bearer $FLAGGR_TOKEN"
curl -X POST "$PLAN/cancel" -H "Authorization: Bearer $FLAGGR_TOKEN"- start activates the first stage.
- Governance decides on Flaggr's own risk assessment of the start (the same engine as the dry run). A
riskAssessmentyou pass is only recorded alongside it and never changes a decision. When the policy blocks the start (409,requiresOverridesays whether an override is allowed), retry with{ "override": { "acknowledgePolicy": true, "reason": "…" } }where the policy allows it. - In an environment that requires approval, or for a risky production start the governance policy wants approved, start opens a change request and returns
202(code: "APPROVAL_REQUIRED"). The request is bound to the plan as it is at that moment: while it is pending, or approved but not yet applied, the draft can't be edited or deleted (409 PLAN_AWAITING_APPROVAL; withdraw it withDELETE /api/projects/{projectId}/change-requests/{requestId}, or Withdraw request on the plan's page in the console). Applying the approved request starts exactly the approved plan; a plan that changed since (or a request made before approvals were bound to content) is refused with409 PLAN_CHANGED_SINCE_APPROVAL, the request is retired, and you request approval again with start. Calling start again while that request is pending returns the same request. Once it is approved but not applied, start answers409 START_APPROVEDwithchangeRequestId: apply it (POST /api/projects/{projectId}/change-requests/{requestId}/apply) or withdraw it to change the plan. In the console an approved start shows Approved — apply, which applies it, and Withdraw request. A request past its 7-day expiry can only be withdrawn; applying one answers409 CHANGE_REQUEST_EXPIREDand retires it. Deleting the plan's service deletes the draft and retires its open start request; applying a start whose plan no longer exists answers410 PLAN_NOT_FOUNDand retires the request. Deleting the plan's flag leaves the draft, and applying its approved start then answers410 FLAG_NOT_FOUNDand retires the request; after creating the flag again, start the plan again to request a new approval. If the approval check itself fails the start answers503 APPROVAL_CHECK_UNAVAILABLEand nothing starts. On the shared demo, approval requests need a project membership (403). - Each flag and environment has at most one live (active or paused) plan, so a conflicting start fails with
400(code: "ROLLOUT_IN_PROGRESS"). Another change holding the plan's lock gives409 BUSY; a rule write that fails gives503 RULE_WRITE_FAILEDand leaves the plan a draft. - A plan won't start while an experiment runs or is paused on its flag (
409 EXPERIMENT_RUNNING, naming theexperiment). Experiments have no environment, and a running one serves its variants ahead of the plan's rule in every environment, on the evaluationshttps://flaggr.devserves with atargetingKey(the data plane behindhttps://api.flaggr.devand SDK-local evaluation don't assign experiments; see Where variants are assigned). End the experiment first. The check comes before any approval, so no change request is opened, and applying an approved start request is refused the same way (the request stays approved). The reverse holds too: experiments can't start or resume while a plan is live (409 ROLLOUT_IN_PROGRESS). - A plan won't start while a rule ahead of its rule serves everyone: no conditions or condition groups (or only the match-all condition), no schedule, and 100% or no percentage, including a rule an earlier plan left at 100% (
409 ROLLOUT_RULE_SHADOWED, with each rule'sremove_targeting_rulecall inrules[].remove). Its rule would reach nobody, and a pause or rollback would change nothing. Remove the rule, or give it conditions, a schedule or a percentage below 100. This check also comes before any approval, and applying an approved start is refused the same way (the request stays approved). A rule added ahead of a live plan's rule later isn't refused: the console marks the plan's rule unreachable. Stage and rollback percentages are whole numbers (400otherwise).
- Governance decides on Flaggr's own risk assessment of the start (the same engine as the dry run). A
- advance approves the current stage (
manualApproval) or advances early.{ "force": true }promotes before the soak ends or past a breached guardrail. Onlyactiveplans advance. - pause toggles: it pauses an
activeplan and resumes apausedone. - cancel stops an
activeorpausedplan: its rule is removed first, then the plan iscancelled. If the rule can't be removed the answer is503 RULE_WRITE_FAILEDand the plan stays live; retry.
PATCH /api/projects/{projectId}/rollouts/{planId} edits a draft (name, stages, safetyChecks, rollbackPolicy) unless its start is awaiting approval (409 PLAN_AWAITING_APPROVAL). DELETE removes any plan that isn't active or paused; cancel a running plan first. A failed, rolled-back or cancelled plan whose rule still serves can't be deleted (409 ROLLOUT_RULE_PRESENT, naming the rule): abort it (POST /api/flags/{key}/canary/abort with pipelineId) or remove the rule first. Deleting a plan never changes the flag. Creating a plan needs the flag to exist in that service and environment (404 FLAG_NOT_FOUND).
Plan routes need read (GET) or write access to the plan's service and environment, so member access overrides apply.
Guardrails and Automatic Rollback
Two things advance soaked stages and evaluate guardrails: the rollout tick (GET /api/cron/rollouts with Authorization: Bearer $CRON_SECRET, every five minutes) and reads of the plans (the plan list, a single plan, a canary's status).
A breached check acts as configured:
pausepauses the plan;rollbackrolls it back perrollbackPolicy.rollbackTo;alertnotifiesrollbackPolicy.notifyChannels.
Rollback, guardrail-pause and processing-failure alerts go to rollbackPolicy.notifyChannels (the console's Notify picker). error_rate and latency checks count only evaluations recorded by the Flaggr control plane; browser-analytics checks read browser analytics.
A guardrail rollback lowers the plan's rule before the plan is marked rolled_back, and never re-adds a rule that was removed. Editing a flag's targeting (console, PATCH /api/flags/{key}, bulk PATCH, MCP) never re-adds or changes a plan's rollout-<planId> rule, and never removes a live plan's rule (cancel the plan or abort the canary instead). A finished plan's leftover rule can be removed by deleting it from the targeting list (MCP: remove_targeting_rule). Such edits take the flag's rollout lock, so they can answer 409 BUSY; retry. If the engine hits an error (storage, connection, a rule write that didn't land), the plan stays active and the next run retries; the plan is marked failed (and its channels alerted) only after 3 failing runs in a row. The stage's tickFailures and lastTickError show what happened.
Version restorers never write over a live (active or paused) plan: rollback to a version (POST /api/flags/{key}/rollback/{version}) and RUM optimization answer 409 ROLLOUT_IN_PROGRESS, and site guardrail mitigation reports the flag as blocked — cancel the plan or let its guardrails act. The circuit breaker cancels the live plan instead. When no plan is live, a restore removes leftover rollout-<planId> rules of ended plans (listed in removedRolloutRuleIds). Deleting a flag a live plan manages is refused too (409 ROLLOUT_IN_PROGRESS).
Applying an approved change request follows the same rule. Flag updates, toggles and promotions are applied under the flag's rollout lock and refused with 409 ROLLOUT_IN_PROGRESS (BUSY when another change holds the lock) while a plan is live on the flag. The request stays approved; apply it once the plan finishes or is cancelled. Switching the flag off and editing only its name, description or tags still go through. A request never adds or reshapes a rollout-<planId> rule: rules the flag no longer carries are dropped, the flag's own keep their current share, and only one the requester saw and removed is taken out. Promotion, direct or approved, never copies the source environment's rollout-<planId> rules and keeps the target's own. A flag with a live plan in the target is refused (direct: listed in refused, 409 when nothing was promoted; approved request: 409, nothing applied). Deleting a service, or a tag cleanup, is refused or skipped while a live plan manages one of the flags it would delete.
Browser-analytics checks
Browser-analytics checks (JS error rate, LCP/INP/CLS p75, friction, conversion) compare canary and baseline sessions over the check's window: sessions whose events carry the plan's targetValue for the flag are the canary, sessions with any other value the baseline, and sessions that never carried the flag don't count. The value must be the target itself: a page that publishes an object flag by its variant name (as @flaggr/sdk 0.5.0 does when the evaluation has one), or a value the analytics script sends as a hash (a string, or an object's JSON, longer than 256 characters), puts its canary sessions in the baseline. The events come from browser analytics and SDK telemetry. js_error_rate needs error events, which the analytics script sends only with data-track-errors="true" (or errors turned on by the _flaggr_analytics flag). conversion_rate counts sessions with a flaggr:conversion event named eventName. friction_rate counts rage and dead clicks (ux_frustration events), which neither the analytics script nor @flaggr/sdk sends, so for your sites it reads 0 and never breaches. The checks read the events of the plan's service's Sites in the plan's environment, preferring Sites that link the flag. Only when the service has no Site there do they read the project's own telemetry (what the flaggrTelemetry() plugin sends, which names no Site).
Site IDs and flag keys are visible in page source, so three limits bound what one sender can do:
- Events the ingest marks untrusted are ignored: those sent from a page whose
Origin(orReferer, when there is noOrigin) isn't the Site's domain or one of its subdomains. Telemetry the SDK sends without a Site (theflaggrTelemetry()plugin) counts only when it comes from the domain of one of the project's Sites. Server-side SDK telemetry (noOrigin) never counts. - One client (a daily keyed hash of its IPv4 address or IPv6 /64) counts for at most 5 sessions per arm per window, its earliest.
- One session counts for at most 10 samples of each of LCP, INP and CLS, and 10 rage or dead clicks, per window (its latest).
The client hash changes at 00:00 UTC, so a window that crosses midnight can count a client twice. Events recorded before the ingest identified clients, or by an ingest without its client-hash secret, aren't subject to the per-client cap. These limits bound what one visitor or address can do; they don't stop a sender with many addresses. Register every domain that serves the snippet on a Site: events from other origins are stored, but analytics views leave them out by default and they never count toward guardrails. The plan analysis (GET .../analysis) reports what the filters dropped per arm in rumExcluded, and each check result on a stage carries the same in excluded.
A check whose window has no session in either arm is recorded as skipped (no RUM data for this service) and doesn't hold the stage. An arm whose counted sessions come from fewer than 3 clients counts as empty, so a lone sender can't decide a check; when that leaves both arms empty, the check is skipped (too few clients to measure). When the sessions dropped as untrusted outnumber the counted ones and came from at least 3 clients, the check holds the stage whatever the counted rest says: its reason says to check that the Site's domain matches where the script runs (for project-level SDK telemetry, to add a Site for the domain the SDK runs on). When only untrusted sessions from fewer clients are left, the check is skipped (no trusted RUM data). For these client counts, each session without a client hash counts as one client. If the analytics store can't be read, the check holds; without one (no Postgres), RUM checks are skipped.
Querying Rollouts
curl https://flaggr.dev/api/projects/proj-123/rollouts -H "Authorization: Bearer $FLAGGR_TOKEN"
curl https://flaggr.dev/api/projects/proj-123/rollouts/$PLAN_ID -H "Authorization: Bearer $FLAGGR_TOKEN"
curl https://flaggr.dev/api/projects/proj-123/rollouts/$PLAN_ID/analysis -H "Authorization: Bearer $FLAGGR_TOKEN"The list holds every plan you can read; filter by flagKey on the client.
GET /api/projects/{projectId}/rollouts/summary?days=7returns release KPIs: auto-advanced stages, guardrail breaches and mean time to rollback.GET /api/projects/{projectId}/rollouts/audience?flagKey=&serviceId=&environment=&days=7estimates per-stage users from browser analytics.
Canary API
POST /api/flags/{key}/canary (MCP: start_canary_rollout) is a shortcut that creates and starts a rollout plan with the canary strategy. The plan is stored and ticked like any other: by the cron every 5 minutes, and whenever the flag's canary status or the project's plans are read. It shows under Releases in the console.
| Request field | Becomes |
|---|---|
initialRolloutPercent, targetRolloutPercent, rampStepPercent, soakPeriodMinutes | Stages at initial, initial + step, … up to target (max 20 stages); every stage soaks soakPeriodMinutes. The percentages are whole numbers from 1 to 100 |
stages[] (name, rolloutPercentage, soakMinutes) | Explicit stages instead of the ramp (whole-number percentages from 1 to 100 that increase; each soaks at least 1 minute) |
errorRateGateDelta / guardrails.maxErrorRateDelta (default 0.02) | error_rate check at the flag's error rate over the hour before the canary + delta, never below 2% |
latencyGateDeltaMs / guardrails.maxLatencyDeltaMs (default 100) | latency check (pauses) at the pre-canary evaluation p99 + delta, never below 100 ms |
minTrafficRatio / guardrails.minTrafficRatio (default 0.7; 0 turns it off) | traffic_ratio hold |
minSampleSize (default 200) | Evaluations each check needs in the stage window before it counts; below it the stage holds |
autoRollbackOnBreach (default true) | An error-rate breach removes the canary rule and marks the plan rolled_back; false pauses instead |
autoAdvance (default true) | Stages advance on their own once soaked and healthy; false waits for /advance |
targetValue | The value the canary serves: default true for boolean flags, required for string, number and object flags |
notifyChannels | Alert channels for breaches and aborts (default: the project's enabled channels) |
override (acknowledgePolicy, reason) | Acknowledges a rollout-governance block that allows an override |
The canary adds one rule, rollout-<planId>, after the flag's own rules. Aborting cancels the plan and removes that rule, so the flag serves what it did before the canary; edits made to the flag during the canary are kept, and baselineRestored says whether the serving config matches the pre-canary snapshot. Aborting a failed or rolled-back canary whose rule still serves removes the rule.
A flag has at most one live plan per environment, so a canary or plan on a flag that already has one is refused. Canaries are also refused for disabled flags, for a value the flag already serves by default or through a rule for everyone (409 NO_CHANGE), while rules from earlier plans remain, while a rule ahead serves everyone (409 ROLLOUT_RULE_SHADOWED), and in protected environments or projects whose rollout governance requires approval. In those cases use a rollout plan (start_rollout_plan), which opens the change request. While an experiment runs or is paused on the flag, a canary is refused with 409 EXPERIMENT_RUNNING and leaves no draft plan behind.
The gates measure evaluations served by flaggr.dev only, blended over canary and baseline traffic. Evaluations on api.flaggr.dev and SDK-local evaluation aren't recorded, so a canary of a flag evaluated there holds at each soaked stage until it is advanced with force. See Canary Rollouts in the REST reference for the request and response shapes and error codes.
API Reference
| Endpoint | Method | Description |
|---|---|---|
/api/projects/{projectId}/rollouts | GET | List plans |
/api/projects/{projectId}/rollouts | POST | Create a plan (draft) |
/api/projects/{projectId}/rollouts/{planId} | GET, PATCH, DELETE | Read, edit a draft, delete |
/api/projects/{projectId}/rollouts/{planId}/start | POST | Start |
/api/projects/{projectId}/rollouts/{planId}/advance | POST | Approve or advance a stage (force optional) |
/api/projects/{projectId}/rollouts/{planId}/pause | POST | Pause or resume |
/api/projects/{projectId}/rollouts/{planId}/cancel | POST | Cancel |
/api/projects/{projectId}/rollouts/{planId}/analysis | GET | Guardrail analysis |
/api/projects/{projectId}/rollouts/summary | GET | Release KPIs |
/api/projects/{projectId}/rollouts/audience | GET | Audience estimate |
/api/projects/{projectId}/change-requests/{requestId} | PATCH, DELETE | Approve or reject a start request; withdraw it |
/api/projects/{projectId}/change-requests/{requestId}/apply | POST | Start the approved plan |
/api/flags/{key}/canary | POST, GET | Start a canary; canary status |
/api/flags/{key}/canary/advance | POST | Advance the live canary |
/api/flags/{key}/canary/abort | POST | Abort the live canary |
Legacy /api/rollouts (retired)
/api/rollouts, /api/rollouts/{id} and its /assessment routes return 410 Gone, with the successor in replacement. Their plans lived in one server instance's memory and never included console plans.
Best Practices
- Always start with a canary stage (1–5%) to catch issues early
- Set safety checks for error rate, latency, and business metrics
- Use
autoAdvance: falsefor production-critical features — require manual approval - Monitor between stages — don't rush through stages even if metrics look good
- Keep rollback reasons descriptive — they're recorded in the event audit log
- One flag, one rollout — a second live rollout plan or canary on the same flag and environment is refused; cancel or finish the first one
Related
- Targeting Rules — Conditions, operators, and gradual rollouts
- Cohorts — Audience segmentation for targeted rollouts
- Overrides & Prerequisites — Identity overrides and flag dependencies
- Flag Health — Health monitoring and auto-remediation