Segments

Synced segments and larger list-based segments are an Enterprise feature

This section documents endpoints for rule-based, list-based, and synced segments.

A "big segment" is a segment that is either a synced segment, or a list-based segment with more than 15,000 entries that includes only one targeted context kind. LaunchDarkly uses different implementations for different types of segments so that all of your segments have good performance.

In the segments API, a big segment is indicated by the unbounded field being set to true.

These segments are available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Segments are groups of contexts that you can use to manage flag targeting behavior in bulk. LaunchDarkly supports:

  • rule-based segments, which let you target groups of contexts individually or by attribute,
  • list-based segments, which let you target individual contexts or uploaded lists of contexts, and
  • synced segments, which let you target groups of contexts backed by an external data store.

To learn more, read Segments.

The segments API allows you to list, create, modify, and delete segments programmatically.

You can find other APIs for working with big segments under Segments (beta) and Integrations (beta).

List segment memberships for context instance

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

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

Request Body schema: application/json
required
property name*
additional property
any
Responses
200

Context instance segment membership collection response

400

Invalid request

401

Invalid access token

404

Invalid resource identifier

post/api/v2/projects/{projectKey}/environments/{environmentKey}/segments/evaluate
Request samples
application/json
{
  • "address": {
    },
  • "jobFunction": "doctor",
  • "key": "context-key-123abc",
  • "kind": "user",
  • "name": "Sandy"
}
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

List segments

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.

Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

query Parameters
limit
integer <int64>

The number of segments to return. Defaults to 20.

offset
integer <int64>

Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query limit.

sort
string <string>

Accepts sorting order and fields. Fields can be comma separated. Possible fields are 'creationDate', 'name', 'lastModified'. Example: sort=name sort by names ascending or sort=-name,creationDate sort by names descending and creationDate ascending.

filter
string <string>

Accepts filter by kind, query, tags, unbounded, external, or included and excluded segment keys. To filter by kind or query, use the equals operator. To filter by tags, use the anyOf operator. Query is a 'fuzzy' search across segment key, name, and description. Example: filter=tags anyOf ['enterprise', 'beta'],query equals 'toggle' returns segments with 'toggle' in their key, name, or description that also have 'enterprise' or 'beta' as a tag. To filter by unbounded, use the equals operator. Example: filter=unbounded equals true. To filter by external, use the exists operator. Example: filter=external exists true. To exclude segments from results, use filter=excludedKeys anyOf ['segmentKey1', 'segmentKey2'].

Responses
200

Segment collection response

401

Invalid access token

404

Invalid resource identifier

get/api/v2/segments/{projectKey}/{environmentKey}
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalCount": 0
}
Create segment
Create a new segment.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
Request Body schema: application/json
required
name
required
string
A human-friendly name for the segment


 
key
required
string
A unique key used to reference the segment


 
description
string
A description of the segment's purpose


 
tags
Array of strings
Tags for the segment


 
unbounded
boolean
Whether to create a standard segment (false) or a big segment (true). Standard segments include rule-based and smaller list-based segments. Big segments include larger list-based segments and synced segments. Only use a big segment if you need to add more than 15,000 individual targets.


 
unboundedContextKind
string
For big segments, the targeted context kind.


 
Responses 
201
Segment response


400
Invalid request


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


429
Rate limited


post/api/v2/segments/{projectKey}/{environmentKey}
Request samples 
application/json
{
  • "name": "Example segment",
  • "key": "segment-key-123abc",
  • "description": "Bundle our sample customers together",
  • "tags": [
    ],
  • "unbounded": false,
  • "unboundedContextKind": "device"
}
Response samples 
application/json
{
  • "name": "Example segment",
  • "description": "Bundle our sample customers together",
  • "tags": [
    ],
  • "creationDate": 0,
  • "lastModifiedDate": 0,
  • "key": "segment-key-123abc",
  • "included": [
    ],
  • "excluded": [
    ],
  • "includedContexts": [
    ],
  • "excludedContexts": [
    ],
  • "_links": {
    },
  • "rules": [
    ],
  • "version": 1,
  • "deleted": false,
  • "_access": {
    },
  • "_flags": [
    ],
  • "unbounded": false,
  • "unboundedContextKind": "string",
  • "generation": 0,
  • "_unboundedMetadata": {
    },
  • "_external": "amplitude",
  • "_externalLink": "https://analytics.amplitude.com/org/1234/cohort/123abc",
  • "_importInProgress": false
}
Get 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.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Responses 
200
Segment response


401
Invalid access token


404
Invalid resource identifier


429
Rate limited


get/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}
Request samples 
Response samples 
application/json
{
  • "name": "Example segment",
  • "description": "Bundle our sample customers together",
  • "tags": [
    ],
  • "creationDate": 0,
  • "lastModifiedDate": 0,
  • "key": "segment-key-123abc",
  • "included": [
    ],
  • "excluded": [
    ],
  • "includedContexts": [
    ],
  • "excludedContexts": [
    ],
  • "_links": {
    },
  • "rules": [
    ],
  • "version": 1,
  • "deleted": false,
  • "_access": {
    },
  • "_flags": [
    ],
  • "unbounded": false,
  • "unboundedContextKind": "string",
  • "generation": 0,
  • "_unboundedMetadata": {
    },
  • "_external": "amplitude",
  • "_externalLink": "https://analytics.amplitude.com/org/1234/cohort/123abc",
  • "_importInProgress": false
}
Patch segment
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.



Click to expand instructions for updating segments


addIncludedTargets


Adds context keys to the individual context targets included in the segment for the specified contextKind. Returns an error if this causes the same context key to be both included and excluded.


Parameters


    

  • contextKind: The context kind the targets should be added to.
    • 

  • values: List of keys.
    • 



Here's an example:


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



addIncludedUsers


Adds user keys to the individual user targets included in the segment. Returns an error if this causes the same user key to be both included and excluded. If you are working with contexts, use addIncludedTargets instead of this instruction.


Parameters


    

  • values: List of user keys.
    • 



Here's an example:


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



addExcludedTargets


Adds context keys to the individual context targets excluded in the segment for the specified contextKind. Returns an error if this causes the same context key to be both included and excluded.


Parameters


    

  • contextKind: The context kind the targets should be added to.
    • 

  • values: List of keys.
    • 



Here's an example:


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



addExcludedUsers


Adds user keys to the individual user targets excluded from the segment. Returns an error if this causes the same user key to be both included and excluded. If you are working with contexts, use addExcludedTargets instead of this instruction.


Parameters


    

  • values: List of user keys.
    • 



Here's an example:


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



removeIncludedTargets


Removes context keys from the individual context targets included in the segment for the specified contextKind.


Parameters


    

  • contextKind: The context kind the targets should be removed from.
    • 

  • values: List of keys.
    • 



Here's an example:


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



removeIncludedUsers


Removes user keys from the individual user targets included in the segment. If you are working with contexts, use removeIncludedTargets instead of this instruction.


Parameters


    

  • values: List of user keys.
    • 



Here's an example:


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



removeExcludedTargets


Removes context keys from the individual context targets excluded from the segment for the specified contextKind.


Parameters


    

  • contextKind: The context kind the targets should be removed from.
    • 

  • values: List of keys.
    • 



Here's an example:


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



removeExcludedUsers


Removes user keys from the individual user targets excluded from the segment. If you are working with contexts, use removeExcludedTargets instead of this instruction.


Parameters


    

  • values: List of user keys.
    • 



Here's an example:


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



updateName


Updates the name of the segment.


Parameters


    

  • value: Name of the segment.
    • 



Here's an example:


{
  "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.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Request Body schema: application/json
required
required
Array of objects (JSONPatch) 
 
comment
string
Optional comment


 
Responses 
200
Segment response


400
Invalid request


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


409
Status conflict


429
Rate limited


patch/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}
Request samples 
application/json
{
  • "patch": [
    ]
}
Response samples 
application/json
{
  • "name": "Example segment",
  • "description": "Bundle our sample customers together",
  • "tags": [
    ],
  • "creationDate": 0,
  • "lastModifiedDate": 0,
  • "key": "segment-key-123abc",
  • "included": [
    ],
  • "excluded": [
    ],
  • "includedContexts": [
    ],
  • "excludedContexts": [
    ],
  • "_links": {
    },
  • "rules": [
    ],
  • "version": 1,
  • "deleted": false,
  • "_access": {
    },
  • "_flags": [
    ],
  • "unbounded": false,
  • "unboundedContextKind": "string",
  • "generation": 0,
  • "_unboundedMetadata": {
    },
  • "_external": "amplitude",
  • "_externalLink": "https://analytics.amplitude.com/org/1234/cohort/123abc",
  • "_importInProgress": false
}
Delete segment
Delete a segment.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Responses 
204
Action succeeded


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


409
Status conflict


429
Rate limited


delete/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}
Request samples 
Response samples 
application/json
{
  • "code": "unauthorized",
  • "message": "Invalid access token"
}
Update context targets on a big 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.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Request Body schema: application/json
required
object (SegmentUserList) 
 
object (SegmentUserList) 
 
Responses 
204
Action succeeded


400
Invalid request


401
Invalid access token


404
Invalid resource identifier


429
Rate limited


post/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}/contexts
Request samples 
application/json
{
  • "included": {
    },
  • "excluded": {
    }
}
Response samples 
application/json
{
  • "code": "invalid_request",
  • "message": "Invalid request body"
}
Get big segment membership for context
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.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
contextKey
required
string <string> 
The context key


 
Responses 
200
Segment membership for context response


400
Invalid request


401
Invalid access token


404
Invalid resource identifier


429
Rate limited


get/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}/contexts/{contextKey}
Request samples 
Response samples 
application/json
{
  • "userKey": "string",
  • "included": true,
  • "excluded": true
}
Update user context targets on a big segment
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.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Request Body schema: application/json
required
object (SegmentUserList) 
 
object (SegmentUserList) 
 
Responses 
204
Action succeeded


400
Invalid request


401
Invalid access token


404
Invalid resource identifier


429
Rate limited


post/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}/users
Request samples 
application/json
{
  • "included": {
    },
  • "excluded": {
    }
}
Response samples 
application/json
{
  • "code": "invalid_request",
  • "message": "Invalid request body"
}
Get big segment membership for 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 the membership status (included/excluded) for a given user in this big segment. This operation does not support standard segments.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
userKey
required
string <string> 
The user key


 
Responses 
200
Segment membership for user response


400
Invalid request


401
Invalid access token


404
Invalid resource identifier


429
Rate limited


get/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}/users/{userKey}
Request samples 
Response samples 
application/json
{
  • "userKey": "string",
  • "included": true,
  • "excluded": true
}
Get expiring targets for segment
Get a list of a segment's context targets that are scheduled for removal.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Responses 
200
Expiring context target response


401
Invalid access token


404
Invalid resource identifier


429
Rate limited


get/api/v2/segments/{projectKey}/{segmentKey}/expiring-targets/{environmentKey}
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}
Update expiring targets for segment
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.



Click to expand instructions for updating expiring context targets


addExpiringTarget


Schedules a date and time when LaunchDarkly will remove a context from segment targeting. The segment must already have the context as an individual target.


Parameters


    

  • targetType: The type of individual target for this context. Must be either included or excluded.
    • 

  • contextKey: The context key.
    • 

  • contextKind: The kind of context being targeted.
    • 

  • value: The date when the context should expire from the segment targeting, in Unix milliseconds.
    • 



Here's an example:


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



updateExpiringTarget


Updates the date and time when LaunchDarkly will remove a context from segment targeting.


Parameters


    

  • targetType: The type of individual target for this context. Must be either included or excluded.
    • 

  • contextKey: The context key.
    • 

  • contextKind: The kind of context being targeted.
    • 

  • value: The new date when the context should expire from the segment targeting, in Unix milliseconds.
    • 

  • version: (Optional) The version of the expiring target to update. If included, update will fail if version doesn't match current version of the expiring target.
    • 



Here's an example:


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



removeExpiringTarget


Removes the scheduled expiration for the context in the segment.


Parameters


    

  • targetType: The type of individual target for this context. Must be either included or excluded.
    • 

  • contextKey: The context key.
    • 

  • contextKind: The kind of context being targeted.
    • 



Here's an example:


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





Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Request Body schema: application/json
required
comment
string
Optional description of changes


 
required
Array of objects (patchSegmentExpiringTargetInstruction) 
Semantic patch instructions for the desired changes to the resource


 
Responses 
200
Expiring  target response


400
Invalid request


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


409
Status conflict


429
Rate limited


patch/api/v2/segments/{projectKey}/{segmentKey}/expiring-targets/{environmentKey}
Request samples 
application/json
{
  • "comment": "optional comment",
  • "instructions": [
    ]
}
Response samples 
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalInstructions": 0,
  • "successfulInstructions": 0,
  • "failedInstructions": 0,
  • "errors": [
    ]
}
Get expiring user targets for segment


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.


Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Responses 
200
Expiring user target response


401
Invalid access token


404
Invalid resource identifier


429
Rate limited


get/api/v2/segments/{projectKey}/{segmentKey}/expiring-user-targets/{environmentKey}
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}
Update expiring user targets for segment


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.



Click to expand instructions for updating expiring user targets


addExpireUserTargetDate


Schedules a date and time when LaunchDarkly will remove a user from segment targeting.


Parameters


    

  • targetType: A segment's target type, must be either included or excluded.
    • 

  • userKey: The user key.
    • 

  • value: The date when the user should expire from the segment targeting, in Unix milliseconds.
    • 



updateExpireUserTargetDate


Updates the date and time when LaunchDarkly will remove a user from segment targeting.


Parameters


    

  • targetType: A segment's target type, must be either included or excluded.
    • 

  • userKey: The user key.
    • 

  • value: The new date when the user should expire from the segment targeting, in Unix milliseconds.
    • 

  • version: The segment version.
    • 



removeExpireUserTargetDate


Removes the scheduled expiration for the user in the segment.


Parameters


    

  • targetType: A segment's target type, must be either included or excluded.
    • 

  • userKey: The user key.
    • 





Request 
path Parameters
projectKey
required
string <string> 
The project key


 
environmentKey
required
string <string> 
The environment key


 
segmentKey
required
string <string> 
The segment key


 
Request Body schema: application/json
required
comment
string
Optional description of changes


 
required
Array of objects (patchSegmentInstruction) 
Semantic patch instructions for the desired changes to the resource


 
Responses 
200
Expiring user target response


400
Invalid request


401
Invalid access token


403
Forbidden


404
Invalid resource identifier


409
Status conflict


429
Rate limited


patch/api/v2/segments/{projectKey}/{segmentKey}/expiring-user-targets/{environmentKey}
Request samples 
application/json
{
  • "comment": "optional comment",
  • "instructions": [
    ]
}
Response samples 
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalInstructions": 1,
  • "successfulInstructions": 1,
  • "failedInstructions": 0,
  • "errors": [
    ]
}
➔ Next to Segments (beta)