---
title: Segments
description: Build a reusable audience of an environment, point rules at it, and change it once for every flag that names it.
type: how-to
product: flags
summary: An audience one rule names and every flag follows, from creation to deletion
updated: 2026-09-28
order: 0
---

A ConfigSegment is a reusable audience of one environment: subjects listed by
id, and conditions over the evaluation context. It exists so that one audience
has one definition — the beta testers, or everyone on the new plan — and a flag
rule names it by id instead of repeating its conditions. This page creates one,
points a rule at it, and covers what changing and deleting one do.

## Create one

```bash
sylphx config config-segments create --parent orgs/acme/projects/shop/envs/production
```

The spec is the audience, and each field answers a different question:

<PropertyTable
	properties={[
		{
			name: 'included',
			type: 'string[]',
			description: 'Subjects always in the segment, by user_id or anonymous_id.',
		},
		{
			name: 'excluded',
			type: 'string[]',
			description: 'Subjects never in the segment, whatever else holds.',
		},
		{
			name: 'conditions',
			type: 'TargetingCondition[]',
			description: 'Conditions over the evaluation context; all must hold.',
		},
		{
			name: 'description',
			type: 'string',
			description: 'Who the segment is.',
		},
	]}
/>

The id is what a rule's IN_SEGMENT names, so it is part of the interface rather
than a detail. A segment lives under an environment, so the same audience in
staging and in production is two segments with two ids.

`included` and `excluded` are lists of subject ids, and they are the two fields
you reach for by hand: someone who has to be in a pilot is in `included`, and
someone who must never see it is in `excluded` however the conditions fall.
`conditions` is the part that scales — the comparisons over the evaluation
context that [targeting rules](/docs/flags/targeting) describes, all of which
must hold.

## Point a rule at it

A rule names a segment with the `in_segment` operator, and the opposite with
`not_in_segment`. Those two operators are the only conditions that need no
`attribute` of their own, because the segment is what they compare against. The
segment decides whether the subject is in the audience; the rule around it still
decides what value that audience gets, so the same segment serves a different
value in each flag that names it.

## Change it

```bash
sylphx config config-segments update orgs/acme/projects/shop/envs/production/config_segments/config-segment
```

An update writes the spec, the same call `create` took. Every flag naming the
segment follows the change — that is the whole point of the object: adding a
subject to the audience once reaches every rule that names it, rather than
editing the same conditions in each flag.

Create, update and delete answer an `Operation`, so the call returns before the
change has reached the environment. `status.conditions` reads Ready when it has.

## Delete it

Delete is refused while a flag names the segment, which keeps a live rule from
pointing at nothing. So the order is: remove the rule that names it first, or
empty the segment instead of removing it.

```bash
sylphx config config-segments delete orgs/acme/projects/shop/envs/production/config_segments/config-segment --yes
```

Delete is `destructive`, so the CLI asks before it runs and `--yes` answers in
advance; the API takes an `etag` that must match the current one. `--dry-run`
validates and prints the result without writing.

<RelatedDocs
	links={[
		{
			href: '/docs/flags/targeting',
			label: 'Targeting rules',
			description: 'The conditions a segment is built from, and the operators that name one.',
		},
		{
			href: '/docs/flags/changes',
			label: 'Change history',
			description: 'Every committed change to a segment, kept after it is deleted.',
		},
		{
			href: '/docs/api/config_segments',
			label: 'The config_segments collection',
			description: 'Every method, its scope and its examples.',
		},
	]}
/>