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
Python
Node.js

curl -i -X GET \
  https://app.launchdarkly.com/api/v2/segments/:projKey/:envKey \
  -H 'Authorization: YOUR_API_KEY_HERE'

Response samples

application/json

{"items": [{"name": "string",
"description": "string",
"tags": ["string"
],
"creationDate": 0,
"key": "string",
"included": ["string"
],
"excluded": ["string"
],
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"rules": [{"_id": "string",
"clauses": [{"_id": "string",
"attribute": "string",
"op": "string",
"values": [null
],
"negate": true
}
],
"weight": 0,
"bucketBy": "string"
}
],
"version": 0,
"deleted": true,
"_access": {"denied": [{"action": "string",
"reason": {"resources": [null
],
"notResources": [null
],
"actions": [null
],
"notActions": [null
],
"effect": "string",
"role_name": "string"
}
}
]
},
"_flags": [{"name": "string",
"key": "string",
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"_site": {"href": "string",
"type": "string"
}
}
],
"unbounded": true,
"generation": 0,
"_unboundedMetadata": {"envId": "string",
"segmentId": "string",
"version": 0,
"includedCount": 0,
"excludedCount": 0,
"deleted": true
},
"_external": "string",
"_externalLink": "string",
"_importInProgress": true
}
],
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
}
}

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

Payload
curl
Python
Node.js

application/json

{"name": "string",
"key": "string",
"description": "string",
"tags": ["ops"
],
"unbounded": true
}

Response samples

application/json

{"name": "string",
"description": "string",
"tags": ["string"
],
"creationDate": 0,
"key": "string",
"included": ["string"
],
"excluded": ["string"
],
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"rules": [{"_id": "string",
"clauses": [{"_id": "string",
"attribute": "string",
"op": "string",
"values": [null
],
"negate": true
}
],
"weight": 0,
"bucketBy": "string"
}
],
"version": 0,
"deleted": true,
"_access": {"denied": [{"action": "string",
"reason": {"resources": ["string"
],
"notResources": ["string"
],
"actions": ["string"
],
"notActions": ["string"
],
"effect": "string",
"role_name": "string"
}
}
]
},
"_flags": [{"name": "string",
"key": "string",
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"_site": {"href": "string",
"type": "string"
}
}
],
"unbounded": true,
"generation": 0,
"_unboundedMetadata": {"envId": "string",
"segmentId": "string",
"version": 0,
"includedCount": 0,
"excludedCount": 0,
"deleted": true
},
"_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
Python
Node.js

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": ["string"
],
"creationDate": 0,
"key": "string",
"included": ["string"
],
"excluded": ["string"
],
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"rules": [{"_id": "string",
"clauses": [{"_id": "string",
"attribute": "string",
"op": "string",
"values": [null
],
"negate": true
}
],
"weight": 0,
"bucketBy": "string"
}
],
"version": 0,
"deleted": true,
"_access": {"denied": [{"action": "string",
"reason": {"resources": ["string"
],
"notResources": ["string"
],
"actions": ["string"
],
"notActions": ["string"
],
"effect": "string",
"role_name": "string"
}
}
]
},
"_flags": [{"name": "string",
"key": "string",
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"_site": {"href": "string",
"type": "string"
}
}
],
"unbounded": true,
"generation": 0,
"_unboundedMetadata": {"envId": "string",
"segmentId": "string",
"version": 0,
"includedCount": 0,
"excludedCount": 0,
"deleted": true
},
"_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

Payload
curl
Python
Node.js

application/json

{"patch": [{"op": "replace",
"path": "/biscuits",
"value": "Chocolate Digestive"
}
],
"comment": "string"
}

Response samples

application/json

{"name": "string",
"description": "string",
"tags": ["string"
],
"creationDate": 0,
"key": "string",
"included": ["string"
],
"excluded": ["string"
],
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"rules": [{"_id": "string",
"clauses": [{"_id": "string",
"attribute": "string",
"op": "string",
"values": [null
],
"negate": true
}
],
"weight": 0,
"bucketBy": "string"
}
],
"version": 0,
"deleted": true,
"_access": {"denied": [{"action": "string",
"reason": {"resources": ["string"
],
"notResources": ["string"
],
"actions": ["string"
],
"notActions": ["string"
],
"effect": "string",
"role_name": "string"
}
}
]
},
"_flags": [{"name": "string",
"key": "string",
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"_site": {"href": "string",
"type": "string"
}
}
],
"unbounded": true,
"generation": 0,
"_unboundedMetadata": {"envId": "string",
"segmentId": "string",
"version": 0,
"includedCount": 0,
"excludedCount": 0,
"deleted": true
},
"_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
Python
Node.js

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

Payload
curl
Python
Node.js

application/json

{"included": {"add": ["string"
],
"remove": ["string"
]
},
"excluded": {"add": ["string"
],
"remove": ["string"
]
}
}

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
Python
Node.js

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
Python
Node.js

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": [{"_id": "string",
"_version": 0,
"expirationDate": 0,
"userKey": "string",
"targetType": "string",
"variationId": "string",
"_resourceId": {"kind": "string",
"projectKey": "string",
"environmentKey": "string",
"flagKey": "string",
"key": "string"
}
}
],
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
}
}

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

Payload
curl
Python
Node.js

application/json

{"comment": "string",
"instructions": [{"kind": "updateExpireUserTargetDate",
"targetType": "included",
"userKey": "userKey",
"value": 1587582000000,
"version": 0
}
]
}

Response samples

application/json

{"items": [{"_id": "string",
"_version": 0,
"expirationDate": 0,
"userKey": "string",
"targetType": "string",
"variationId": "string",
"_resourceId": {"kind": "string",
"projectKey": "string",
"environmentKey": "string",
"flagKey": "string",
"key": "string"
}
}
],
"_links": {"property1": {"href": "string",
"type": "string"
},
"property2": {"href": "string",
"type": "string"
}
},
"totalInstructions": 0,
"successfulInstructions": 0,
"failedInstructions": 0,
"errors": [{"instructionIndex": 0,
"message": "string"
}
]
}

➔ Next to Teams (beta)