Segments

Big Segments is an add-on feature

This section documents endpoints for both standard segements and Big Segments. Big Segments is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Segments allow you to create targeting rules and lists of users that can be shared by one or more feature flags in an environment. Creating a segment is a lot like creating a flag. You can include individual users from a segment. You can also create targeting rules, same as those for flags, that include or exclude users based on attributes your application has provided about those users. Finally, you can explicitly exclude users that would otherwise be included by those rules. To learn more, read Building user segments.

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

List segments

Get a list of all user segments in the given project.

SecurityApiKey
Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

Responses
200

Segment collection response

401

Invalid access token

404

Invalid resource identifier

get/api/v2/segments/{projectKey}/{environmentKey}
Request samples
curl -i -X GET \
  'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{environmentKey}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Create segment

Create a new user segment.

SecurityApiKey
Request
path Parameters
projectKey
required
string <string>

The project key

environmentKey
required
string <string>

The environment key

Request Body schema: application/json
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
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": "string",
  • "key": "string",
  • "description": "string",
  • "tags": [
    ],
  • "unbounded": true
}
Response samples
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "creationDate": 0,
  • "key": "string",
  • "included": [
    ],
  • "excluded": [
    ],
  • "_links": {
    },
  • "rules": [
    ],
  • "version": 0,
  • "deleted": true,
  • "_access": {
    },
  • "_flags": [
    ],
  • "unbounded": true,
  • "generation": 0,
  • "_unboundedMetadata": {
    },
  • "_external": "string",
  • "_externalLink": "string",
  • "_importInProgress": true
}

Get segment

Get a single user segment by key.

SecurityApiKey
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
curl -i -X GET \
  'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "name": "string",
  • "description": "string",
  • "tags": [
    ],
  • "creationDate": 0,
  • "key": "string",
  • "included": [
    ],
  • "excluded": [
    ],
  • "_links": {
    },
  • "rules": [
    ],
  • "version": 0,
  • "deleted": true,
  • "_access": {
    },
  • "_flags": [
    ],
  • "unbounded": true,
  • "generation": 0,
  • "_unboundedMetadata": {
    },
  • "_external": "string",
  • "_externalLink": "string",
  • "_importInProgress": true
}

Patch segment

Update a user segment. The request body must be a valid semantic patch, JSON patch, or JSON merge patch.

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.

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.

Parameters
  • values: List of user keys.

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.

Parameters
  • values: List of user keys.

removeIncludedUsers

Removes user keys from the individual user targets included in the segment.

Parameters
  • values: List of user keys.

removeExcludedUsers

Removes user keys from the individual user targets excluded from the segment.

Parameters
  • values: List of user keys.

updateName

Updates the name of the segment.

Parameters
  • value: Name of the segment.

Using JSON patches on a segment

You can also use JSON patch. To learn more, read Updates using JSON patches.

For example, to update the description for a segment, 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>. Using /0 adds the new entry to the beginning 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": [{ "attribute": "email", "op": "endsWith", "values": [".edu"], "negate": false }]
      }
    }
  ]
}

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

SecurityApiKey
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
Array of objects (JSONPatch)
comment
string
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": "string",
  • "description": "string",
  • "tags": [
    ],
  • "creationDate": 0,
  • "key": "string",
  • "included": [
    ],
  • "excluded": [
    ],
  • "_links": {
    },
  • "rules": [
    ],
  • "version": 0,
  • "deleted": true,
  • "_access": {
    },
  • "_flags": [
    ],
  • "unbounded": true,
  • "generation": 0,
  • "_unboundedMetadata": {
    },
  • "_external": "string",
  • "_externalLink": "string",
  • "_importInProgress": true
}

Delete segment

Delete a user segment.

SecurityApiKey
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
curl -i -X DELETE \
  'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "code": "unauthorized",
  • "message": "invalid key"
}

Update targets on a Big Segment

Update targets included or excluded in a Big Segment.

SecurityApiKey
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
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

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

SecurityApiKey
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
curl -i -X GET \
  'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{environmentKey}/{segmentKey}/users/{userKey}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "userKey": "string",
  • "included": true,
  • "excluded": true
}

Get expiring user targets for segment

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

SecurityApiKey
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
curl -i -X GET \
  'https://app.launchdarkly.com/api/v2/segments/{projectKey}/{segmentKey}/expiring-user-targets/{environmentKey}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    }
}

Update expiring user targets for segment

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 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.
SecurityApiKey
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
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": "string",
  • "instructions": [
    ]
}
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalInstructions": 0,
  • "successfulInstructions": 0,
  • "failedInstructions": 0,
  • "errors": [
    ]
}