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

# Coordinate Segments

> Learn how to make segments mutually exclusive using coordination tags.

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="Coordinate Segments"
  description="Learn how to make segments mutually exclusive using coordination tags."
  steps={[
{
  name: "Set Up Basic Coordination",
  text: "Create segments that exclude each other using matching tags: Create a second segment with the same coordination: These segments are now mutually exclusive—no user can be in both.",
},
{
  name: "Coordinate Across Multiple Groups",
  text: "Exclude a segment from multiple coordination groups: This segment doesn't overlap with any segment that has search, ranking, or mixer as exclusivity tags.",
},
{
  name: "Update Coordination Tags",
  text: "Change coordination tags on an existing segment: Changing coordination tags on an allocated segment may require re-allocating it, which can affect which users are in the segment.",
},
{
  name: "Allocate with Coordination",
  text: "Allocate a segment with coordination tags: If successful, the segment is allocated and guaranteed to be mutually exclusive with coordinating segments. If allocation fails due to insufficient space:",
},
{
  name: "Check Available Space",
  text: "List all segments to check available space in a coordination group: Filter the results for segments with overlapping coordination tags and sum their allocation proportions to see how much space the segments use.",
},
]}
/>

Use coordination to make segments mutually exclusive, ensuring users can only be in one experiment at a time.

<Tip>
  See [Coordination](../../flags/segments-reference#coordination) in the reference for details on how coordination works, common patterns, and best practices.
</Tip>

## Set Up Basic Coordination

Create segments that exclude each other using matching tags:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=ranking-exp-1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Ranking Experiment 1",
    "targeting": {},
    "allocation": {
      "proportion": {"value": "0.1"},
      "exclusivityTags": ["ranking"],
      "exclusiveTo": ["ranking"]
    }
  }'
```

Create a second segment with the same coordination:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=ranking-exp-2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Ranking Experiment 2",
    "targeting": {},
    "allocation": {
      "proportion": {"value": "0.1"},
      "exclusivityTags": ["ranking"],
      "exclusiveTo": ["ranking"]
    }
  }'
```

These segments are now mutually exclusive—no user can be in both.

## Coordinate Across Multiple Groups

Exclude a segment from multiple coordination groups:

```bash theme={null}
curl -X POST "https://flags.confidence.dev/v1/segments?segmentId=mixed-experiment" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Mixed Experiment",
    "targeting": {},
    "allocation": {
      "proportion": {"value": "0.05"},
      "exclusivityTags": ["search"],
      "exclusiveTo": ["search", "ranking", "mixer"]
    }
  }'
```

This segment doesn't overlap with any segment that has `search`, `ranking`, or `mixer` as exclusivity tags.

## Update Coordination Tags

Change coordination tags on an existing segment:

```bash theme={null}
curl -X PATCH "https://flags.confidence.dev/v1/segments/ranking-exp-1?updateMask=allocation.exclusivityTags,allocation.exclusiveTo" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allocation": {
      "exclusivityTags": ["ranking", "search"],
      "exclusiveTo": ["ranking", "search", "mixer"]
    }
  }'
```

<Warning>
  Changing coordination tags on an allocated segment may require re-allocating it, which can affect which users are in the segment.
</Warning>

## Allocate with Coordination

Allocate a segment with coordination tags:

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

If successful, the segment is allocated and guaranteed to be mutually exclusive with coordinating segments.

If allocation fails due to insufficient space:

* Reduce the allocation proportion
* Archive some existing segments
* Change coordination tags

## Check Available Space

List all segments to check available space in a coordination group:

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

Filter the results for segments with overlapping coordination tags and sum their allocation proportions to see how much space the segments use.

## Next Steps

After setting up coordination:

1. [Create flag rules](./create-flag-rule) to use your coordinated segments
2. [Allocate segments](./create-segment#allocate-a-segment) to activate them
3. [Resolve flags](./resolve-flags) to test your coordination logic