Skip to main content

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 │
                     └─────────────┘
StatusDescription
draftPlan created but not started. Stages can be edited.
activeRollout in progress. One stage is active at a time.
pausedTemporarily halted. Can be resumed.
completedAll stages finished. Feature is at 100%.
rolled_backRollout was reversed. Feature returns to previous state.
failedThe rollout engine stopped the plan after an error.
cancelledStopped 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" }]
    }
  }'
FieldDescription
flagKey, serviceIdThe flag to roll out; the service must belong to the project
environmentdevelopment, staging or production (default)
nameUp to 200 characters
strategystaged; linear (startPercent, endPercent, durationMinutes); canary (canaryPercent, canaryDurationMinutes), which is what the canary API creates; or ring (rings: name, percentage, cohortId, duration)
stagesAt least one; see below
targetValueThe value served to the rolled-out percentage
safetyChecksOptional guardrails checked while a stage runs
rollbackPolicyOptional: automatic, conditions, rollbackTo (previous_stage, fully_off, or specific_percentage with rollbackPercentage) and notifyChannels

Stage Properties

PropertyDescription
id, nameIdentifier (unique in the plan) and display name
percentageShare of traffic served targetValue, a whole number from 0 to 100
durationMinutesSoak time before the stage can advance (at least 1)
autoAdvanceAdvance automatically once the soak ends and the guardrails pass (default true)
manualApprovalHold the stage until someone approves it with /advance
cohortIdRing 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

FieldDescription
typeerror_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
thresholdBreach threshold for the type
actionpause, rollback or alert
comparisonHow 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
eventNameRequired for conversion_rate: the conversion name that counts (the name of a flaggr:conversion event)
minSampleSizeSample 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
windowSecondsLook-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 riskAssessment you pass is only recorded alongside it and never changes a decision. When the policy blocks the start (409, requiresOverride says 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 with DELETE /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 with 409 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 answers 409 START_APPROVED with changeRequestId: 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 answers 409 CHANGE_REQUEST_EXPIRED and retires it. Deleting the plan's service deletes the draft and retires its open start request; applying a start whose plan no longer exists answers 410 PLAN_NOT_FOUND and retires the request. Deleting the plan's flag leaves the draft, and applying its approved start then answers 410 FLAG_NOT_FOUND and 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 answers 503 APPROVAL_CHECK_UNAVAILABLE and 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 gives 409 BUSY; a rule write that fails gives 503 RULE_WRITE_FAILED and leaves the plan a draft.
    • A plan won't start while an experiment runs or is paused on its flag (409 EXPERIMENT_RUNNING, naming the experiment). Experiments have no environment, and a running one serves its variants ahead of the plan's rule in every environment, on the evaluations https://flaggr.dev serves with a targetingKey (the data plane behind https://api.flaggr.dev and 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's remove_targeting_rule call in rules[].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 (400 otherwise).
  • advance approves the current stage (manualApproval) or advances early. { "force": true } promotes before the soak ends or past a breached guardrail. Only active plans advance.
  • pause toggles: it pauses an active plan and resumes a paused one.
  • cancel stops an active or paused plan: its rule is removed first, then the plan is cancelled. If the rule can't be removed the answer is 503 RULE_WRITE_FAILED and 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:

  • pause pauses the plan;
  • rollback rolls it back per rollbackPolicy.rollbackTo;
  • alert notifies rollbackPolicy.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 (or Referer, when there is no Origin) isn't the Site's domain or one of its subdomains. Telemetry the SDK sends without a Site (the flaggrTelemetry() plugin) counts only when it comes from the domain of one of the project's Sites. Server-side SDK telemetry (no Origin) 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=7 returns release KPIs: auto-advanced stages, guardrail breaches and mean time to rollback.
  • GET /api/projects/{projectId}/rollouts/audience?flagKey=&serviceId=&environment=&days=7 estimates 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 fieldBecomes
initialRolloutPercent, targetRolloutPercent, rampStepPercent, soakPeriodMinutesStages 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
targetValueThe value the canary serves: default true for boolean flags, required for string, number and object flags
notifyChannelsAlert 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

EndpointMethodDescription
/api/projects/{projectId}/rolloutsGETList plans
/api/projects/{projectId}/rolloutsPOSTCreate a plan (draft)
/api/projects/{projectId}/rollouts/{planId}GET, PATCH, DELETERead, edit a draft, delete
/api/projects/{projectId}/rollouts/{planId}/startPOSTStart
/api/projects/{projectId}/rollouts/{planId}/advancePOSTApprove or advance a stage (force optional)
/api/projects/{projectId}/rollouts/{planId}/pausePOSTPause or resume
/api/projects/{projectId}/rollouts/{planId}/cancelPOSTCancel
/api/projects/{projectId}/rollouts/{planId}/analysisGETGuardrail analysis
/api/projects/{projectId}/rollouts/summaryGETRelease KPIs
/api/projects/{projectId}/rollouts/audienceGETAudience estimate
/api/projects/{projectId}/change-requests/{requestId}PATCH, DELETEApprove or reject a start request; withdraw it
/api/projects/{projectId}/change-requests/{requestId}/applyPOSTStart the approved plan
/api/flags/{key}/canaryPOST, GETStart a canary; canary status
/api/flags/{key}/canary/advancePOSTAdvance the live canary
/api/flags/{key}/canary/abortPOSTAbort 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: false for 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