Skip to content
FlagSwiftDocs

Target a group with segments and rules

Describe an audience once, such as beta testers or customers on a plan, and reuse it across flags and environments.

Time
About 10 min
Who can do it
Anyone with segments.create or segments.update: Product manager, Developer, Release manager, Admin. Only an Admin can delete.
Where
Segments, then Flags > your flag > Targeting & rollout
You finish with
A reusable audience that one or more flags serve

What and why#

What it is#

A segment is a named audience. By default it belongs to your whole organization, so a flag in any project can use it; when you create it you can instead scope it to one project, and then only that project's flags can use it. It can list people, accounts and devices, hold attribute rules, and include other segments. A flag then names the segment in its targeting, and everyone in it is served the flag.

When to use it#

  • The same audience applies to several flags, such as beta-testers or enterprise-accounts.
  • The audience changes over time and you want to edit it in one place.
  • A list or rule would otherwise be pasted into the targeting of many flags.

How it works#

A person is in a segment when they appear in its users, accounts or devices lists, or match any one of its rules, or are in any segment it includes. Segments ship to server SDKs inside the configuration, so they are evaluated locally with the same engine. A flag that matches a segment returns SEGMENT_MATCH. Segments are checked after the flag's own lists and before its attribute rules and rollout, and a match is served on whatever the percentage says.

Before you start#

  • The segments.create permission to make one and segments.update to edit it. Product managers, Developers, Release managers and Admins have both. Only Admins have segments.delete. See Give people the right access.
  • Decide what identifies the audience: a list of people you know, or attributes your app sends such as plan, country or app version.
  • Make sure your SDK passes those attributes in the user context. A rule can only match what it receives. See Target by person, account, device and attribute.
  • Decide the scope: Whole organization (any project's flags can use it) or One project (only that project's flags can, and only that project receives it). You choose once, when you create it; it cannot be changed later.
  • Editing a segment changes every flag that uses it, in every project that can use it. You cannot delete a segment while a flag uses it; the error names the projects.

Walk through it#

  1. Create the segment

    Open Segments, choose New Segment. The page lists every segment of the organization with its scope (Organization, or the project it is scoped to) and where it is used; filter by scope next to the search box. Segments are shared by every environment of the projects that can use them.

    Fields in the New segment dialog
    FieldDescription
    Name*Up to 80 characters. Choose a name that describes the audience, not the flag it is for.
    Key*Up to 50 characters, lower case letters, numbers, hyphens and underscores, such as beta-testers. Flags refer to the segment by key, so it cannot be changed after you save.
    DescriptionUp to 500 characters. Optional.
    Scope*Whole organization (the default) or One project with a project picker. Fixed at creation: when you edit a segment the scope is shown but cannot be changed. Keys are unique across the organization either way. A project segment is deleted with its project.
    The New segment dialog, top part. In edit mode the Key is read only.
  2. List people, accounts and devices

    Under Users, Accounts and Devices enter one identifier per line (commas and spaces also separate them). Each title shows a live count. Blank entries and duplicates are dropped and each entry is trimmed.

    The three lists, with a live count in each title.
    • Each identifier can be up to 255 characters.
    • A segment holds up to 5,000 users, accounts and devices together.
    • Matching is exact and case-sensitive.
  3. Add rules for everyone else

    Under Rules, add conditions with an attribute name, an operator and a value. A person is in the segment when they match any rule, and every condition in one rule must hold. The operators are equals, contains and in (is one of), and they behave as described in Target by person, account, device and attribute.

    Rule limits
    LimitDescription
    Rules per segment20.
    Conditions per rule10, and a rule needs at least one.
    Attribute nameUp to 100 characters: letters, numbers and . _ : -.
    ValueUp to 255 characters. An is-one-of list holds at most 100 values.

    The dialog shows Can't save yet with the problem while a rule is incomplete.

    The Rules and Also includes sections at the bottom of the dialog.
  4. Include other segments (optional)

    If other segments exist, Also includes shows a checkbox for each. Everyone in a chosen segment is also in this one. A segment can include up to 10 others. It cannot include itself, two segments cannot include each other in a loop, and a chain may go at most 4 levels deep (a segment, then 4 more beneath it). Deeper membership would stop matching, so saving is refused.

  5. Save

    Choose Create Segment. When you edit an existing segment the button reads Save Changes and stays off until something changed.

    You should see. The segment appears in the list with its counts, such as 2 users, 0 accounts, 0 devices, 1 rule, and an Unused badge until a flag uses it.
  6. Use it from a flag

    Open Flags, choose the flag, open Targeting & rollout and pick the environment. In step 2, Segments, select the segment (each is a button that stays highlighted while chosen) and choose Save changes. A flag environment can use at most 20 segments. Do the same in each environment where the audience should get the flag.

    Step 2, Segments. Chosen segments are highlighted.

    Matching any segment is enough

    The flag does not read segments from top to bottom. It serves the flag when the person is in any of the selected segments, and the inspector names the first one that matches. Prerequisites and the rollout percentage do not hold back a person who matches a segment.

    Segments only grant the flag

    A segment can only turn the flag on for its members. To serve a different variant to an audience you need variant allocation, not a segment.
  7. Test it

    Open Check who gets this flag at the bottom of the tab, enter a User, Account or Device and choose Check. Try one person who should be in and one who should not. To try attributes, use the inspect endpoint below. Find out why someone got a result explains the answer.

    You should see. For a member you see Served, the reason SEGMENT_MATCH and segment: beta-testers.

Editing a segment changes every flag that uses it

The change applies to all environments at once, including production, and takes effect for people on their next evaluation. If a flag in production uses the segment, directly or through an included segment, only a role that may change production targeting can edit it. Developers and Product managers are refused with This segment is used by a flag in production, where your role cannot change targeting. Segment changes are not held for approval.

Do it with the API#

Dashboard endpoints authenticate with your signed-in session cookie (auth_session), not an API key. Replace PROJECT_ID with the project's id.

Create a segment

Needs segments.create. users, accounts, devices, rules and includes are optional.

Request
curl -s -X POST "https://flags.example.com/api/segments" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "key": "beta-testers",
    "name": "Beta testers",
    "users": ["user-123", "user-456"],
    "rules": [
      { "id": "pro-plans", "conditions": [{ "attribute": "plan", "operator": "in", "value": ["pro", "team"] }] }
    ]
  }'
201 Created
{
  "status": "success",
  "message": "Segment created successfully",
  "data": {
    "id": "6650d2a3b4c5d6e7f8a9b0c1",
    "key": "beta-testers",
    "name": "Beta testers",
    "description": "",
    "projectId": "PROJECT_ID",
    "users": ["user-123", "user-456"],
    "accounts": [],
    "devices": [],
    "rules": [{ "id": "pro-plans", "conditions": [{ "attribute": "plan", "operator": "in", "value": ["pro", "team"] }] }],
    "includes": [],
    "createdBy": "mustafa@example.com",
    "createdAt": "2026-10-03T09:12:44.000Z",
    "updatedAt": "2026-10-03T09:12:44.000Z",
    "usage": { "flags": 0, "segments": 0 }
  }
}

Use it on a flag

segments is the full list of segment keys for that environment and replaces what was there. The keys must be organization-wide segments or segments scoped to the flag's own project; a segment scoped to another project is refused with 400. Needs targeting.update in the environment.

Request
curl -s -X PATCH "https://flags.example.com/api/flags/$FLAG_ID/environments/production" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{"segments":["beta-testers"]}'

List every segment with GET /api/segments (each has projectId and projectName, null when organization-wide), or the ones a project's flags may use with GET /api/segments?projectId=PROJECT_ID, edit with PATCH /api/segments/{id} (lists you send replace the old ones) and delete with DELETE /api/segments/{id}. See the Segments API.

What to check#

  • A person on the explicit list matches even if they would not match the rules.
  • A person who matches no segment, list or rule falls through to the rollout for the environment.
  • The segment's badge on the Segments page reads Used by 1 flag once a flag selects it.
  • Editing the segment is recorded in the audit log as a segment update, with before and after counts.

If something goes wrong#

A segment with this key already exists

Why: Keys are unique across the organization, whatever the scope, and the key cannot be changed once saved.

Fix: Choose another key, or edit the existing segment.

This segment is used by 2 flags and 1 other segment. Remove it there first.

Why: A segment that a flag selects, or that another segment includes, cannot be deleted. Archived flags count.

Fix: Deselect it in each flag and uncheck it under Also includes in the other segment, then delete it. The Segments list shows how many flags use it.

Segments cannot include each other in a loop, or can include others at most 4 levels deep

Why: The include graph has a cycle or is longer than the engine follows.

Fix: Remove one of the includes so the chain is shorter and nothing includes itself, directly or through others.

Segment "x" is scoped to another project and cannot be used by this flag

Why: The segment was created for a different project. A flag can use organization-wide segments and segments scoped to its own project.

Fix: Pick another segment, or create an organization-wide (or this project's) segment for the audience.

An organization-wide segment can only include organization-wide segments

Why: Includes follow the scope: a segment that every project can use cannot depend on one that only one project has.

Fix: Include an organization-wide segment, or create the including segment scoped to the project instead.

A segment's scope cannot be changed after it is created

Why: Flags and includes were checked against the scope when they were saved.

Fix: Create a new segment with the scope you want, move the flags to it, then delete the old one.

A flag still shows (missing) beside a segment

Why: A segment key in the flag no longer exists (for example its project was deleted), so it matches nobody.

Fix: Select the missing entry again in the Segments step to remove it and save.

Saving a segment is refused for a Developer or Product manager

Why: A flag in production uses the segment and your role cannot change production targeting.

Fix: Ask a Release manager or an Admin to make the change.

A member is not served the flag

Why: The flag is off in that environment, the kill switch is on, the identifier differs in case or spacing, or the segment is not selected in that environment.

Fix: Check the person with Check who gets this flag and read the reason. See Find out why someone got a result.

Good to know#

Build from small segments

Make small segments such as staff and beta-testers, then include them in a larger one. You change a group in one place and the larger audience follows.
Is a segment shared between projects?
It is if it is organization-wide (the default): any project's flags can use it. A segment scoped to one project is used only by that project's flags, and only that project receives its definition. Either way it is shared across all environments.
Can I change a segment's scope later?
No. Choose it when you create the segment. To change it, create a new segment and move the flags over.
What happens to a project's segments when I delete the project?
Segments scoped to that project are deleted with it. Organization-wide segments stay.
How many segments can I have?
500 per organization. A flag environment can use up to 20 of them.
Can I rename a segment or change its key?
You can change the name, description and everything inside it. The key is fixed because flags refer to it.
Do segments reach client-side SDKs?
Client SDKs ask the server to evaluate, so segment definitions stay on the server. Server SDKs receive them in their configuration and evaluate locally.