Segments

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.

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

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

envKey
required
string <string>

The environment key.

Responses
200

Segment collection response

401

Invalid access token

404

Invalid resource identifier

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

Create segment

Create a new user segment

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

envKey
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/{projKey}/{envKey}
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

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

envKey
required
string <string>

The environment key.

key
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/{projKey}/{envKey}/{key}
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/segments/:projKey/:envKey/:key \
  -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 JSON patch or JSON merge patch document. To learn more about semantic patches, read Updates.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

envKey
required
string <string>

The environment key.

key
required
string <string>

The user 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/{projKey}/{envKey}/{key}
Request samples
application/json
{
  • "patch": [
    ],
  • "comment": "string"
}
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.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

envKey
required
string <string>

The environment key.

key
required
string <string>

The user 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/{projKey}/{envKey}/{key}
Request samples
curl -i -X DELETE \
  https://app.launchdarkly.com/api/v2/segments/:projKey/:envKey/:key \
  -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

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

envKey
required
string <string>

The environment key.

key
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/{projKey}/{envKey}/{key}/users
Request samples
application/json
{
  • "included": {
    },
  • "excluded": {
    }
}
Response samples
application/json
{
  • "code": "invalid_request",
  • "message": "invalid request body"
}

Get Big Segment membership for user

Returns the membership status (included/excluded) for a given user in this segment. This operation does not support basic Segments.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

envKey
required
string <string>

The environment key.

key
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/{projKey}/{envKey}/{key}/users/{userKey}
Request samples
curl -i -X GET \
  https://app.launchdarkly.com/api/v2/segments/:projKey/:envKey/:key/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

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

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

Update expiring user targets for segment

Update the list of a segment's user targets that are scheduled for removal

Requires a semantic patch representation of the desired changes to the resource. To learn more about semantic patches, read Updates.

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.

Request
Security:
ApiKey (readwrite)
path Parameters
projKey
required
string <string>

The project key.

envKey
required
string <string>

The environment key.

segmentKey
required
string <string>

The user 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/{projKey}/{segmentKey}/expiring-user-targets/{envKey}
Request samples
application/json
{
  • "comment": "string",
  • "instructions": [
    ]
}
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalInstructions": 0,
  • "successfulInstructions": 0,
  • "failedInstructions": 0,
  • "errors": [
    ]
}