Review history, compare versions and roll back
See who changed a flag and when, read the saved versions of an environment, and go back to a good one without losing anything.
- Time
- About 8 min
- Who can do it
- Anyone who can read flags can view history. Rolling back needs rollouts.rollback: Developers and Release managers (not Developers in production) and Admins.
- Where
- Flags > your flag > History & rollback
- You finish with
- An earlier configuration restored as a new version
What and why#
What it is#
Every time a flag's configuration in an environment changes, FlagSwift saves it as a numbered version: on or off, rollout percentage, lists, rules, segments and the rest. Versions belong to one environment, so a change in Staging never appears in Production's list. Alongside the versions, the Activity list records each change with the person's email.
When to use it#
- A change made things worse and you want the previous configuration back immediately.
- You need to find who changed a flag, when, and from what to what.
- You want evidence for a review: export the history as CSV or JSON.
How it works#
A rollback never rewrites history. It applies the old configuration as a new version, so version 9 can restore version 6 and you can roll back again, even to version 8. It takes effect as soon as the change reaches your SDKs, which is at once for streaming and on the next poll otherwise.
Before you start#
- Anyone who can read the flag (
flags.read) can open its history. Rolling back needsrollouts.rollbackin that environment. Release managers and Admins have it everywhere. Developers have it outside production only, and Product managers do not have it. - The flag and its project must not be archived. Archived flags cannot be rolled back until restored.
- The kill switch must not be active in the environment. See Handle an incident with the kill switch.
Walk through it#
Open the history
Open Flags, choose the flag and open the History & rollback tab.
Read the versions
The Roll back panel lists the saved versions of the environment you pick in Environment to roll back, newest first, in pages. Each row shows:
A version row Item Description v7 The version number. It rises with every change. Current A badge on the version the environment is at now. on / off and a percentage Whether the flag was on and its rollout percentage in that version. Kill switch A badge on a version saved while the emergency stop was active. It has no Restore button. Who and when The person who saved it, how long ago, and for a rollback the version it restored and the reason. The Roll back panel for Production. The Current version and any version saved under the kill switch have no Restore button. There is no side-by-side comparison
The console does not show a diff. To compare two versions, read their rows, and read the Activity list below, which shows each change as a before and after value.Find who did what
Activity lists every change to the flag across environments, newest first, in pages. Each entry has a label and the person's email:
- Toggled, Rollout changed, Targeting updated, Variants updated and Variant allocation changed, with a before and after such as
off → onor10% → 25%. - Rolled back, such as
v8 → v9 (restored v6)followed by the reason. - Kill switch, such as
activated: Checkout errors spiking. - Created, Archived, Restored and Moved project, which belong to the flag and not an environment.
Choose CSV or JSON above the list to download the full history, up to 10,000 entries.
- Toggled, Rollout changed, Targeting updated, Variants updated and Variant allocation changed, with a before and after such as
Roll back
Choose the environment, then either select Roll back to previous or select Restore on a version. A dialog titled Confirm rollback asks you to confirm and has an optional Reason (optional) box. The reason is kept in the audit log and can be up to 300 characters. Choose Roll back to apply it.
The confirmation dialog for restoring version 7 in Production, and the same dialog while the rollback is applied. It cannot be dismissed until it finishes. You should see. A new version appears at the top of the list marked Current, and Activity shows Rolled back with your email and the versions, such asv8 → v9 (restored v6).Roll back to previous does not simply pick the last number. It returns to the most recent earlier version that serves differently from now and was not saved under the kill switch, looking back over the last 50 versions.
What a rollback restores#
- It puts back on or off, the rollout percentage, targeting lists, rules, segments, Roll out by, prerequisites, default value and variant allocation.
- It never restores the emergency stop. A rollback is refused while the kill switch is active, and versions saved under the kill switch cannot be restored.
- It does not change the flag's variants themselves. A version is refused if the flag has variants that have changed since, and it asks you to pick a later version.
- Segments that were deleted since are left out. A version that needs a prerequisite flag that is no longer active is refused, because dropping it would serve the flag without its safeguard.
Approval does not hold up a rollback
Do it with the API#
There are two routes. The Dashboard endpoints authenticate with your signed-in session cookie (auth_session). Automation uses an admin API key with the rollouts:write scope and addresses the flag by its key.
Dashboard API: list versions, then roll back
Versions need flags.read, and environment is required. Rollback needs rollouts.rollback. version is optional and reason is up to 300 characters. A successful rollback returns the updated flag.
# Saved versions of one environment, newest first
curl -s "https://flags.example.com/api/flags/$FLAG_ID/versions?environment=production&limit=5" \
-b "auth_session=$SESSION"
# Restore version 6 (leave version out to return to the previous one)
curl -s -X POST "https://flags.example.com/api/flags/$FLAG_ID/rollback" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{"environment":"production","version":6,"reason":"error rate spike"}'{
"status": "success",
"message": "OK",
"data": {
"current": 8,
"items": [
{
"id": "6650f4c5d6e7f8a9b0c1d2e3",
"version": 8,
"action": "rollout",
"config": { "enabled": true, "rolloutPercentage": 50, "targeting": { "enabled": false, "users": [] }, "killSwitchActive": false },
"restoredFrom": null,
"reason": null,
"actorEmail": "dev@example.com",
"createdAt": "2026-10-03T09:30:00.000Z"
}
],
"pagination": { "page": 1, "limit": 5, "total": 8, "totalPages": 2, "hasNext": true, "hasPrev": false }
}
}Evaluation API: roll back with an admin key
Needs an admin key with the rollouts:write scope, and the key can never do more than the person who made it. The change is recorded under the key's name. Choose a target first with GET /api/v1/flags/new-dashboard/environments/production/versions, which takes a server or admin key with flags:read. See the Evaluation API and the Rollouts API.
curl -s -X POST "https://flags.example.com/api/v1/flags/new-dashboard/environments/production/rollback" \
-H "Authorization: Bearer $FLAGSWIFT_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"version":6,"reason":"error rate spike after release"}'{
"flag": "new-dashboard",
"environment": "production",
"version": 9,
"enabled": true,
"rolloutPercentage": 5
}What to check#
- A new version appears at the top of the list and is marked Current.
- Activity shows Rolled back with the person and the versions, such as
v8 → v9 (restored v6). - The inspector gives the result you expected for a sample identifier. See Find out why someone got a result.
If something goes wrong#
Cannot roll back while the kill switch is active
Why: A rollback never restores the emergency stop, and is refused while it is on in the environment.
Fix: Lift the kill switch first from the Flags page, then roll back.
There is no earlier version to roll back to
Why: Every earlier version in the last 50 serves the same as now, or was saved under the kill switch.
Fix: Pick a specific version with Restore, or change the configuration by hand.
The flag is already at this version
Why: You chose the Current version.
Fix: Pick an earlier one.
That version uses variants that have since changed. Pick a later version.
Why: The flag's variants were edited after that version was saved, so its weights no longer fit.
Fix: Restore a later version, or set the allocation by hand in the Variants tab.
That version depends on flags that are no longer active here
Why: The version has prerequisites that were archived or removed.
Fix: Restore a version without them, or bring the prerequisite flags back.
There is no Restore button on a version
Why: It is the current version or was saved while the kill switch was active.
Fix: Restore a different version.
Reason must be 300 characters or less
Why: The reason box in the dialog accepts more text than the server keeps, so a long reason is refused when you confirm.
Fix: Shorten the reason to 300 characters and confirm again.
Forbidden for a Developer in production
Why: Developers do not have rollback rights in a production environment.
Fix: Ask a Release manager or an Admin.
Good to know#
Give every rollback a reason