Skip to main content

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.

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
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: 
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: 
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: 
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"
    }
  }'
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: 
curl -X POST "https://flags.confidence.dev/v1/segments/sweden-10pct:allocate" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
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.

​
Get a Segment

To retrieve a segment’s configuration: 
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: 
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"
      }
    }
  }'
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: 
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 for more sophisticated audience targeting
  2. Set up coordination to make segments mutually exclusive
  3. Create flag rules to assign variants to segments