See which flags are used
Find out how often each flag is evaluated, which ones nobody uses and which ones are ready to clean up.
- Time
- About 8 min
- Who can do it
- Anyone with metrics.read; archiving needs flags.archive
- Where
- Overview, Metrics, Reports and Stale flags
- You finish with
- A list of flags that are safe to retire
What and why#
Flags are cheap to add and easy to forget. A flag that has been on for everyone for months is no longer a decision, it is a branch in your code that someone must still read. FlagSwift counts how often every flag is evaluated, so you can see what is busy, what is idle and what is finished.
What is counted#
One count is added each time a server key calls GET /api/v1/evaluation/server in its default mode and a flag is evaluated. FlagSwift keeps only counts, grouped by project, environment, flag, hour, variant, evaluation reason and on or off. It never stores who was evaluated. Counts are buffered in memory and written about every 10 seconds, so a crash loses at most a few seconds.
What is not counted#
Flags a server SDK evaluates locally from the downloaded configuration (mode=config) never reach the server at the moment of the check, so they add nothing. Client SDKs evaluate through the server and are counted. Time before counting began shows as zero, and the pages say when counting started.
How long it is kept#
Hourly totals are kept for 30 days. The longest window any page offers is 30 days. Setting METRICS_ENABLED=false stops collection; pages keep showing what already exists.
Before you start#
- The
metrics.readpermission, which every built-in role has. - To archive from the Stale flags page, the
flags.archivepermission. Developers, release managers and admins have it. - Server evaluations reaching FlagSwift. See what is counted above.
Walk through it#
Start from the overview
Overview has an Analytics section with evaluations across all projects for the last 7 days, and a Needs attention card with five counts: alerts firing, releases awaiting approval, releases scheduled, stale flags and flags not evaluated in 14 days. It also lists the busiest projects.
See usage over time
Open Metrics and choose a project, an environment (or all of them) and a range of 24 hours, 7 days (the default) or 30 days. You see three tiles, then the chart and tables below.
What Metrics shows Item Description Evaluations Total server evaluations in the range. Served on The share of evaluations that returned on. Flags evaluated How many flags had at least one evaluation. The Busiest flags table lists up to 50. Evaluations over time Hourly points for ranges up to 2 days, daily points beyond that. Why flags were served The evaluation reason behind each result. By environment Shown when you have not picked an environment. You should see. The chart moves a few seconds after you evaluate a flag with a server key. Results are cached for 15 seconds, so wait a little before refreshing.Look at one flag
Open a flag from Flags and choose the Analytics tab. Each environment the flag is configured in gets a card with evaluations, served on, a variant split, reasons and when it was last seen. An environment with no traffic reads not evaluated.
Compare every flag in a table
Open Reports for Flag performance, with project, environment and range filters and a search box. Columns are Flag, Evaluations, Served on, Last evaluated, On in and Created, and the headers sort. The page shows the first 100 rows of the current sort. Export CSV downloads all rows that match your search, in the columns
flag, key, type, evaluations, served_on_percent, last_evaluated, on_in, created.Flag performance. Click a column header to sort. A flag with no evaluations shows not in this period, and a flag off everywhere gets an off everywhere badge. You should see. The third tile, Flags with no evaluations, counts active flags with zero evaluations in the range.Find flags to remove
Open Stale flags, choose a project, a period of 7, 14 (the default) or 30 days and optionally a reason. Only flags older than the period are listed, because newer ones have not had a fair chance. A person who can archive flags sees an Archive button on each row, which asks for confirmation and warns if the flag is still on somewhere. Archiving is reversible: a flag can be restored.
Stale flags. Hover a reason badge for its definition. The Archive button asks for confirmation and warns when the flag is still on somewhere. Why a flag is listed Reason Description Not evaluated No server evaluation in the period. Fully rolled out On at 100% in every environment, no kill switch active, and unchanged for the period. The code can drop the check. Off everywhere Off in every environment and unchanged for the period. A flag can have more than one reason. Older flags are listed first.
A flag can look unused when it is not
Do it with the API
These are dashboard API calls: they use your signed-in session cookie (see Automate with the HTTP API) and need metrics.read. days is a whole number from 1 to 30. The same family has /api/metrics/report (every active flag, up to 1,000), /api/metrics/summary (organization-wide, takes only days) and /api/flags/{id}/metrics (one flag, needs flags.read).
# Usage for a project over 14 days, Production only
curl -s -b jar.txt "https://flags.example.com/api/metrics?projectId=$PROJECT_ID&environment=production&days=14"
# Flags nobody evaluated for 30 days
curl -s -b jar.txt "https://flags.example.com/api/metrics/stale?projectId=$PROJECT_ID&days=30"{
"status": "success",
"data": {
"projectId": "prj_123",
"thresholdDays": 30,
"collectingSince": "2026-08-01T00:00:00.000Z",
"warmingUp": false,
"items": [{
"name": "new-checkout",
"displayName": "New checkout",
"reasons": ["unused", "fully_rolled_out"],
"enabledIn": ["production"],
"lastChangedAt": "2026-07-02T09:12:00.000Z"
}]
}
}Good to know#
Warming up
warmingUp to true). A flag shown as Not evaluated then may simply not have had time to be evaluated. Wait out a full period before archiving on that evidence alone.Is the evaluation count exact?
Does it record who was evaluated?
Why does the Overview stale count differ from Stale flags?
Can I get a 90 day view?
What to check#
- Counts are stored as hourly totals and kept for 30 days by default, so a window longer than the retention shows less than you expect.
- Before archiving, open the flag's Lifecycle tab for removal advice. See the Lifecycle page for the 14 and 30 day rules.
- Search the code for the flag key. If a server SDK evaluates it locally, zero evaluations means nothing.
- After archiving, the flag leaves the Stale flags list and the report on the next load.
If something goes wrong#
Metrics shows No evaluations recorded
Why: Nothing called the server evaluation endpoint with a server key in that range, the environment filter is wrong, or METRICS_ENABLED=false.
Fix: Evaluate a flag with a server key in default mode, choose All environments and check the setting.
A flag I use every day is listed as Not evaluated
Why: Your backend evaluates it locally from the downloaded configuration, which is not counted.
Fix: Do not archive on this evidence. Check code references instead.
The Archive button is missing
Why: Your role lacks flags.archive. Product managers, auditors and viewers do not have it.
Fix: Ask someone with a developer, release manager or admin role.
Export CSV is greyed out on Reports
Why: The table is still loading or no flag matches the filters.
Fix: Wait for the table, or clear the search. The file is named flag-report-<project>-<days>d.csv and has the columns flag, key, type, evaluations, served_on_percent, last_evaluated, on_in and created.
The API returns 400 about days
Why: days must be a whole number from 1 to 30.
Fix: Send an integer in that range, or leave it out for the default.
An archived flag still appears
Why: Results are cached for up to 15 seconds.
Fix: Reload the page after a moment.