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

# Create Segments

> Learn how to create segments to define target audiences.

**Create Segments**

Learn how to create segments to define target audiences.

[Do this in the app →](/docs/capabilities/segments/create-segments.md)

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.

## 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.

## 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](/docs/reference/api/how-to-guides/flags/coordinate-segments.md) for more details.

## 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.

## 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](/docs/reference/api/how-to-guides/flags/target-with-criteria.md) for more sophisticated audience targeting
2. [Set up coordination](/docs/reference/api/how-to-guides/flags/coordinate-segments.md) to make segments mutually exclusive
3. [Create flag rules](/docs/reference/api/how-to-guides/flags/create-flag-rule.md) to assign variants to segments