Skip to content
FlagSwiftDocs

Find out why someone got a result

When a person gets a result you did not expect, run the real evaluation for them and read the reason it returns.

Time
About 6 min
Who can do it
Anyone who can read flags (flags.read). Every built-in role can.
Where
Flags > your flag > Targeting & rollout > Check who gets this flag
You finish with
The result, its reason code and the numbers behind it

What and why#

What it is#

The inspector runs the same evaluation engine your SDKs use, for one person and one environment, against the settings you have saved. It changes nothing, records no event and does not count as an evaluation in your metrics. The answer is a result (Served or Not served), the variant if the flag has variants, and a reason that names the step that decided.

When to use it#

  • A customer says they cannot see a feature, or that a colleague sees it and they do not.
  • You just added a list, segment or rule and want to prove it works before telling anyone.
  • You are partway through a rollout and want to know whether a given person is inside the percentage.

How it works#

The engine checks, in order: the kill switch, whether the flag is on, the always-on lists, segments, attribute rules, prerequisites and finally the rollout percentage. The first step that decides gives the reason. For a rollout it also shows the person's bucket, a number from 0 to 9,999 that never changes for that identifier and flag, against the cutoff (the percentage times 100).

Before you start#

  • Permission to read flags (flags.read). Checking a person changes nothing, so every role can do it, auditors and viewers included.
  • At least one identifier for the person: a user, an account or a device. Each can be up to 255 characters.
  • The environment you are asking about. The same flag can differ between environments.
  • Your latest edits saved. The inspector reads saved settings, not what is on screen.

Walk through it#

  1. Open the inspector

    Open Flags, choose the flag and open the Targeting & rollout tab. Select the environment at the top, then scroll to Check who gets this flag. It is open by default.

  2. Enter who to check

    Fill in User (placeholder User ID or email), Account, Device, or any combination, and choose Check. The button stays off until you enter at least one. Use the same strings your app sends, with the same capitals and no stray spaces.

  3. Read the answer

    You see a row of facts. Read them left to right:

    Three people checked against the same saved settings. Each result row reads the same way: the outcome, the variant if the flag has one, the reason, then the bucket against the cutoff.
    What the result row shows
    ItemDescription
    Served / Not servedWhether the flag is on for this person.
    Variant badgeFor a flag with variants, the variant this person gets. Not served shows the off variant.
    ReasonThe step that decided. See the table below.
    segment: …Shown when a segment granted the flag. It names the first selected segment the person is in.
    bucket N of M (kind)Shown when the person has an identifier of the kind the rollout counts by. They are inside the rollout when N is below M, for example bucket 312 of 500 (user). M is the percentage times 100.
    You should see. For a listed person: Served and TARGETED_USER. For a person outside a 5 percent rollout: Not served, ROLLOUT_OUT and a bucket above 500.
  4. Include attributes when rules matter

    The console box takes identifiers only. To test an attribute rule against real values, use Test these rules in the Rules step, which tells you which rule matches and ticks each condition, or call the inspect endpoint below, which also accepts attributes.

  5. Compare with what your app saw

    If the inspector and your app disagree, work through the list under What to check. The server evaluation endpoint returns the same reasons when you pass explain=true, so you can compare like with like.

Reading the reason#

Reasons, in the order they are checked
ReasonDescription
KILL_SWITCHAn emergency stop is active. Everyone gets the off result.
DISABLEDThe flag is switched off in this environment. Targeting does not override it.
TARGETED_USERThe person, account or device is in the always-on lists and that toggle is on.
SEGMENT_MATCHA segment selected for this environment includes the person.
RULE_MATCHAn attribute rule matched.
DEPENDENCY_BLOCKEDA prerequisite flag is not on for this person, so the rollout was skipped. People matched by the three steps above are never held back.
FULL_ROLLOUTThe rollout is at 100 percent.
ROLLOUT_INThe person is inside the percentage. Served.
ROLLOUT_OUTThe person is outside the percentage, or the percentage is 0.
NO_IDENTIFIERThe flag rolls out by an identifier you did not enter. Only the first identifier of the chosen kind is counted.
ENV_NOT_CONFIGURED / FLAG_NOT_FOUNDThe flag has no configuration for the environment, or no flag has that key. These come from the Evaluation API, not the inspector.

Stickiness explained

The bucket does not depend on the environment, only on the identifier and the flag key. A person keeps the same bucket when you raise the percentage or promote a rollout, which is why a person is never taken out of a rollout you widen.

Do it with the API#

Inspect a person (Dashboard API)

This is a Dashboard endpoint, so it authenticates with your signed-in session cookie (auth_session), not an API key, and needs flags.read. Send at least one of identifier, account or device. attributes must be a JSON object. inRollout, targeted and ruleMatched show what each step would say on its own, whatever finally decided.

Request
curl -s -X POST "https://flags.example.com/api/flags/$FLAG_ID/environments/production/inspect" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"user-123","account":"acme","attributes":{"plan":"pro"}}'
200 OK
{
  "status": "success",
  "message": "OK",
  "data": {
    "enabled": true,
    "reason": "ROLLOUT_IN",
    "bucketBy": "user",
    "matchedSegment": null,
    "bucket": 312,
    "cutoff": 500,
    "rolloutPercentage": 5,
    "inRollout": true,
    "targeted": false,
    "ruleMatched": false,
    "variantBucket": null
  }
}

Ask the Evaluation API for reasons

This is the Evaluation API, which authenticates with a server or admin key in the Authorization header. It evaluates every flag for the person. Without explain=true the reasons are left out. Keep this call on your backend: it returns more than a browser should see. See the Evaluation API.

Request
curl -s -G "https://flags.example.com/api/v1/evaluation/server" \
  -H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY" \
  --data-urlencode "env=production" \
  --data-urlencode "user_identifier=user-123" \
  --data-urlencode 'user_attributes={"plan":"pro"}' \
  --data-urlencode "explain=true"
200 OK
{
  "environment": "production",
  "hashVersion": 1,
  "version": "f1c2",
  "flags": {
    "new-dashboard": { "enabled": true, "reason": "ROLLOUT_IN", "version": 7 },
    "checkout-layout": { "enabled": false, "variant": "classic", "value": "classic", "reason": "ROLLOUT_OUT", "version": 3 }
  }
}

What to check#

  • The environment in the inspector is the one your key points at.
  • The identifier you entered is the same string your app sends, including case.
  • You saved your edits before checking.
  • If the inspector and your app disagree, look for a different environment, an SDK still serving a cached configuration, or an app that omits the attribute or identifier.

If something goes wrong#

The Check button is greyed out

Why: Nothing has been entered in User, Account or Device.

Fix: Enter at least one identifier.

Enter a user, account or device to check (400 from the API)

Why: The inspect request had none of identifier, account or device.

Fix: Add at least one. Each is at most 255 characters.

The inspector says Served but my app gets the off value

Why: The app is in another environment, uses a different identifier string, does not send the attribute, or still holds an older configuration.

Fix: Compare with explain=true on the server endpoint using the app's exact values, and check how fresh the SDK's configuration is. See Get changes in real time with streaming.

The inspector says Not served, but I expected a rule to match

Why: Attributes are not part of the console box, so a rule cannot match there.

Fix: Use Test these rules, or the inspect endpoint with attributes.

DEPENDENCY_BLOCKED with a note that a prerequisite flag is not ON for this person

Why: The flag depends on another flag that is off for this person, so the rollout step was skipped. Someone matched by a list, segment or rule would not have been held back.

Fix: Check the prerequisite flag for the same person, then fix it there. See Make one flag depend on another.

NO_IDENTIFIER

Why: The flag rolls out by account or device and you entered only a user, or the reverse.

Fix: Enter the kind shown in Roll out by, or change what the rollout counts. See Roll out a feature.

Good to know#

Reproduce before you edit

Run the check first, note the reason, then change one thing and run it again. A reason that moves from ROLLOUT_OUT to SEGMENT_MATCH tells you exactly which edit worked.
Does checking a person affect my metrics or analytics?
No. The Dashboard inspector is read-only and records nothing. Only evaluations made through the Evaluation API with an SDK key are counted.
Why does the same person land in a different bucket on another flag?
The bucket is computed from the identifier and the flag key together, so each flag spreads people differently. That keeps the same people from always being first in every rollout.
Can I check someone who is not in my app yet?
Yes. Enter any identifier. The inspector only needs strings, not a real user record.
Does the inspector use prerequisites and segments?
Yes. It loads the segments the flag selects and the prerequisite flags in the environment, and evaluates them the way an SDK would.