Segments

A segment is a named set of users, such as "Beta testers" or "Enterprise customers", defined once in a project and used by the targeting rules of any config in that project. Instead of copying the same conditions into every flag, a rule says "the context is in Beta testers". When the definition of a beta tester changes, you edit the segment, and every config that uses it follows.

Segments are available on Free and Pay as you go, with the same limits.

Who is in a segment

A segment holds one or more condition groups. A context is in the segment when any one of its groups matches, and a group matches when every condition in it matches. Inside a group conditions combine with AND, and across groups with OR.

For example, a "Beta testers" segment with two groups:

• Group 1: the /email trait ends with @acme.com
• Group 2: the /betaOptIn trait equals true, AND the app version is at least 2.0.0

Everyone at Acme is a beta tester, and so is anyone outside Acme who opted in on version 2 or later of the app.

The conditions in a group are the same attribute conditions that targeting rules use: the identifier, the name, a trait, the app name, or the app version, with the same operators. See Targeting Rules.

A segment cannot use another segment, and it holds no percentages. To roll something out to a percentage of a segment, use a percentage rollout in the config's targeting rules.

Name and key

• The name is how the segment shows in the dashboard and in audit logs. It can be up to 150 characters long.
• The key identifies the segment in the Admin API, Terraform, and the MCP server. It must be unique within the project and follows the same rules as a config key. While you create a segment, the key follows the name until you edit it.

Both can be changed at any time. Targeting rules refer to a segment by its id, not its key, so renaming a segment does not affect what your applications receive.

Environment overrides

The groups you define for a segment are its project definition, and every environment uses it by default. An environment can have an environment override instead: its own complete set of condition groups, used in that environment in place of the project definition. An override replaces the project definition as a whole; nothing is merged.

For example, Production can use the project definition of "Beta testers", while Staging overrides it with two named QA accounts.

Removing an override returns the environment to the project definition. A new environment starts on the project definition, and deleting an environment deletes its overrides.

Creating and editing a segment

Open a project and select Segments in the sidebar. The list shows each segment's name and key, how many configs use it in their targeting rules (Used by, with the configs and their environments when you hover the count), the environments that override it, and when it was last updated. Create Segment opens the form for a new segment.

On a segment's page, the scope selector chooses what you are editing:

• Project definition: the name, the key, and the groups every environment without an override uses.
• An environment that uses the project definition: its groups are shown read-only. Override in the environment copies them into an override that you can edit and save.
• An environment with an override: the override's groups. Reset to project definition removes the override.

Each scope is saved on its own. In a group, AND adds a condition; below the groups, OR add a condition group adds a group.

Viewers, operators, developers, admins, and owners can see segments. Operators, developers, admins, and owners can edit them and their environment overrides. Developers, admins, and owners can also create and delete them.

The Audit Log tab lists every change to the segment, with who made it, from where (the dashboard, the Admin API, Terraform, OpenTofu, or MCP), and before and after values. A change to an environment override names the environment.

Saving changes that reach live environments

A segment edit takes effect right away in every config that uses the segment, without saving those configs. So when a save changes the segment in a live environment where configs use it, ConfigDirector asks you to confirm, and lists those environments and configs.

Saving the project definition changes every environment without an override, and saving or resetting an override changes its own environment. A save that leaves the segment as it was in every live environment where configs use it, such as a rename, does not ask for confirmation.

Testing a segment

Test segment on the segment's page checks whether a context is in the segment. Pick an existing context or describe a custom one, the same way as in the targeting rules tester. The result says whether the context is in the segment and which group matched, each group is marked as matched or not, and each condition shows the value the context had.

The tester evaluates the groups as they are on the page, saved or not, in the scope you selected. With an environment selected, it picks contexts from that environment. With the project definition selected, choose the environment to pick contexts from.

Using a segment in targeting rules

On a config's Targeting Rules tab:

• AND on a conditional rule opens a menu with Attribute condition and Segment condition.
• The add rule menu has Add segment rule, a conditional rule that starts with a segment condition.
• A segment condition reads is in or is not in, followed by the segment, which you can search by name or key.

A segment condition is combined with the rule's other conditions by AND, like any other condition. For example, "context is in Beta testers AND the /country trait is one of US" matches beta testers in the US. A rule can hold up to 10 segment conditions.

In each environment, a segment condition uses the segment's definition for that environment: its override if it has one, otherwise the project definition.

The targeting rules tester shows, for each segment condition, whether the context is in the segment and which group matched. The config's audit log shows a segment condition by the segment's name and key, for example IF context is in segment Beta testers (beta-testers).

Editing a segment writes an entry to the segment's audit log only. The configs that use it keep their rules as they are, and their audit logs do not change.

Segment membership of a context

The page of a context (Contexts, then a context) lists every segment in the project and whether the context is in it, in the context's environment. For a context in a segment, it shows the group that matched, and a segment overridden in that environment is marked Override. A segment's name opens it on that environment's scope, so the group numbers match.

Contexts do not record the app name or the app version, so a segment that tests either is evaluated without them and marked App not known.

Deleting a segment

Delete Segment at the bottom of a segment's page deletes its project definition and every environment override. A segment cannot be deleted while the targeting rules of any config use it, in any environment. The dialog lists those configs and their environments, so you can remove the segment conditions first.

Archived configs are not counted. An archived config whose targeting rules use a deleted segment can no longer be restored.

Server SDK versions

Client SDKs receive values that ConfigDirector has already evaluated, segments included, so every client SDK version works with segments.

Server SDKs evaluate targeting rules themselves, so they need a version that understands segments:

An older server SDK is never sent a rule that contains a segment condition. For that SDK, the rule is skipped and the next rule applies, so the context gets the value of a later rule or the default targeting rule value. Keep this in mind for a rule that excludes a segment, such as "context is in Blocked users, serve false" above a rule that serves true to everyone: an older SDK skips the exclusion and serves true to blocked users too. ConfigDirector tells you when an older SDK is affected:

• The SDK cannot evaluate segments alert names the environment, the SDK version, and the SDK keys it connects with.
• Saving targeting rules that use a segment lists the server SDK versions that cannot evaluate segments and connected to that environment in the last 7 days, before the rules are saved. When saving a segment asks for confirmation, the confirmation lists them too.

Limits

The limits apply to the dashboard, the Admin API, Terraform, and the MCP server alike.

Managing segments as code

Segments can be managed through the Admin API, the Terraform provider, and the MCP server. Each needs an API token with the Segments: Read permission to read segments, Segments: Create to create them, Segments: Update to change them, and Segments: Delete to delete them.