> ## Documentation Index
> Fetch the complete documentation index at: https://confidence.spotify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Segments

> Learn how to create segments to define target audiences.

export const HowToSchema = ({name, description, steps = []}) => {
  const schema = {
    "@context": "https://schema.org",
    "@type": "HowTo",
    name,
    description
  };
  if (steps.length > 0) {
    schema.step = steps.map((s, i) => ({
      "@type": "HowToStep",
      position: i + 1,
      name: typeof s === "string" ? s : s.name,
      text: typeof s === "string" ? s : s.text || s.name
    }));
  }
  return <script type="application/ld+json" dangerouslySetInnerHTML={{
    __html: JSON.stringify(schema)
  }} />;
};

<HowToSchema
  name="Create Segments"
  description="Learn how to create segments to define target audiences."
  steps={[
{
  name: "Create a Basic Segment",
  text: "To create a segment that targets 100% of all users:",
},
{
  name: "Create a Segment with Targeting",
  text: "To create a segment that targets users from Sweden with 10% allocation:",
},
{
  name: "Set the Randomization Unit",
  text: 'By default, Confidence randomizes based on the targeting_key field in the evaluation context. You can specify a different field using targetingKeySelector: If the randomization field is missing from the evaluation context or is null, the segment doesn\'t match. The empty string ("") is a valid value for randomization.',
},
{
  name: "Allocate a Segment",
  text: "Segments start in an UNALLOCATED state. To use a segment in a flag rule, you must first allocate it: When coordinating with other segments, the allocation operation may fail if there's not enough space to make the segment mutually exclusive with overlapping segments. See Coordinate Segments for more details.",
},
{ name: "Get a Segment", text: "To retrieve a segment's configuration:" },
{
  name: "Update a Segment",
  text: "You can update a segment's targeting or allocation using the PATCH endpoint: Updating an allocated segment may require re-allocating it. Make changes carefully to avoid disrupting active experiments.",
},
{
  name: "Archive a Segment",
  text: "When a segment is no longer needed, archive it: You can no longer use archived segments in new rules, but existing rules continue to work.",
},
]}
/>

A segment is a cohort of users. Targeting and allocation define the cohort:

* **Targeting**: A set of criteria that filter users based on attributes
* **Allocation**: What percentage (0% to 100%) of the targeted users should be in the segment

<Note>
  Confidence makes no assumptions about the entity that you target or randomize on. Usually, the entity is a type of user (represented by an identifier). Because of this, the examples on this page involve users. Your unit could be something else.
</Note>

## Create a Basic Segment

To create a segment that targets 100% of all users:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=all-users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "All Users",
    "targeting": {},
    "allocation": {
      "proportion": {
        "value": "1.0"
      }
    }
  }'
```

## Create a Segment with Targeting

To create a segment that targets users from Sweden with 10% allocation:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=sweden-10pct" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "10% of users from Sweden",
    "targeting": {
      "criteria": {
        "sweden": {
          "attribute": {
            "attributeName": "country",
            "eqRule": {
              "value": {
                "stringValue": "SE"
              }
            }
          }
        }
      },
      "expression": {
        "ref": "sweden"
      }
    },
    "allocation": {
      "proportion": {
        "value": "0.1"
      }
    }
  }'
```

## Set the Randomization Unit

By default, Confidence randomizes based on the `targeting_key` field in the evaluation context. You can specify a different field using `targetingKeySelector`:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=device-based" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Device-based segment",
    "targeting": {},
    "allocation": {
      "proportion": {
        "value": "0.5"
      },
      "targetingKeySelector": "device_id"
    }
  }'
```

<Note>
  If the randomization field is missing from the evaluation context or is `null`, the segment doesn't match. The empty string (`""`) is a valid value for randomization.
</Note>

## Allocate a Segment

Segments start in an `UNALLOCATED` state. To use a segment in a flag rule, you must first allocate it:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/segments/sweden-10pct:allocate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

<Note>
  When coordinating with other segments, the allocation operation may fail if there's not enough space to make the segment mutually exclusive with overlapping segments. See [Coordinate Segments](./coordinate-segments) for more details.
</Note>

## Get a Segment

To retrieve a segment's configuration:

```bash theme={null}
curl -X GET "https://flags.confidence.dev/v1/segments/sweden-10pct" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Update a Segment

You can update a segment's targeting or allocation using the PATCH endpoint:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/segments/sweden-10pct?updateMask=allocation.proportion" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allocation": {
      "proportion": {
        "value": "0.2"
      }
    }
  }'
```

<Warning>
  Updating an allocated segment may require re-allocating it. Make changes carefully to avoid disrupting active experiments.
</Warning>

## Archive a Segment

When a segment is no longer needed, archive it:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/segments/sweden-10pct:archive" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

You can no longer use archived segments in new rules, but existing rules continue to work.

## Next Steps

After creating segments:

1. [Add targeting criteria](./target-with-criteria) for more sophisticated audience targeting
2. [Set up coordination](./coordinate-segments) to make segments mutually exclusive
3. [Create flag rules](./create-flag-rule) to assign variants to segments