Segments

A segment is a named, reusable audience, such as "beta testers" or "internal staff". You define it once and reference it from targeting rules. When you change the segment, every rule that references it uses the new definition.

Segments belong to the workspace. They are the same in every environment. A change to a segment applies to all environments at once.

How membership worksCopy Anchor Link

A user is a member of a segment when either of these is true:

• The user's context matches any of the segment's rules. Each rule has conditions combined with AND.
• The user's key is in the segment's member list.

The key attribute decides which context attribute Toggld compares with the member list. The default is targetingKey. For example, with the key attribute email, the member ana@example.com matches the context { "email": "ana@example.com" }. The attribute value must be a string.

Segment rules use the same conditions and operators as flag rules.

Create a segmentCopy Anchor Link

1. Open Segments and select New segment.
2. Enter a Name and a Key, such as beta-testers. Targeting rules reference the key, and you cannot change it later.
3. Optionally, add a Description and change the Key attribute.
4. Select Create segment.
5. On the segment page, add rules under Definition. Each rule reads "Members where all of these match". Select Save segment.
6. To add a member list, open Members. Add keys one at a time, or use Bulk import members.

The segment page shows Used by, the flags whose rules reference the segment in any environment.

Use a segment in a flagCopy Anchor Link

In a flag's targeting rule, select Segment and choose the segment. Choose in segment or not in segment. See Use segments in rules.

To target different audiences in each environment, reference different segments in each environment's rules. For example, use dev-testers in Development and premium-users in Production.

LimitsCopy Anchor Link

• A segment's member list can hold up to 5,000 members. A request that would exceed the limit fails with HTTP 422 and the error SegmentValidationError.
• Larger lists are not available yet.
• A segment cannot reference other segments.

Delete a segmentCopy Anchor Link

Toggld refuses to delete a segment while any flag rule references it, in any environment. The API returns HTTP 409 with the error SegmentReferenced and lists the flag keys in flagKeys. Remove the segment from those rules first, then delete it.

Manage segments with the APICopy Anchor Link

Segment endpoints require a management key. Because segments are shared, a management key from any environment changes the segment for every environment.

Create a segmentCopy Anchor Link

curl https://api.toggld.io/api/v1/segments \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "beta-testers",
    "name": "Beta testers",
    "keyAttribute": "targetingKey",
    "rules": [
      {
        "id": "internal",
        "conditions": [{ "attribute": "email", "operator": "endsWith", "value": "@example.com" }]
      }
    ]
  }'

Add and remove membersCopy Anchor Link

POST /api/v1/segments/{key}/members adds and removes members in one request. Both operations are idempotent: adding an existing member or removing a missing one changes nothing. Use this endpoint for bulk imports too.

curl https://api.toggld.io/api/v1/segments/beta-testers/members \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "add": ["user-123", "user-456"], "remove": ["user-789"] }'

List membersCopy Anchor Link

GET /api/v1/segments/{key}/members returns one page of members and the total count. Use query to filter by substring, and limit and offset to page. The default page size is 50 and the maximum is 200.

curl "https://api.toggld.io/api/v1/segments/beta-testers/members?query=user&limit=50&offset=0" \
  -H "Authorization: Bearer ffk_YOUR_MANAGEMENT_KEY"

Update a definitionCopy Anchor Link

PATCH /api/v1/segments/{key} changes the name, description, key attribute, or rules. To prevent lost updates, send the segment's current version as expectedVersion. If the segment changed after you read it, the API returns HTTP 409 with the error SegmentConflict.

Segments in local evaluation and flag filesCopy Anchor Link

Local evaluation and flag files download the segments that your flags reference, including their member lists. Segment membership then resolves inside your process with no extra request.

Toggld plans a separate list mode for very large segments that does not ship members to SDKs. It is not available yet. If a local or file-backed client finds such a segment, it logs a warning once and treats users who do not match the segment rules as non-members.