Skip to content
FlagSwiftDocs

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.read permission, which every built-in role has.
  • To archive from the Stale flags page, the flags.archive permission. Developers, release managers and admins have it.
  • Server evaluations reaching FlagSwift. See what is counted above.

Walk through it#

  1. 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.

  2. 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
    ItemDescription
    EvaluationsTotal server evaluations in the range.
    Served onThe share of evaluations that returned on.
    Flags evaluatedHow many flags had at least one evaluation. The Busiest flags table lists up to 50.
    Evaluations over timeHourly points for ranges up to 2 days, daily points beyond that.
    Why flags were servedThe evaluation reason behind each result.
    By environmentShown 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.
  3. 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.

  4. 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.
  5. 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
    ReasonDescription
    Not evaluatedNo server evaluation in the period.
    Fully rolled outOn at 100% in every environment, no kill switch active, and unchanged for the period. The code can drop the check.
    Off everywhereOff 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

Flags that a server SDK evaluates locally from the downloaded configuration are not counted. A flag used only that way can show no evaluations. Check code references before you remove it.

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).

Request
# 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"
Stale response (trimmed)
{
  "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

When counting began less than the chosen period ago, the Stale flags page says so (the API sets 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?
Close to it. Counts are buffered and written every 10 seconds, and pages cache results for 15 seconds. Several server instances add into the same hourly rows.
Does it record who was evaluated?
No. Only totals by flag, environment, hour, variant and reason are stored. For per-person results see outcome analytics.
Why does the Overview stale count differ from Stale flags?
The Overview always uses 14 days across all active projects. The Stale flags page uses the period and project you choose.
Can I get a 90 day view?
No. The pages and metrics API stop at 30 days, and data older than 30 days is deleted.

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.