Segments

For a given context instance with attributes, get membership details for all segments. In the request body, pass in the context instance.

Get a list of all segments in the given project.

Segments can be rule-based, list-based, or synced. Big segments include larger list-based segments and synced segments. Some fields in the response only apply to big segments.

Filtering segments

The filter parameter supports the following operators: equals, anyOf, and exists.

You can also combine filters in the following ways:

• Use a comma (,) as an AND operator
• Use a vertical bar (|) as an OR operator
• Use parentheses (()) to group filters

Supported fields and operators

You can only filter certain fields in segments when using the filter parameter. Additionally, you can only filter some fields with certain operators.

When you search for segments, the filter parameter supports the following fields and operators:

Here are a few examples:

• The filter ?filter=tags anyOf ["enterprise", "beta"],query equals "toggle" matches segments with "toggle" in their key, name, or description that also have "enterprise" or "beta" as a tag.
• The filter ?filter=excludedKeys anyOf ["segmentKey1", "segmentKey2"] excludes the segments with those keys from the results.
• The filter ?filter=unbounded equals true matches larger list-based segments and synced segments.

The documented values for filter query parameters are prior to URL encoding. For example, the [ in ?filter=tags anyOf ["enterprise", "beta"] must be encoded to %5B.

Create a new segment.

Get a single segment by key.

Segments can be rule-based, list-based, or synced. Big segments include larger list-based segments and synced segments. Some fields in the response only apply to big segments.

Update a segment. The request body must be a valid semantic patch, JSON patch, or JSON merge patch. To learn more the different formats, read Updates.

Using semantic patches on a segment

To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch to your Content-Type header. To learn more, read Updates using semantic patch.

The body of a semantic patch request for updating segments requires an environmentKey in addition to instructions and an optional comment. The body of the request takes the following properties:

• comment (string): (Optional) A description of the update.
• environmentKey (string): (Required) The key of the LaunchDarkly environment.
• instructions (array): (Required) A list of actions the update should perform. Each action in the list must be an object with a kind property that indicates the instruction. If the action requires parameters, you must include those parameters as additional fields in the object.

Instructions

Semantic patch requests support the following kind instructions for updating segments.

{
  "instructions": [{
    "kind": "addIncludedTargets",
    "contextKind": "org",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

{
  "instructions": [{
    "kind": "addIncludedUsers",
    "values": [ "user-key-123abc", "user-key-456def" ]
  }]
}

{
  "instructions": [{
    "kind": "addExcludedTargets",
    "contextKind": "org",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

{
  "instructions": [{
    "kind": "addExcludedUsers",
    "values": [ "user-key-123abc", "user-key-456def" ]
  }]
}

{
  "instructions": [{
    "kind": "removeIncludedTargets",
    "contextKind": "org",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

{
  "instructions": [{
    "kind": "removeIncludedUsers",
    "values": [ "user-key-123abc", "user-key-456def" ]
  }]
}

{
  "instructions": [{
    "kind": "removeExcludedTargets",
    "contextKind": "org",
    "values": [ "org-key-123abc", "org-key-456def" ]
  }]
}

{
  "instructions": [{
    "kind": "removeExcludedUsers",
    "values": [ "user-key-123abc", "user-key-456def" ]
  }]
}

{
  "instructions": [{
    "kind": "updateName",
    "value": "Updated segment name"
  }]
}

Using JSON patches on a segment

If you do not include the header described above, you can use a JSON patch or JSON merge patch representation of the desired changes.

For example, to update the description for a segment with a JSON patch, use the following request body:

{
  "patch": [
    {
      "op": "replace",
      "path": "/description",
      "value": "new description"
    }
  ]
}

To update fields in the segment that are arrays, set the path to the name of the field and then append /<array index>. Use /0 to add the new entry to the beginning of the array. Use /- to add the new entry to the end of the array.

For example, to add a rule to a segment, use the following request body:

{
  "patch":[
    {
      "op": "add",
      "path": "/rules/0",
      "value": {
        "clauses": [{ "contextKind": "user", "attribute": "email", "op": "endsWith", "values": [".edu"], "negate": false }]
      }
    }
  ]
}

To add or remove targets from segments, we recommend using semantic patch. Semantic patch for segments includes specific instructions for adding and removing both included and excluded targets.

Delete a segment.

Update context targets included or excluded in a big segment. Big segments include larger list-based segments and synced segments. This operation does not support standard segments.

Get the membership status (included/excluded) for a given context in this big segment. Big segments include larger list-based segments and synced segments. This operation does not support standard segments.

Update user context targets included or excluded in a big segment. Big segments include larger list-based segments and synced segments. This operation does not support standard segments.

Contexts are now available

After you have upgraded your LaunchDarkly SDK to use contexts instead of users, you should use Get expiring targets for segment instead of this endpoint. To learn more, read Contexts.

Get the membership status (included/excluded) for a given user in this big segment. This operation does not support standard segments.

Get a list of a segment's context targets that are scheduled for removal.

Update expiring context targets for a segment. Updating a context target expiration uses the semantic patch format.

To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch to your Content-Type header. To learn more, read Updates using semantic patch.

If the request is well-formed but any of its instructions failed to process, this operation returns status code 200. In this case, the response errors array will be non-empty.

Instructions

Semantic patch requests support the following kind instructions for updating expiring context targets.

{
  "instructions": [{
    "kind": "addExpiringTarget",
    "targetType": "included",
    "contextKey": "user-key-123abc",
    "contextKind": "user",
    "value": 1754092860000
  }]
}

{
  "instructions": [{
    "kind": "updateExpiringTarget",
    "targetType": "included",
    "contextKey": "user-key-123abc",
    "contextKind": "user",
    "value": 1754179260000
  }]
}

{
  "instructions": [{
    "kind": "removeExpiringTarget",
    "targetType": "included",
    "contextKey": "user-key-123abc",
    "contextKind": "user",
  }]
}

Contexts are now available

After you have upgraded your LaunchDarkly SDK to use contexts instead of users, you should use Get expiring targets for segment instead of this endpoint. To learn more, read Contexts.

Get a list of a segment's user targets that are scheduled for removal.

Contexts are now available

After you have upgraded your LaunchDarkly SDK to use contexts instead of users, you should use Update expiring targets for segment instead of this endpoint. To learn more, read Contexts.

Update expiring user targets for a segment. Updating a user target expiration uses the semantic patch format.

To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch to your Content-Type header. To learn more, read Updates using semantic patch.

If the request is well-formed but any of its instructions failed to process, this operation returns status code 200. In this case, the response errors array will be non-empty.

Instructions

Semantic patch requests support the following kind instructions for updating expiring user targets.